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 date (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):
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.
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.