1 of 5

SSO How to

Configure Single Sign On

Cymmetri Single Sign On is a module that allows the end-user to simply authenticate once into the Cymmetri Identity platform web portal, and then access all the applications assigned to them without having to log in again into the target application.

The following article explains how to configure any application added to be managed in your Cymmetri Identity platform deployment to support Single SignOn mechanism.

Warning: Single SignOn Module needs to be enabled for your tenant for this configuration to be enabled and for Single SignOn to work.

Supported Single SignOn Mechanisms

Let us first visit the various supported Single SignOn Mechanisms available for the Cymmetri Identity platform.

SAML 2.0 SAML 2.0 (Security Assertion Markup Language) is a mechanism used primarily by web applications to share messages between each other to perform a Single SignOn for the end user.

OpenID Connect OpenID Connect refers to an authentication mechanism that is derived from the OpenID family of Single SignOn mechanisms. It enables the system to perform Single SignOn for a wide range of target application types (such as - Web applications, Mobile Native Applications, Desktop based Applications). It is therefore more versatile than SAML 2.0, and is more commonly used for mobile applications. It is also the mechanism used typically for social logins.

Warning: Please note that for using the above mentioned two mechanisms (SAML 2.0 and OpenID Connect), the managed application must support the corresponding mechanism.

REST API based SSO The above two Single SignOn mechanisms are based on well-accepted and standard mechanisms. However, there might be a few legacy applications in your organization, that for various reasons may not be able to integrate and support the above mentioned protocols, we have introduced Custom API-based SSO as an alternative Single SignOn Mechanism. This requires a few changes in the managed application code which will be referenced in the following section.

Note: Cymmetri Identity platform supports Custom API-based SSO mechanism. However, it is highly recommended to migrate to the aforementioned SAML 2.0 and OpenID Connect mechanisms.

Configuring Applications for Single SignOn

To allow your end-users to access applications managed by your Cymmetri Identity platform deployment, the applications must be configured for Single SignOn, and then assigned the application.

Redirect to Applications without Single SignOn

While it is not recommended for obvious reasons, as an administrator you may configure an application to be used simply for provisioning and redirection, without performing Single SignOn.

Note: The following section is to be used for configure only applications for which you do not need to perform Single SignOn. In case you need to configure any of the following Single SignOn mechanisms, you may skip this section and refer to the corresponding configuration in your chosen method of Single SignOn.

Configuring the Application URL

For configuring an application to simply redirect the enduser to the landing page of the managed application -

Once in the applications menu, click on the application tile for which you need to configure the landing page URL and then on the left side menu, select the SignOn menu item.

Toggle the “Enable Single Sign-On (SSO)” switch to open the corresponding configuration options.

Enter the landing page URL in the “Application URL” text box and click the adjoining “Save” button.

The popup indicating “SSO Updated Successfully” will indicate that the Application URL has been configured successfully for your application.

Conclusion

Assigning the application to an end user will show an application tile as shown below:

Clicking on the application tile, will redirect the user to the assigned landing page URL.

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.

Service Provider initiated flow (SP initiated flow)
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

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.)
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.
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.
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.
If a session does not exist for any user, the user is asked to login into the Cymmetri Identity platform.
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.)
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.
The managed application would then validate the SAML response (and the signature, if was requested in the SAML request body).
If the SAML Response body is not a valid SAML Response, then the user is redirected to the managed application’s error page.
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.
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.
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.
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

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.
Assertion Consumer Service URL - This is the URL to which the SAML response must be sent by the Cymmetri Identity platform.
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.
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 -

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.
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

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.
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.
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 -

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.
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

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.
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.)
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.
The managed application would then validate the SAML response (and the signature, if was requested in the SAML request body).
If the SAML Response body is not a valid SAML Response, then the user is redirected to the managed application’s error page.
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.
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.
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.
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

Prerequisites from the managed Application

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.
Assertion Consumer Service URL - This is the URL to which the SAML response must be sent by the Cymmetri Identity platform.
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.
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 -

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.
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

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.
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.
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 -

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.
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

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

Configure API SSO

Cymmetri platform highly recommends adding support to either SAML 2.0 or OpenID Connect protocols owing to their well-accepted standards and to avoid vendor lock-in.

In the absence of the ability of the managed application to adopt either the SAML 2.0 or the OpenID Connect 1.0 standard, the Cymmetri Identity platform provides with the ability to integrate simple REST API based mechanism to allow an end-user to perform Single SignOn from the Cymmetri Identity Portal

REST API based SSO Explained

Flow explained

