Configure SAML 2.0 Single Sign On

To use this mechanism, please ensure that your managed application supports authentication using SAML 2.0 protocol acting as the Service Provider (SP).

SAML 2.0 is a primarily web-based Single SignOn mechanism that uses XML based messages exchanged between the authenticating party, referred to as the Identity Provider (IdP) in the SAML 2.0 terms, and the relying party, referred to as the Service Provider (SP) in the SAML 2.0 terms.

In the context of Cymmetri SAML 2.0 implementation, your Cymmetri Identity platform deployment acts as the Identity provider (IdP) and the application managed that the end-user wishes to access through Single SignOn acts as the Service Provider (SP).

The mechanisms within the SAML 2.0 protocol used for sharing Single SignOn messages are referred to as the SAML 2.0 bindings. While the SAML 2.0 and its predecessor SAML 1.1 support various bindings, the Cymmetri Identity platform supports the two most commonly used bindings for web applications - viz., HTTP POST Binding and HTTP Redirect Binding. These reflect the manner in which the requests and responses are shared between the Identity provider (Cymmetri platform) and the Service Provider (managed application).

HTTP Redirect Binding - The SAML Assertion messages (request and response XML messages) are shared as GET query parameters.

HTTP POST Binding - The SAML Assertion messages (request and response XML messages) are shared as POST body messages.

Additionally, there are two flows in which SAML 2.0 Request-Response cycle may be accomplished.

1. Service Provider initiated flow (SP initiated flow)

2. Identity Provider initiated flow (IdP initiated flow)

At this stage, to start the configuration of the managed application for SAML 2.0 based SignOn mechanism, we must identify the supported flow for the managed application.

Let us explore what both of these flows mean and how to configure your managed application to use them.

Service Provider initiated flow (SP initiated flow)

Description

The SAML 2.0 Service Provider Initiated flow indicates that the Service provider (in our case, this would be the managed application to which the end-user wishes to perform Single SignOn into) has started the SAML 2.0 Single SignOn process by sending a SAML 2.0 request XML to the Cymmetri Identity platform. This is achieved by the user landing on the Single SignOn URL of the managed application.

In practice, however, since the user is typically on the Cymmetri Identity platform, we have enabled mechanisms to redirect the user to the Single SignOn URL of the managed application, when the user clicks on the application tile.

Flow Description

1. User lands on the SSO URL page of the managed application. (This may be either through clicking on the application tile on the Cymmetri platform or by the user actually entering the SSO URL of the managed application in the browser address bar.)

2. Managed application generates the SAML 2.0 request XML which holds the following important parameters - Request Id, Assertion Consumer Service URL (ACS), the protocol binding expected, and the Issuer of the request.

3. A redirect is made to the page handling Single SignOn requests on the Cymmetri Identity platform (<baseurl-of-cymmetri-deployment/samlsrvc/SingleSignOnService>) with the request in base64 format as a query parameter.

4. This page sends the SAML request body to the backend services of the Cymmetri platform to validate the request and to verify whether a session exists for a Cymmetri user in the current browser instance.

5. If a session does not exist for any user, the user is asked to login into the Cymmetri Identity platform.

6. If a session exists for the user, then the backend validates whether the user is authorised to access the application for which the SSO request has been initiated. (by checking whether the user is assigned the application.)

7. The backend services of the Cymmetri Identity platform generates a SAML response XML body and send it as GET request query parameter (if the protocol binding expected in the SAML request is HTTP Redirect) or as a POST request body (if the protocol binding expected in the SAML request is HTTP POST binding) to the Assertion Consumer Service URL mentioned in the SAML Request body, with the SAML Response audience as the Issuer mentioned in the SAML request body, and a field “InResponseTo” as the Request ID from the SAML request body.

8. The managed application would then validate the SAML response (and the signature, if was requested in the SAML request body).

9. If the SAML Response body is not a valid SAML Response, then the user is redirected to the managed application’s error page.

10. If the SAML response body is a valid SAML response, then the SAML assertion is extracted to obtain the user information sent by the Cymmetri Identity platform.

11. If the user information is not valid, for any reason, then the corresponding error is displayed to the user by redirecting the user to the managed application’s error page.

12. If all the user information is valid, the managed application initiates the user’s session in the managed application web portal, and corresponding session cookies are generated.

13. Finally, the user is redirected from the application’s Assertion Consumer Service URL to the landing page of the managed application.

In case of any validation errors, please refer to the section explaining the error scenarios below and change the configuration in either the managed application or the Cymmetri application SignOn configuration page.

