SAML 2.0 Overview
Overview
This article outlines the SAML 2.0 metadata exchange and authentication process.
Terminology
Term | Definition |
|---|---|
SAML | Security Assertion Markup Language, a type of XML used in SAML-based SSO. |
IdP | Identity Provider. In the case of the Cloud SSO, the IdP is always the Cloud SSO app, and by extension, iMIS. |
SP | Service provider, also referred to as the third party. Any connecting system that makes use of SAML SSO. |
Metadata | An XML document that describes a particular entity. The two most common types are SP Metadata and IdP Metadata. |
Entity ID | A unique string that identifies either an SP or an IdP. This is typically a URL, and typically the same as the metadata URL, but doesn't have to be. |
ACS URL | Assertion Consumer Service. SAML's fancy term for the URL endpoint that SAML responses should be sent to at the SP. |
Binding Format | The method by which the SAML response is sent. Can be one of HTTP POST (most common), or HTTP Redirect. |
Audience (Restriction) | The audience is the intended recipient of the SAML response. If the Audience Restriction is required by the SP, then it must match the value the SP is expecting it to be (sometimes the same as the SP's Entity ID, but not always). |
Client App | A record stored by the IdP to describe a single connecting SP / third party. The IdP stores the metadata of the SP along with some settings pertaining to that SP. |
(AuthN) Request | An XML document sent from the SP to the IdP requesting that the current user be signed in via SAML. |
Assertion | An XML document sent from the IdP to the SP describing the current user that is signed in (i.e. their username, or other NameID format). |
Attribute(s) | One or more XML elements that are sent inside an Assertion to provide more information about the current user. This is typically the user's profile information. |
NameID | SAML's term for the current user's username. Can also be another piece of information that uniquely identifies the user, such as a database ID, GUID, e-mail address, or something else. |
1. Client App Registration
To register a client app / SP / third party integration, you must know the SP's metadata information, and upload or enter it into the Cloud SSO.
A. SP Metadata
The first step in client app registration is to import or enter the SP's metadata information.
The SP will typically provide this in the form of an XML file, a URL, or listed manually.
If the SP will not provide its metadata until it has an IdP metadata document first, you may enter dummy values into the Client App form in the Cloud SSO app in order to save and generate an IdP metadata document. Once the SP provides its metadata, you may edit the client app settings and enter the correct information.
B. IdP Metadata
After saving the client app, you should see a button on the Client Apps screen, on your client app record, that says View IdP Metadata. This will take you to the IdP metadata screen for this app where you can either:
Download the IdP metadata .xml file
Copy and paste the IdP metadata XML document
Copy and paste individual values (such as the entity ID and single sign on endpoint)
Copy and paste, or download the public certificate and/or private key, if needed
Once you enter the IdP metadata into the SP's configuration area and save the changes, the SAML SSO should be ready to go.
2. SAML Request and Response
A. Initiating an Authentication Request
Cloud SSO's SAML implementation supports SP-initiated login as well as IdP-initiated login. SP-initiated login is preferred. You will need to have the SP generate an authentication request in this case. This is typically done by attempting to access a protected page or resource, which should trigger an authentication request (if you are not already signed in).
Behind the scenes, the SP will generate an AuthN request document and send it to the Cloud SSO's single sign-on endpoint.
You can also take the IdP-Initiated Login URL from the IdP Metadata screen and use it to initiate the login process. (Note that not all third-parties support this mode.)
B. iMIS Identity Verification
Once the authentication request is validated by the Cloud SSO, we verify the user's identity in iMIS.
Identity Mode: iMIS EMS or 2017
In iMIS Cloud identity mode, the user is simply redirected to the secure RiSE page where the RiSE SSO iPart was published. If the user is already signed in, the user is immediately redirected back to the Cloud SSO with the relevant user context information. If the user is not already signed in, RiSE handles the user signing in and will return them to the SSO iPart page once they have successfully signed in, thereby redirecting them back to the Cloud SSO.
Identity Mode: iMIS 2017 Legacy On-Premises
In iMIS 2017 Legacy On-Premises identity mode, if the Cloud SSO app can read the current forms authentication cookie and obtain the username of the current user, the user is not shown a login screen, and instead, a SAML response is immediately sent.
If the user is not signed in, or we are otherwise unable to read the forms auth cookie, then the user is shown a sign-in page where they must enter their current iMIS username and password which is checked against the iMIS database before proceeding.
C. Profile Retrieval (Optional)
If the profile IQA or role IQA options are set, then the current username is run against these IQAs and the profile information for this user is retrieved and translated into SAML attributes.
D. SAML Response
Once the current user is verified, and their profile information is (optionally) retrieved, the SAML response is built, (optionally) signed, and sent via the designated channel / URI back to the SP.
At this point, the user should be signed in to the SP / third-party system according to the SAML configuration.