User is assigned the application and clicks on the application tile.
The end user session is captured as the client IP address as received from the user’s browser.
The user session is validated and the Cymmetri Identity platform checks if the end user is authorised to perform Single SignOn into the managed application.
In case, such a session token is created and the end-user is redirected as a query parameter to an endpoint on the managed application.
The endpoint on the managed application also captures the end-user’s client IP address, and sends the received token to its backend.
The managed application backend already holds the Application ID and Application password assigned to it when the API-based SSO is configured on the Cymmetri Identity platform.
The managed application backend now makes a POST call to the validate token API endpoint exposed by the Cymmetri Identity platform with the form parameters as follows -
1. app_id - Previously shared application ID
2. app_pass - Previously shared application password
3. user_ip - End-user’s client IP address as captured from the end-user’s browser
4. auth_token - the token sent to the endpoint of the managed application.
The Cymmetri Identity platform responds back with a success message in case the application ID, application Password, client IP address and the user session string match with the corresponding records in its backend.
In case of success, the managed application is expected to generate a user session for the prescribed user Id as shared in the success response message.
The Cymmetri Identity platform responds back with a failure message in case of even one parameter mismatch from among - application ID, application Password, client IP address or the user session string (shared token).
In case of failure, the managed application is expected to cancel the login attempt and show the error message shared by the Cymmetri Identity platform.

Configuration for REST API based SSO mechanism

For configuring the REST API based SSO mechanism, first select the application already added into your Cymmetri Identity platform deployment.

Then proceed to the SSO configuration using the “SignOn” link in the left-hand side menu bar.

Enable the Single SignOn by clicking the toggle button on the right-hand side of the page.

Now enter the application URL as below -

Application URL = <base url of the deployment>/apiSSO?applicationId=<applicationId>

Let us first copy the URL from the address bar -

The corresponding URL in my case is -

https://ssotester.cymmetri.io/application/6241c3b604c15417a91c7030/sign-on

We evaluate the following values from the URL -

Base URL of the deployment - https://ssotester.cymmetri.io
applicationId - 6241c3b604c15417a91c7030

Now we generate the Application URL as - https://ssotester.cymmetri.io/apiSSO?applicationId=6241c3b604c15417a91c7030

Let us enter this value in the Application URL text bar and click the “Save” button.

Let us proceed by selecting the radio button “API-based SSO”

Click on the dropdown “Advanced Settings (API)” to configure the API-based SSO and enter the information -

Configuration Parameters

Source app token param name - Refers to the key of the query parameter used to share the randomly generated token from the Cymmetri backend.
Application Secret - Refers to the parameter app_pass that must be sent back by the managed application to validate the token.
Target App Redirect URL - Refers to the endpoint exposed by the managed application to receive the token as a query parameter.
Token Validity - number of seconds for which the generated token is valid. The managed application must send back the token for validation within these many seconds.
Target app token param name - This is the field that the managed application must use to send back the token for validation.
External Application ID - Refers to the parameter app_id that must be sent back by the managed application to validate the token.

Assign the application to a user.

On clicking the application tile, the user is redirected to the URL below as per the configuration above.

http://localhost:4124/getToken?auth_token=<random token>

Once the token is received by the application, the application makes a POST call as indicated by the CURL request below -

curl --location --request POST 'https://ssotester.cymmetri.io/api-sso/api/sso/validateToken' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'app_id=demoapps' \ --data-urlencode 'app_pass=Pras@4i1m$' \ --data-urlencode 'auth_token=<random token>' \ --data-urlencode 'user_ip=<client IP address>'

Responses from the Validation

Success Response

JSON response

{

“status”:”Success”,

“allow_user”:”true”,

“user_id”:”abhishek.kulkarni”

}

Error Response

JSON Response

{

“status”:”User not verified”,

“allow_user”:”false”,

“user_id”:”abhishek.kulkarni”

}

In case of this error, “User not verified” message must be shown by the managed application. The user must not be allowed to login.

JSON Response

{

“status”:”Application not verified”,

“allow_user”:”false”,

“user_id”:”abhishek.kulkarni”

}

In case of this error, “Application not verified” message must be shown by the managed application. The user must not be allowed to login. The application configuration on the Cymmetri Identity platform and the managed application must be validation and cross-verified.

Configure OpenID Connect based Single SignOn

To use this mechanism ensure that the managed application supports authentication using OpenID Connect 1.0 protocol.

OpenID Connect 1.0 is a simple authentication layer protocol built on top of OAuth 2.0 protocol. It acts as a Single SignOn mechanism and authentication mechanism for not only the Web based applications, as SAML 2.0 does, but also for applications requiring access to APIs protected by this protocol as an authorisation mechanism, and for mobile-native or Single page Applications (SPA) to verify user’s identity.

For understanding the core concepts of the OpenID Connect 1.0 protocol, it is important to grab the basics of the underlying OAuth 2.0 protocol.