Configuring application to use Service Provider initiated flow

The configuration parameters mentioned in the information panel below are required to configure an application for Single SignOn using the Identity provider initiated flow in the Cymmetri Identity portal.

Prerequisites from the managed Application

1. Request Issuer - This is the request issuer that would have been sent by the managed application in case this were a Service Provider initiated flow.

2. Assertion Consumer Service URL - This is the URL to which the SAML response must be sent by the Cymmetri Identity platform.

3. Expected NameID Policy - This indicates whether the managed application expects the user subject name to be sent as the Email Address, username, or some other unspecified value.

4. Expected Signature Algorithm - The expected algorithm to be used for signing the responses and assertions.

First we create an application in our Cymmetri Identity platform as discussed in previous articles. Let us use this application example below. We have already enabled SignOn as discussed here.

Let us go ahead and click on the radio button to enable SAML 2.0 option.

Let us now click on the dropdown for “Advanced Settings (SAML 2.0)”.

Click on the “Download Metadata” button, it is to be used in future steps.

Click on the purple “Download Metadata” button, it should open up a new tab with the xml file.

Let us come back to the SAML 2.0 settings for our sample managed application in Cymmetri platform deployment

Let us start entering the fields one by one.

SAML Type - We select the “SP_INITIATED” from the dropdown.

Since the metadata downloaded from the test app does not indicate the use of a particular signature algorithm, let us simply use “RSA_SHA256”.

Further, we need to select NameID Format. Referring to the highlighted portion in the metadata downloaded from the sample application, we find two supported NameID formats -

1. unspecified - This is a generic and default selection of NameID format, typically this would mean that the Cymmetri Identity platform may send any user attribute, which can be selected further. The managed application must handle it accordingly. This will be used whenever some custom or unusual user attribute is to be passed to the managed application.

2. email - This indicates to the managed application, that the Identity Provider (Cymmetri Identity Platform) will be sending the end-user’s email address, and that the managed application must handle it accordingly.

We see three other NameID formats in the dropdown, let us understand them one-by-one.

NameID Formats explained

1. transient - This is used as a NameID format when we wish to indicate to the managed application, that the end-user’s details sent during the SAML 2.0 process is in fact not permanent, but may change for the period of the end-user’s identity lifecycle.

2. persistent - This is used as a NameID format when we wish to indicate to the managed application, that the end-user’s details sent during the SAML 2.0 process is permanent, and will remain the same for the period of the end-user’s identity lifecycle.

3. username - This is used as a NameID format when we wish to indicate to the managed application, that we will be sharing the end-user’s username from Cymmetri Identity Provider to the managed application during the SAML 2.0 process.

Let us select email as the NameID format for now.

Let us now discuss NameID Values

There are two scenarios here -

1. Choosing NameID format as “username” and “email” - The value of the NameID Value will not matter, the end-user’s username or email address will be shared to the managed application.

2. Choosing NameID format as “unspecified”, “transient”, and “persistent” - The value of the NameID value will allow for a particular value of the User object to be shared to the managed application.

Possible Values of NameID Value are - email, mobile, firstName, lastName, displayName, loginId.

Let us select email as a NameID value, however, it will not affect the configuration.

Let us select “Exclusive” as the Canonicalization Method. Reasons may be explained here in the SAML reference document.

For configuring the “Request Issuer”, let us refer back to the downloaded saml-metadata.xml from the demo application.

We use the entityID from the downloaded metadata as the Request Issuer

Please note that the Request Issuer field is how the Cymmetri Identity platform identifies the managed application from the SAML Request sent by the managed application. Please ensure that the request issuer is unique across the deployment.

For the Assertion Consumer Service URL, we once again refer to the downloaded XML,

Let us enter the Assertion Consumer URL as “https://sptest.iamshowcase.com/acs”.

Finally, we refer to the downloaded XML one last time, for deciding upon the toggle buttons -

Here we see the managed demo application, requires only the Assertions to be signed and not the Authentication requests, we define the toggle switches accordingly.

Upload the metadata we downloaded from the Cymmetri Identity Platform configuration.

Hit the “Submit File” button to store the Identity provider metadata in the application.

Now copy the managed application’s Single SignOn URL from the popup as shown below -

Enter this URL into the SignOn configuration of the managed application on the Cymmetri Identity portal.

Click the “Save” button.

Testing the Service Provider initiated flow

Now that both sides are configured, let us test the flow by assigning the application to the current user.

Click on the “My Access” menu on the left sidebar under the “My Workspace” section.

