This page is based upon functions added in openDCIM version 20.01
Security Assertion Markup Language
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. Oauth2 is another, but if you look at the target use cases, Saml is more suited for an application like openDCIM. Oauth2 is a service where you grant the authority to an application to act on the behalf of a user. Saml is designed as a service to assure the identity of the user. That may seem like a pedantic distinction, but it's an important one. There's plenty of documentation on the web to argue both for or against that statement, so look at it this way - at least the Saml setup for openDCIM has a wiki entry.
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.
Development for openDCIM was developed and tested using KeyCloak and PingFederate 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):
- The IdP should support POST and Redirect bindings. openDCIM will not attempt SOAP and it's a pain to configure, so don't bother.
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.
SP Setup (The part you do in openDCIM)
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.
SAML Authentication Configuration
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.
SAML SP Information and Certificate Generation
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.
SAML Identity Provider Configuration
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.
SAML Account Configuration
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.