Glossary of terms used in OAuth 2.0 and OpenID Connect 1.0 protocols

Client (RP) - Client refers to the managed application to which the end-user wishes to perform Single SignOn into. The client in the context of the OAuth 2.0 and OpenID Connect 1.0, is also referred to as the Relying Party (RP), since it relies on the Authorisation Server
1. Client ID - Client ID is the unique identifier assigned to each managed application while configuring the application for OpenID Connect 1.0 or OAuth 2.0 flow.
2. Client Secret - This is a secret value that is shared between the relying party and the Authorisation server, so that they may communicate and be always assured that the communication shared was actually sent by the other node in the communication.
Cymmetri Identity Platform - Cymmetri Identity platform in the context of OpenID Connect 1.0 Single SignOn mechanism acts as two components in the OAuth 2.0 and OpenID Connect 1.0 flows. These component roles are explained below.
1. OpenID module (Authorisation Server) - Since the Cymmetri Identity platform acts as an Identity platform, it holds the capability to ensure that user session is valid, the user is authorised to access the managed application, among other authorisation decisions, it plays the role of Authorisation server in the OpenID Connect 1.0 process.
2. User Management Module (Resource server) - Since the Cymmetri Identity platform acts as a user identity hub, it holds the capability to store and provide user information to a managed application for the purpose of authentication and Single SignOn, it plays the role of Resource server (Resource, being the user information) in the OpenID Connect 1.0 process.
User (Resource Owner) - The user information to be shared for a successful authentication is the resource in the OpenID Connect 1.0 flow, therefore, in the OAuth 2.0 terms, the user information is the resource, and the end-user is the resource owner.
OpenID Authorisation Endpoint - Authorization endpoint is used for accepting authentication/authorization requests in the form of redirected requests with the OpenID request query parameters added to it.
OpenID Token Endpoint - Token endpoint is used for generating Access and ID tokens by using the authorisation code received by the managed application (Relying Party).
User Information Endpoint - User information endpoint may be invoked by using the token shared to the managed application from the Cymmetri Identity platform, it will provide a list of all the user information that the user has consented to share with the end-application.
Token Introspection Endpoint - Token introspection endpoint is used when the relying party is an API client that requires access to the APIs protected by the OpenID Connect deployment. It will verify whether the access token is still valid and well-formed.
Redirect URIs - These are callback resources on the managed application, that can receive the messages sent from the Authorisation provider (Cymmetri Identity platform).
Scope - These are parameters used to indicate what information related to the user can be shared to the managed application.
State - This is a random string generated by the Relying party (managed application) to ensure that the message sent back by the Cymmetri platform is a response for the request raised by it for Single SignOn.
Nonce - This is a random string generated by Relying party (managed application) to ensure that the message sent back by the Cymmetri platform is a response for the request raised by it for Single SignOn and to prevent replay attacks.
Access Token - Access token is generated by the Cymmetri Identity platform for the purpose of authorising a client (whether an end-user OR an application using OpenID Connect). This may be verified for the purpose of ensuring the validity of the access token by the client requesting the token.
ID Token - The ID token is generated by the Cymmetri Identity platform for the purpose of authenticating an end-user using OpenID Connect protocol. Typically, the subject name and the email Address are shared as a part of this ID token along with any nonces or states used in the protocol are shared. This ID token may be used to get more information using the User Information Endpoint.
Authorisation Code - This is a string generated by the Cymmetri Identity platform for the purpose of server-to-server communication between the Relying party (managed application) and the Authorisation provider (Cymmetri Identity Platform). It may be exchanged by the relying party for the purpose of obtaining access and ID tokens.

Understanding OpenID Connect Flows

Common Use Cases for OpenID Connect 1.0

For performing Single SignOn with managed applications that have a backend (Typical Web Application SSO)
For performing Single SignOn with managed applications that do not have a backend (Single Page Applications and mobile-native applications)
For authorising access to REST APIs by verifying that the client making the calls has the requisite access.

Commonly Used OpenID Connect 1.0 flows

1. Authorisation Code Grant Type Flow

Typically used in the same scenario as the SAML 2.0 flow, it is used when the Identity provider and the Managed application are both capable of having a separate frontend and backend. These backends can have back-channel communication that is secure and cannot be modified or viewed in transit. This is therefore typically used when full-blown web applications are available.

2. Implicit Grant Type Flow

Typically used when the managed application is a simple Single Page application or a mobile native application that may not be able to use back-channel secure communication and a shared secret may not be used for authenticating the managed application to the Identity provider.

3. Client Credentials Type Flow

Typically used when a user is not involved and there is no need for ID tokens. The managed application handles its own authentication or is operating as a backend service only and needs to access a resource protected by the Identity provider.

