ModernAuth
Any application where you enter the username and password directly into it is considered basic authentication, and it's not really something that the Cyber Security folks typically like to see when the app is visible to the outside world. While most openDCIM installations are set for internal only, there is still a push to move everything to modern authentication. Just what is modern authentication? It's a workflow where you, as a user, go to visit a website, which we call a Service Provider (SP). The SP needs to know who you are, but why should it be the authority, especially if it is a third-party application? Instead, the SP needs to know about an Identity Provider (IdP), which may be your corporate system, or it could even be a social media login, like Facebook or Google. The SP and the IdP have to be pre-configured to work with each other, because the IdP will typically want to limit the scope of what URLs it can send the user data (Assertion) to. Generally speaking, an Assertion has the basic information of Name, Email, and UserID, but it can also contain elements inserted from other sources, such as group membership information. The SP gets some information about the IdP, specifically what URL to redirect to for authentication and the public key(s) that will be used for cryptographically signing (and sometimes encrypting) the Assertion sent back. The IdP is configured to only accept redirected login and logout requests from specific URLs. Because of this, the SP (in this case, openDCIM), never knows your password. Hence, modern authentication.
Many corporate environments are shifting away from using LDAP authentication, especially as more and more applications are migrating to cloud based services. Saml is a popular standard that is used for that. SAML is sent as an XML document that allows for a lot of data to be sent in various formats, but we're basically interested in the user profile information (Username, Given Name, Family Name, Email, Phone) and their group memberships (if used for authorization and not just authentication). Public Key Cryptography - basically signing certificates - are used to sign the XML message (and optionally encrypt), so the certificates have to be shared ahead of time.
OpenID Connect is very similar to SAML, except that rather than passing back all of the information about a user at once, only a select amount is sent in an encrypted token. Because tokens are part of the header, it is limited in size. Additional information can often be queried by performing what is called introspection, but as with SAML, our needs are fairly basic, so we really just use the ID Token. A pre-shared secret is used for encryption/decryption, so one disadvantage of using openID Connect is that, depending upon your Corporate Security Policy, you may be required to change it more frequently than you would with a signing certificate (used in SAML). As of version 23.01, we support both SAML and OIDC, so use whichever suits you best.
The OIDC configuration within openDCIM is shared with LDAP on the OIDC/LDAP tab. There are three pieces of information that you will need to coordinate with your OpenID Connect Identity Provider (IdP).
- Authorization Endpoint - this is the base URL for authentication. To be compliant, the IdP must also publish a JSON object at BASE_URL/.well-known/openid-configuration.
- Client ID - This is the name given by your IdP administrator to your application.
- Client Secret - This will be provided to you by your IdP administrator and as mentioned above, it may have to rotate on a periodic basis for security compliance.
The claim must follow the OIDC 1.0 Userinfo claim spec as detailed at https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
Just like with SAML, you will need to map out the attributes provided using Attribute_Mapping, especially if you wish to use it for Authorization.
Development for openDCIM was developed and tested using KeyCloak, PingFederate, and AzureAD as SAML2.0 providers. However, any SAML2.0 compliant provider should work - it's just a matter of realizing exactly what settings are needed. Generally speaking, here are some important toggles that may need to be set:
- Assertions should be signed, but not encrypted
- The IdP must be able to provide a metadata URL so that openDCIM can retrieve the x509 certificates used for signing
- The IdP should not require CA recognized certificates for openDCIM to sign with, as they are self generated and signed. This is referred to as Unanchored in PingFed.
- The IdP Assertion needs to contain the following information (the fields can be named anything, as long as you know what they are):
- username
- givenName
- sn
- The IdP should support POST and Redirect bindings. openDCIM will not attempt SOAP and it's a pain to configure, so don't bother.
- The IdP Administrator will need to know what URL to send the assertion back to, called the Assertion Consumer Service. It will be your {base_url}/saml/acs.php
If you wish to also use Saml for authorization (as in, what rights you have, rather than using the openDCIM db to manage it), you should also include an array of group names as another attribute.
There are two configuration tabs of interest when you are using Saml. First and foremost is where you set up your connection with the IdP, and that tab is called "SAML", and we will cover that here. The other tab, which you would fill out after setting up the SAML portion, is Attribute_Mapping.
The Base URL field is exactly that, and it must match what you define in the IdP, because some special URLs will be built adding on to this. Do not leave a trailing slash on the Base URl.
Show Success Page is mostly helpful when setting up, because after a successful login, it dumps the values to the page that the IdP returned in the Assertion. If you aren't 100% sure of what your IdP admin named the fields that are sent to you, this is where you can see them. It does have an auto-refresh to move on to the next page after 10 seconds, so you'll want to copy and paste the information to a text editor while you're working.
Entity ID is a unique identifier assigned by the IdP administrator for your application. Some IdP's will use the URL, others a hash. This field must match, otherwise when openDCIM redirects to the IdP for authentication, the IdP won't know the context and will likely complain of an unknown client id.
Country, State, and Organization are standard certificate fields. The Common Name is hard coded to "openDCIM SP Cert".
If you have a key and certificate pair already generated (in the database), the expiration date for it will display. Make sure that you generate a new one before it expires!
Generate new key/cert - simply change this field to Yes, and after you click Update, a new set will be generated and saved in the database, because we like the Easy Button.
All of the fields here will be provided by your IdP administrator. If they have a full metadata.xml file hosted, though, you can automatically pull the IdP entityId, SSO URL, and SLS URL from the metadata, along with the x509 certificate used for signing. Again, we like the Easy Button.
IdP Metadata URL is the most important field here for you to enter, because you must have, at minimum, the certificate information available to pull. If you don't have a metadata URL, it will be very tough to get SAML authentication to work for your site.
If you change the value in Refresh IdP Metadata? to Yes, once you hit Update, the metadata will be pulled from the IdP and the database will be updated.
Sometimes your account information comes back with parts that you don't want to include in the UserID, such as DOMAIN. There is a Remove Account Prefix and a Remove Account Suffix that you can put values into (this is a substring match, not a Regular Expression) for openDCIM to strip out. Most commercial SAML providers can strip this out before sending to you, which would typically be the preferred method to ensure consistency.