Let us click on the application tile we created for the managed application demo.

We will now be redirected a few times and finally should land on the page below -

Identity Provider initiated flow (IdP initiated flow)

Description

The SAML 2.0 Identity Provider Initiated flow indicates that the Identity provider (in our case, this would be the Cymmetri Identity platform) has started the SAML 2.0 Single SignOn process by sending an unsolicited SAML 2.0 response XML to the Cymmetri Identity platform. This is achieved by the user clicking on the managed application tile in their workspace.

Flow Description

1. The user clicks on the application tile, which sends a request to the Cymmetri Identity platform backend to initiate the SAML 2.0 SignOn process.

2. The backend validates whether the user is authorised to access the application for which the SSO request has been initiated. (by checking whether the user is assigned the application.)

3. The backend services of the Cymmetri Identity platform generates a SAML response XML body and send it as GET request query parameter (if the protocol binding expected in the SAML request is HTTP Redirect) or as a POST request body (if the protocol binding expected in the SAML request is HTTP POST binding) to the Assertion Consumer Service URL mentioned in the SAML Request body, with the SAML Response audience as the Issuer mentioned in the SAML request body, and a field “InResponseTo” as the Request ID from the SAML request body.

4. The managed application would then validate the SAML response (and the signature, if was requested in the SAML request body).

5. If the SAML Response body is not a valid SAML Response, then the user is redirected to the managed application’s error page.

6. If the SAML response body is a valid SAML response, then the SAML assertion is extracted to obtain the user information sent by the Cymmetri Identity platform.

7. If the user information is not valid, for any reason, then the corresponding error is displayed to the user by redirecting the user to the managed application’s error page.

8. If all the user information is valid, the managed application initiates the user’s session in the managed application web portal, and corresponding session cookies are generated.

9. Finally, the user is redirected from the application’s Assertion Consumer Service URL to the landing page of the managed application.

Configuring application to use Identity Provider initiated flow

The configuration parameters mentioned in the information panel below are required to configure an application for Single SignOn using the Identity provider initiated flow in the Cymmetri Identity portal.

Prerequisites from the managed Application

1. Request Issuer - This is the request issuer that would have been sent by the managed application in case this were a Service Provider initiated flow.

2. Assertion Consumer Service URL - This is the URL to which the SAML response must be sent by the Cymmetri Identity platform.

3. Expected NameID Policy - This indicates whether the managed application expects the user subject name to be sent as the Email Address, username, or some other unspecified value.

4. Expected Signature Algorithm - The expected algorithm to be used for signing the responses and assertions.

First we create an application in our Cymmetri Identity platform as discussed in previous articles. Let us use this application example below. We have already enabled SignOn as discussed here.

Identity Provider initiated flow is a subset of the Service Provider initiated flow. Some steps are similar if you have already configured the Service Provider initiated flow.

Let us go ahead and click on the radio button to enable SAML 2.0 option.

Let us now click on the dropdown for “Advanced Settings (SAML 2.0)”.

Click on the purple “Download Metadata” button, it should open up a new tab with the xml file.

Let us come back to the SAML 2.0 settings for our sample managed application in Cymmetri platform deployment

Let us start entering the fields one by one.

SAML Type - We select the “IDP_INITIATED” from the dropdown.

Since the metadata downloaded from the test app does not indicate the use of a particular signature algorithm, let us simply use “RSA_SHA256”.

Further, we need to select NameID Format. Referring to the highlighted portion in the metadata downloaded from the sample application, we find two supported NameID formats -

1. unspecified - This is a generic and default selection of NameID format, typically this would mean that the Cymmetri Identity platform may send any user attribute, which can be selected further. The managed application must handle it accordingly. This will be used whenever some custom or unusual user attribute is to be passed to the managed application.

2. email - This indicates to the managed application, that the Identity Provider (Cymmetri Identity Platform) will be sending the end-user’s email address, and that the managed application must handle it accordingly.

We see three other NameID formats in the dropdown, let us understand them one-by-one.

NameID Formats explained

1. transient - This is used as a NameID format when we wish to indicate to the managed application, that the end-user’s details sent during the SAML 2.0 process is in fact not permanent, but may change for the period of the end-user’s identity lifecycle.

2. persistent - This is used as a NameID format when we wish to indicate to the managed application, that the end-user’s details sent during the SAML 2.0 process is permanent, and will remain the same for the period of the end-user’s identity lifecycle.

3. username - This is used as a NameID format when we wish to indicate to the managed application, that we will be sharing the end-user’s username from Cymmetri Identity Provider to the managed application during the SAML 2.0 process.