Configuring and Managing OpenID Connect flow for Authorisation Code Grant Type

Understanding the Authorisation Code Grant Type

Flow Diagram

Flow Explained

User requests to access the application.
The managed application generates a random string each for state and nonce for starting the OpenID flow; and set these as the cookies for the user browser.
The Cymmetri Identity platform frontend will generate authorization request with the client_id, state, nonce, redirect_uri, response_type expected, and the scopes requested by the application.
The request will be verified by the OpenID service in the Cymmetri Identity platform backend.
Redirect the user to the login flow page, and initiate the login challenge-response flow.
Login Challenge sent by the OpenID service to the frontend.
Login session of the end-user is verified by the user service.
Once the login session is verified, the frontend service responds back to the OpenID service with the challenge sent to it, to complete the login challenge-response flow.
The openID service sets a login_verifier nonce as a cookie.
The frontend replays the authorization request to the openID service with the login_verifier nonce to initiate the consent flow.
The OpenID service validates the login_verifier nonce. If successful, then the OpenID service will redirect the end-user to the consent flow page.
The frontend would then load the consent page with the scopes expected by the managed application, as reflected in the configuration.
The end user must then provide the consent for the scopes to share the relevant data to the managed application.
The challenge-response for consent flow is sent to the OpenID service with the scopes accepted by the end-user.
The OpenID service will set a cookie on the user’s browser with a consent verifier nonce.
The frontend replays the authorization request to the openID service with the consent_verifier nonce.
If the response was accepted by the Consent flow, then an authorization code will be sent to the frontend.
The Cymmetri frontend will then redirect the user to the “redirect_uri” of the managed application with the authorization code, state, and the nonce will be sent as query parameters.
The managed application will verify the state and the nonce shared in step 2.
The managed application will then make a POST API request to the Token API of the Cymmetri OpenID service to exchange the authorization_code with the ID token and the Access token.
If this authorization_code is validated by the OpenID service, the managed application will receive the ID token and the Access token.
The managed application may simply use the ID token to get the username and email address of the user and attempt to generate a session.
If more user information is needed and the profile scope was consented by the user, then the managed application may make a call to the User Information endpoint of the OpenID service using the “access token” received in step 21.
This user information may also be used by managed application to generate a user session.
Once the user session is created, the managed application sets the session cookie on the user browser, and redirects the user to the managed application landing page.

Configuring the Authorisation Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty OR an endpoint from the managed application may be added that can initiate the OpenID flow by making a call to the OpenID service of the Cymmetri Identity platform deployment.

Select the OpenId/OAuth radio button to start configuring OpenID flow

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

The ‘openid’ scope is mandatory for this flow.

The ‘offline_access’ scope is not currently used by the Cymmetri Identity platform deployment.

Other profiles are optional.

Providing ‘profile’ scope overrides the settings for the ‘email', ‘address’ and ‘phone’ scopes.

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Authorization Code refers to the current flow.
Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the authorization code, and NOT the ID token, we may choose “code” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen code as our return type, we could choose any other response type that also includes code return type.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

This indicates the manner in which the response (access token or ID token) is shared back by the Cymmetri Identity platform to the managed application.

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow uses redirections to share credentials and involves user interaction. So we choose to use “Client Secret over HTTP Basic” as the response type setting for this flow.

Configuring and Managing OpenID Connect flow for Implicit Grant Type

Understanding the Implicit Grant Type

Flow Diagram

Flow Explained

User requests to access the application.
The managed application generates a random string each for state and nonce for starting the OpenID flow; and set these as the cookies for the user browser.
The Cymmetri Identity platform frontend will generate authorization request with the client_id, state, nonce, redirect_uri, response_type expected, and the scopes requested by the application.
The request will be verified by the OpenID service in the Cymmetri Identity platform backend.
Redirect the user to the login flow page, and initiate the login challenge-response flow.
Login Challenge sent by the OpenID service to the frontend.
Login session of the end-user is verified by the user service.
Once the login session is verified, the frontend service responds back to the OpenID service with the challenge sent to it, to complete the login challenge-response flow.
The openID service sets a login_verifier nonce as a cookie.
The frontend replays the authorization request to the openID service with the login_verifier nonce to initiate the consent flow.
The OpenID service validates the login_verifier nonce. If successful, then the OpenID service will redirect the end-user to the consent flow page.
The frontend would then load the consent page with the scopes expected by the managed application, as reflected in the configuration.
The end user must then provide the consent for the scopes to share the relevant data to the managed application.
The challenge-response for consent flow is sent to the OpenID service with the scopes accepted by the end-user.
The OpenID service will set a cookie on the user’s browser with a consent verifier nonce.
The frontend replays the authorization request to the openID service with the consent_verifier nonce.
If the response was accepted by the Consent flow, then an authorization code will be sent to the frontend.
The Cymmetri frontend will then redirect the user to the “redirect_uri” of the managed application with the access token, ID token, state, and the nonce will be sent as query parameters.
The managed application may simply use the ID token to get the username and email address of the user and attempt to generate a session.
If more user information is needed and the profile scope was consented by the user, then the managed application may make a call to the User Information endpoint of the OpenID service using the “access token” received in step 21.
This user information may also be used by managed application to generate a user session.
Once the user session is created, the managed application sets the session cookie on the user browser, and redirects the user to the managed application landing page.

Configuring the Implicit Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty OR an endpoint from the managed application may be added that can initiate the OpenID flow by making a call to the OpenID service of the Cymmetri Identity platform deployment.

Select the OpenId/OAuth radio button to start configuring OpenID flow -

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Implicit refers to the current flow.

Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the ID token directly along with access token, we may choose “id_token” or “id_token token” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen 'id_token token' as our return type, we could choose any other response type that also includes both of these return types.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

Credential Dropdown Settings

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow uses redirections to share credentials and involves user interaction. So we choose to use “Client Secret over HTTP Basic” as the response type setting for this flow.

Configuring and Managing OpenID Connect flow for Client Credentials Grant Type

Understanding the Client Credentials Grant Type

Flow Diagram

Flow Explained

Generating Access Token for the Managed Application

OpenID service shares client ID, client secret, and audience to the managed application during the configuration phase.
The managed application makes a POST request to the token API of the OpenID service with the previously shared clientID, client secret, the audience string, and the grant_type as “client_credentials”.
The OpenID service validates the combination of (client_id, client_secret, and audience) and generates an access token to be shared to the managed application with an expiry time (in seconds).
The managed application should then verify the access token received by calling the token introspection endpoint.

Using the Access token to access protected API resource

The managed application should first request an access token as discussed above.
The managed application may then attempt to access the protected resource by sharing the client_id and authenticate the request using Bearer token as the access_token.
The protected resource may then validate the access token shared by calling the token introspection and validate that the client_id shared by the managed application in step 2 matches the client_id for which the access_token was generated, and that the token has not expired.
If the validation in step 3 is successful, the protected resource will be shared to the managed application.

Configuring the Client Credentials Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty for this flow, since the user does not need to be involved with this flow.

Select the OpenId/OAuth radio button to start configuring OpenID flow -

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.
Audience - This audience needs to be shared by the managed application, and the Cymmetri Identity platform will validate it for providing access token.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Authorization Code refers to the current flow.

Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the access token, and NOT the ID token, we may choose “code” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen code as our return type, we could choose any other response type that also includes code return type.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

Credential Dropdown Settings

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow has API exchange of tokens and validations. So we choose to use “Client Secret over HTTP POST” as the response type setting for this flow.

Configure OpenID Connect based Single SignOn

To use this mechanism ensure that the managed application supports authentication using OpenID Connect 1.0 protocol.

For understanding the core concepts of the OpenID Connect 1.0 protocol, it is important to grab the basics of the underlying OAuth 2.0 protocol.

Glossary of terms used in OAuth 2.0 and OpenID Connect 1.0 protocols