Let us select email as the NameID format for now.

Let us now discuss NameID Values

There are two scenarios here -

1. Choosing NameID format as “username” and “email” - The value of the NameID Value will not matter, the end-user’s username or email address will be shared to the managed application.

2. Choosing NameID format as “unspecified”, “transient”, and “persistent” - The value of the NameID value will allow for a particular value of the User object to be shared to the managed application.

Possible Values of NameID Value are - email, mobile, firstName, lastName, displayName, loginId.

Let us select email as a NameID value, however, it will not affect the configuration.

Let us select “Exclusive” as the Canonicalization Method. Reasons may be explained here in the SAML reference document.

For configuring the “Request Issuer”, let us refer back to the downloaded saml-metadata.xml from the demo application.

We use the entityID from the downloaded metadata as the Request Issuer

Please note that the Request Issuer field is how the Cymmetri Identity platform identifies the managed application from the SAML Request sent by the managed application. Please ensure that the request issuer is unique across the deployment.

For the Assertion Consumer Service URL, we once again refer to the downloaded XML,

Let us enter the Assertion Consumer URL as “https://sptest.iamshowcase.com/acs”.

Finally, we refer to the downloaded XML one last time, for deciding upon the toggle buttons -

Here we see the managed demo application, requires only the Assertions to be signed and not the Authentication requests, we define the toggle switches accordingly.

Click on the “Save” button.

Testing the Identity Provider initiated flow

Now that both sides are configured, let us test the flow by assigning the application to the current user.

Click on the “My Access” menu on the left sidebar under the “My Workspace” section.

Let us click on the application tile we created for the managed application demo.

We will now be redirected a few times and finally should land on the page below -

Possible Error Scenarios in Validation

Scenario 1: SAML request body does not meet the validation requirements for the SAML request.

Cause: Incorrect implementation of the SAML protocol by the managed application.

Fix: Verify that the SAML protocol is accurately implemented by the managed application.

Scenario 2: SAML request body does not have the same issuer as the configuration in the Cymmetri platform.

Cause: Incorrect configuration of SignOn on the Cymmetri platform for the managed application.

Fix: Change the request Issuer in the managed application configuration on the Cymmetri platform according to the Issuer field in the SAML request.

Scenario 3: SAML response body does not meet the validation requirements for the SAML response.

Cause: Incompatible expectations of the SAML 2.0 response body between the managed application and the Cymmetri Identity platform.

Fix: Connect with the Cymmetri Identity platform support team.

Scenario 4: SAML Response assertion has the incorrect audience.

Cause: Incorrect configuration of the request issuer field in the Cymmetri Identity platform for the managed application.

Fix: Verify and change the request issuer field in the managed application configuration on the Cymmetri platform according to the Issuer field in the SAML request.

Scenario 5a: User from the SAML Assertion is not valid.

Cause: Incorrect name ID format.

Fix: Verify and change the NameID format as expected by the managed application.

Scenario 5b: User from the SAML Assertion is not valid.

Cause: Incorrect user field in the assertion.

Fix: Verify that the right user field is selected as the “NameID Value” in the managed application configuration and Verify that the user information has the correct information as expected by the managed application in the field selected as the “NameID Value” in the managed application configuration on the Cymmetri platform.

Scenario 5c: User from the SAML Assertion is not valid.

Cause: User information is as expected but scenario 5b is not the cause.

Fix: Verify that the user information is present in the user database of the managed application. In case the managed application has JIT feature, ensure that the SAML attributes are correctly configured.

Configure SAML attributes

In case of default attributes, the user object already has the attributes, we just need to ensure that the right values are assigned to these attributes. In case of custom attributes, custom attributes must be added to your Cymmetri Identity platform deployment.

Let us investigate how this works out in the SAML 2.0 process and how the data is received from the Cymmetri Identity platform.

Let us click on the “configure SAML attributes” link in the configuration page

On clicking the following should pop up

Let us add an attribute mapper as per the table defined above

We have added the First Name of the user from the Cymmetri Identity Platform to the managed Application as the key “First Name”.

Click on the save icon next to the delete icon (trash can icon).

Click on the “X” icon to close the attribute mapper.

Now once again go back to the “My Access” page and click the application tile.

Once we obtain the results after the redirections we should find the attributes sent to the managed application.

As is visible, the SAML response now holds the attributes as “First Name” and the “Last Name”.

Samples

SAML 2.0 Sample Request

SAML 2.0 Sample Response