Client (RP) - Client refers to the managed application to which the end-user wishes to perform Single SignOn into. The client in the context of the OAuth 2.0 and OpenID Connect 1.0, is also referred to as the Relying Party (RP), since it relies on the Authorisation Server
1. Client ID - Client ID is the unique identifier assigned to each managed application while configuring the application for OpenID Connect 1.0 or OAuth 2.0 flow.
2. Client Secret - This is a secret value that is shared between the relying party and the Authorisation server, so that they may communicate and be always assured that the communication shared was actually sent by the other node in the communication.
Cymmetri Identity Platform - Cymmetri Identity platform in the context of OpenID Connect 1.0 Single SignOn mechanism acts as two components in the OAuth 2.0 and OpenID Connect 1.0 flows. These component roles are explained below.
1. OpenID module (Authorisation Server) - Since the Cymmetri Identity platform acts as an Identity platform, it holds the capability to ensure that user session is valid, the user is authorised to access the managed application, among other authorisation decisions, it plays the role of Authorisation server in the OpenID Connect 1.0 process.
2. User Management Module (Resource server) - Since the Cymmetri Identity platform acts as a user identity hub, it holds the capability to store and provide user information to a managed application for the purpose of authentication and Single SignOn, it plays the role of Resource server (Resource, being the user information) in the OpenID Connect 1.0 process.
User (Resource Owner) - The user information to be shared for a successful authentication is the resource in the OpenID Connect 1.0 flow, therefore, in the OAuth 2.0 terms, the user information is the resource, and the end-user is the resource owner.
OpenID Authorisation Endpoint - Authorization endpoint is used for accepting authentication/authorization requests in the form of redirected requests with the OpenID request query parameters added to it.
OpenID Token Endpoint - Token endpoint is used for generating Access and ID tokens by using the authorisation code received by the managed application (Relying Party).
User Information Endpoint - User information endpoint may be invoked by using the token shared to the managed application from the Cymmetri Identity platform, it will provide a list of all the user information that the user has consented to share with the end-application.
Token Introspection Endpoint - Token introspection endpoint is used when the relying party is an API client that requires access to the APIs protected by the OpenID Connect deployment. It will verify whether the access token is still valid and well-formed.
Redirect URIs - These are callback resources on the managed application, that can receive the messages sent from the Authorisation provider (Cymmetri Identity platform).
Scope - These are parameters used to indicate what information related to the user can be shared to the managed application.
State - This is a random string generated by the Relying party (managed application) to ensure that the message sent back by the Cymmetri platform is a response for the request raised by it for Single SignOn.
Nonce - This is a random string generated by Relying party (managed application) to ensure that the message sent back by the Cymmetri platform is a response for the request raised by it for Single SignOn and to prevent replay attacks.
Access Token - Access token is generated by the Cymmetri Identity platform for the purpose of authorising a client (whether an end-user OR an application using OpenID Connect). This may be verified for the purpose of ensuring the validity of the access token by the client requesting the token.
ID Token - The ID token is generated by the Cymmetri Identity platform for the purpose of authenticating an end-user using OpenID Connect protocol. Typically, the subject name and the email Address are shared as a part of this ID token along with any nonces or states used in the protocol are shared. This ID token may be used to get more information using the User Information Endpoint.
Authorisation Code - This is a string generated by the Cymmetri Identity platform for the purpose of server-to-server communication between the Relying party (managed application) and the Authorisation provider (Cymmetri Identity Platform). It may be exchanged by the relying party for the purpose of obtaining access and ID tokens.

Understanding OpenID Connect Flows

Common Use Cases for OpenID Connect 1.0

For performing Single SignOn with managed applications that have a backend (Typical Web Application SSO)
For performing Single SignOn with managed applications that do not have a backend (Single Page Applications and mobile-native applications)
For authorising access to REST APIs by verifying that the client making the calls has the requisite access.

Commonly Used OpenID Connect 1.0 flows

1. Authorisation Code Grant Type Flow

2. Implicit Grant Type Flow

3. Client Credentials Type Flow

Configuring and Managing OpenID Connect flow for Authorisation Code Grant Type

Understanding the Authorisation Code Grant Type

Flow Diagram

Flow Explained

User requests to access the application.
The managed application generates a random string each for state and nonce for starting the OpenID flow; and set these as the cookies for the user browser.
The Cymmetri Identity platform frontend will generate authorization request with the client_id, state, nonce, redirect_uri, response_type expected, and the scopes requested by the application.
The request will be verified by the OpenID service in the Cymmetri Identity platform backend.
Redirect the user to the login flow page, and initiate the login challenge-response flow.
Login Challenge sent by the OpenID service to the frontend.
Login session of the end-user is verified by the user service.
Once the login session is verified, the frontend service responds back to the OpenID service with the challenge sent to it, to complete the login challenge-response flow.
The openID service sets a login_verifier nonce as a cookie.
The frontend replays the authorization request to the openID service with the login_verifier nonce to initiate the consent flow.
The OpenID service validates the login_verifier nonce. If successful, then the OpenID service will redirect the end-user to the consent flow page.
The frontend would then load the consent page with the scopes expected by the managed application, as reflected in the configuration.
The end user must then provide the consent for the scopes to share the relevant data to the managed application.
The challenge-response for consent flow is sent to the OpenID service with the scopes accepted by the end-user.
The OpenID service will set a cookie on the user’s browser with a consent verifier nonce.
The frontend replays the authorization request to the openID service with the consent_verifier nonce.
If the response was accepted by the Consent flow, then an authorization code will be sent to the frontend.
The Cymmetri frontend will then redirect the user to the “redirect_uri” of the managed application with the authorization code, state, and the nonce will be sent as query parameters.
The managed application will verify the state and the nonce shared in step 2.
The managed application will then make a POST API request to the Token API of the Cymmetri OpenID service to exchange the authorization_code with the ID token and the Access token.
If this authorization_code is validated by the OpenID service, the managed application will receive the ID token and the Access token.
The managed application may simply use the ID token to get the username and email address of the user and attempt to generate a session.
If more user information is needed and the profile scope was consented by the user, then the managed application may make a call to the User Information endpoint of the OpenID service using the “access token” received in step 21.
This user information may also be used by managed application to generate a user session.
Once the user session is created, the managed application sets the session cookie on the user browser, and redirects the user to the managed application landing page.

Configuring the Authorisation Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty OR an endpoint from the managed application may be added that can initiate the OpenID flow by making a call to the OpenID service of the Cymmetri Identity platform deployment.

Select the OpenId/OAuth radio button to start configuring OpenID flow

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

The ‘openid’ scope is mandatory for this flow.

The ‘offline_access’ scope is not currently used by the Cymmetri Identity platform deployment.

Other profiles are optional.

Providing ‘profile’ scope overrides the settings for the ‘email', ‘address’ and ‘phone’ scopes.

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Authorization Code refers to the current flow.
Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the authorization code, and NOT the ID token, we may choose “code” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen code as our return type, we could choose any other response type that also includes code return type.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

This indicates the manner in which the response (access token or ID token) is shared back by the Cymmetri Identity platform to the managed application.

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow uses redirections to share credentials and involves user interaction. So we choose to use “Client Secret over HTTP Basic” as the response type setting for this flow.

Configuring and Managing OpenID Connect flow for Implicit Grant Type

Understanding the Implicit Grant Type

Flow Diagram

Flow Explained

User requests to access the application.
The managed application generates a random string each for state and nonce for starting the OpenID flow; and set these as the cookies for the user browser.
The Cymmetri Identity platform frontend will generate authorization request with the client_id, state, nonce, redirect_uri, response_type expected, and the scopes requested by the application.
The request will be verified by the OpenID service in the Cymmetri Identity platform backend.
Redirect the user to the login flow page, and initiate the login challenge-response flow.
Login Challenge sent by the OpenID service to the frontend.
Login session of the end-user is verified by the user service.
Once the login session is verified, the frontend service responds back to the OpenID service with the challenge sent to it, to complete the login challenge-response flow.
The openID service sets a login_verifier nonce as a cookie.
The frontend replays the authorization request to the openID service with the login_verifier nonce to initiate the consent flow.
The OpenID service validates the login_verifier nonce. If successful, then the OpenID service will redirect the end-user to the consent flow page.
The frontend would then load the consent page with the scopes expected by the managed application, as reflected in the configuration.
The end user must then provide the consent for the scopes to share the relevant data to the managed application.
The challenge-response for consent flow is sent to the OpenID service with the scopes accepted by the end-user.
The OpenID service will set a cookie on the user’s browser with a consent verifier nonce.
The frontend replays the authorization request to the openID service with the consent_verifier nonce.
If the response was accepted by the Consent flow, then an authorization code will be sent to the frontend.
The Cymmetri frontend will then redirect the user to the “redirect_uri” of the managed application with the access token, ID token, state, and the nonce will be sent as query parameters.
The managed application may simply use the ID token to get the username and email address of the user and attempt to generate a session.
If more user information is needed and the profile scope was consented by the user, then the managed application may make a call to the User Information endpoint of the OpenID service using the “access token” received in step 21.
This user information may also be used by managed application to generate a user session.
Once the user session is created, the managed application sets the session cookie on the user browser, and redirects the user to the managed application landing page.

Configuring the Implicit Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty OR an endpoint from the managed application may be added that can initiate the OpenID flow by making a call to the OpenID service of the Cymmetri Identity platform deployment.

Select the OpenId/OAuth radio button to start configuring OpenID flow -

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Implicit refers to the current flow.

Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the ID token directly along with access token, we may choose “id_token” or “id_token token” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen 'id_token token' as our return type, we could choose any other response type that also includes both of these return types.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

Credential Dropdown Settings

This indicates the manner in which the response (access token or ID token) is shared back by the Cymmetri Identity platform to the managed application.

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow uses redirections to share credentials and involves user interaction. So we choose to use “Client Secret over HTTP Basic” as the response type setting for this flow.

Configuring and Managing OpenID Connect flow for Client Credentials Grant Type

Understanding the Client Credentials Grant Type

Flow Diagram

Flow Explained

Generating Access Token for the Managed Application

OpenID service shares client ID, client secret, and audience to the managed application during the configuration phase.
The managed application makes a POST request to the token API of the OpenID service with the previously shared clientID, client secret, the audience string, and the grant_type as “client_credentials”.
The OpenID service validates the combination of (client_id, client_secret, and audience) and generates an access token to be shared to the managed application with an expiry time (in seconds).
The managed application should then verify the access token received by calling the token introspection endpoint.

Using the Access token to access protected API resource

The managed application should first request an access token as discussed above.
The managed application may then attempt to access the protected resource by sharing the client_id and authenticate the request using Bearer token as the access_token.
The protected resource may then validate the access token shared by calling the token introspection and validate that the client_id shared by the managed application in step 2 matches the client_id for which the access_token was generated, and that the token has not expired.
If the validation in step 3 is successful, the protected resource will be shared to the managed application.

Configuring the Client Credentials Grant Type in the Cymmetri Identity platform

First, we need to add the managed application into the Cymmetri Identity platform deployment.

Enable the Single SignOn by -

Clicking on the SignOn link on the left side menu
Clicking the toggle button on the right side.
The application URL text box may be left empty for this flow, since the user does not need to be involved with this flow.

Select the OpenId/OAuth radio button to start configuring OpenID flow -

Click on the dropdown for Advanced Settings (OpenID)

Main Dropdown Settings

Client ID - Refers to the client_id to be sent to the managed application.
Client Name - User friendly name for the client.
Client Secret - Can be left blank. After saving the configuration, a popup will show the generated client secret.
Redirect URLs - Refers to the endpoint on the managed application, that acts as a callback URL.
Audience - This audience needs to be shared by the managed application, and the Cymmetri Identity platform will validate it for providing access token.

Access Dropdown Settings

Scope Settings

Scopes are used to track the consents of the end-users. This is used to determine what information the end-user wishes to share with the managed application.

Let us understand the scopes in play here -

openid - As we wish to support OAuth 2.0 flows as well, the openid scope is optional. However, since we are dealing with OpenID Connect flow here, openid scope is mandatory for this flow.
email - User’s email address is shared with the managed application.
address - User’s address fields are shared with the managed application.
phone - User’s phone number and mobile number fields are shared with the managed application.
profile - Shares the entire list of user attributes with the managed application.
offline_access - <added for future-proofness, not yet implemented>

Grant Type setting lets the Cymmetri Identity platform know which flow you wish to opt for -

Authorization Code refers to the current flow.

Refresh Token has not been implemented currently for the Cymmetri Identity platform.

Since this flow requires sharing the access token, and NOT the ID token, we may choose “code” as a response type.

The managed application is expected to mention using query parameters while starting the OpenID Connect flow to mention which response type it is expecting from the Cymmetri Identity platform.

While, we have chosen code as our return type, we could choose any other response type that also includes code return type.

Public subject type setting is used, since it is the most common mechanism for OpenID connect flows.

Pairwise Mechanism may be supported upon request. Please contact Cymmetri Support team in case your application needs support for pairwise subject type.

Credential Dropdown Settings

This indicates the manner in which the response (access token or ID token) is shared back by the Cymmetri Identity platform to the managed application.

Client Secret over HTTP basic - Shared as a query parameter or a fragment to the managed application through an HTTP redirect.
Client Secret over HTTP POST - Shared as a part of the response body to a REST endpoint exposed by the managed application through a POST Request.
Private key JWT - Share JWT instead of opaque access tokens. This is no longer considered safe and other options are preferred.

No Authentication as a response type is not to be used in the OpenID Connect flow.

The current flow has API exchange of tokens and validations. So we choose to use “Client Secret over HTTP POST” as the response type setting for this flow.

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).

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.

Service Provider initiated flow (SP initiated flow)
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

Flow Description

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.)
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.
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.
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.
If a session does not exist for any user, the user is asked to login into the Cymmetri Identity platform.
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.)
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.
The managed application would then validate the SAML response (and the signature, if was requested in the SAML request body).
If the SAML Response body is not a valid SAML Response, then the user is redirected to the managed application’s error page.
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.
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.
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.
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 Service Provider initiated flow

Prerequisites from the managed Application

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.
Assertion Consumer Service URL - This is the URL to which the SAML response must be sent by the Cymmetri Identity platform.
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.
Expected Signature Algorithm - The expected algorithm to be used for signing the responses and assertions.

Let us start by taking a demo application for the purpose of testing this functionality. We will be using a demo application provided by RSA labs - RSA SAML Test provider (SAML 2.0 Test Service Provider ).

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.

Let us visit the link here to the demo application. [SAML 2.0 Test Service Provider]

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 -

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.
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

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.
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.
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 -

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.
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

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.

Let us return back to the managed demo application for completing the configuration on the Service provider side. [SAML 2.0 Test Service Provider ]

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

Flow Description

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.
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.)
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.
The managed application would then validate the SAML response (and the signature, if was requested in the SAML request body).
If the SAML Response body is not a valid SAML Response, then the user is redirected to the managed application’s error page.
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.
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.
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.
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

Prerequisites from the managed Application

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.
Assertion Consumer Service URL - This is the URL to which the SAML response must be sent by the Cymmetri Identity platform.
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.
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)”.

Let us visit the link here to the demo application. [SAML 2.0 Test Service Provider]

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 -

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.
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

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.
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.
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 -

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.
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.