1 of 4

SSO Configuration

SAML 2.0 Based SSO

Note: 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 Sign On 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 platform acts as the Identity Provider (IdP) and the managed application that the end-user wishes to access through Single Sign On acts as the Service Provider (SP).

SAML 2.0 bindings

The mechanisms within the SAML 2.0 protocol used for sharing Single Sign On 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 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.

SAML 2.0 Request-Response Cycle

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)

To start the configuration of the managed application for SAML 2.0 based SignOn mechanism, we must identify the flow supported by the managed application.

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

Service Provider Initiated Flow (SP Initiated Flow)

The SAML 2.0 Service Provider Initiated flow indicates that the Service Provider (in our case, the managed application which the end-user wishes to access via Single Sign On) has started the SAML 2.0 Single Sign On process by sending a SAML 2.0 request XML to the Cymmetri platform. This is achieved by the user landing on the Single Sign On URL of the managed application.

In practice, however, since the user is typically on the Cymmetri 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 expected Protocol Binding, and the Issuer of the Request.
A redirect is made to the page handling Single Sign On requests on the Cymmetri platform (<baseurl-of-cymmetri-tenant/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 authorized 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 platform generates a SAML response XML body and send it as GET request query parameter (if the protocol binding in the SAML request is HTTP Redirect) or as a POST request body (if the protocol binding 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 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.

Note: 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 Sign On configuration page.

Service Provider(SP) Initiated Flow Configuration

The configuration parameters mentioned below are required to configure an application for Single Sign On using the Service Provider Initiated flow in the Cymmetri platform.

Prerequisites from the Managed Application

Entity ID/ 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 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 see an example demonstrating SP Initiated flow. We will be using a Service Now Instance for this example.

First we create an application in Cymmetri platform as discussed in previous articles. Let us use this application example below. We have already enabled SignOn as discussed and selected the 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.

Now go back to Service Now instance and Navigate to Multi-Provider SSO > Identity Providers. Choose any existing IdP and click the Generate Metadata button. The integration automatically generates the instance's SP metadata from the system property settings.

Let us come back to the SAML 2.0 settings for our managed application in Cymmetri platform and start entering the fields one by one.

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

Since the metadata downloaded from ServiceNow 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 only 1 supported NameID format

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

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

NameID Formats:

unspecified: This is a generic and default selection of NameID format, typically this would mean that the Cymmetri 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.
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.

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 metadata.xml from the Service Now application.

We use the entityID from the downloaded metadata as the Entity ID

Please note that the Entity ID field is how the Cymmetri platform identifies the managed application from the SAML Request sent by the managed application. Please ensure that the Entity ID 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://dev165684.service-now.com/navpage.do"

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

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

Let us return back to Service Now application for completing the configuration on the Service rovider side.

Note:

Before starting the IDP Configuration the Multi Provider SSO Plugin needs to be enabled. Steps for the same are provided here: https://docs.servicenow.com/bundle/vancouver-platform-security/page/integrate/single-sign-on/task/t_ActivateMultipleProviderSSO.html

Also the plugin is activated, we need to Configure Multi-Provider SSO properties, Steps for the same are provided here: https://docs.servicenow.com/bundle/vancouver-platform-security/page/integrate/single-sign-on/task/t_ConfigureMultiProviderSSOProps.html

For successfully enable SSO properties you might have to configure an account recovery user, Steps for the same are provided here: https://docs.servicenow.com/bundle/vancouver-platform-security/page/integrate/single-sign-on/concept/config-acr.html

Once the above 3 steps are successfully completed we can create a new IDP

Create a new IDP

Click on the New button to create a new IDP

Then select SAML

Then upload the metadata from the file downloaded in a previous step. and Hit Import button to store the Identity provider metadata in the application.

Once imported provide the Signing/ Encryption Key Alias and Signing/ Encryption Key Password as saml2sp and in the Advanced Tab tick the CreateAuthnContextClass checkbox. The Signing/ Encryption Key Alias and Signing/ Encryption Key Password are used for encryption of data and the CreateAuthnContextClass is used to tell the IDP that Service Now requires that they present a specific login mechanism such as form, Kerberos etc.

Note: Also make sure both the logout urls present here are removed temporarily for testing purposes, else you would logout completely from ServiceNow

Then enter the instance url in the SignOn configuration of the managed application on the Cymmetri portal.

Click the “Save” button.

Next Create a New User in Service Now. Go to Organization->Users->New and provide the credentials of the user logged into Cymmetri as show below and Submit:

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.

Then to activate the externa IDP in Service Now we need to test the connection on the Service Now side by clicking on the Test Connection button.

Once successfully tested you should see the below screen with successful test results. Click on the Activate button to activate the IDP.

Once activated Click on the Set as Auto Redirect IdP link to automatically redirect to IDP when using a SP Initiated process

Once it is enabled we can come to the currently logged in user's My Workspace-> My Access page and click on the Service Now application tile

We will now be redirected to the ServiceNow home page using the logged in users crendentials as shown below:

Identity Provider Initiated Flow (IdP Initiated Flow)

The SAML 2.0 Identity Provider Initiated flow indicates that the Identity Provider (in our case, the Cymmetri 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 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 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 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.

Identity Provider(IdP) Initiated Flow Configuration

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

Entity ID/ Request Issuer: This is the entity id/ 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.

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

First we create an application in the Cymmetri platform as discussed in previous article. Let us use Service Now application as an example below. We have already enabled SignOn and enabled SAML 2.0 option.

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

Let us start entering the fields one by one.

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

All the remaining steps for configuring IdP Initiated SAML 2.0 flow are same as shown above in the SP Initiated flow.

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 currently logged in user's My Workspace-> My Access page and click on the Service Now application tile

We will now be redirected to the ServiceNow home page using the logged in users crendentials as shown below:

Identity Provider Initiated Flow (IdP Initiated Flow)

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 entity id/request issuer field in the Cymmetri Identity platform for the managed application.

Fix: Verify and change the entity id/ 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.

SAML Attribute Mapper

A SAML Attribute Mapper is a component or feature in a Single Sign-On (SSO) or identity federation system that helps map user attributes between different identity providers (IdPs) and service providers (SPs) during the SAML (Security Assertion Markup Language) authentication process.

Here's how it works:

Authentication: When a user tries to access a service or application that requires authentication, they are redirected to an identity provider (IdP) for authentication. The IdP verifies the user's identity and generates a SAML assertion containing information about the user.
SAML Assertion: The SAML assertion typically contains various attributes about the user, such as their username, email address, roles, or other user-related information. These attributes are represented as name-value pairs.
Attribute Mapping: Before the SAML assertion is sent to the service provider (SP), which is the application or service the user is trying to access, there may be a need to map or transform these attributes. This is where the SAML Attribute Mapper comes into play.
- Attribute Transformation: Sometimes, the IdP may use different attribute names or formats than what the SP expects. The SAML Attribute Mapper can transform the attributes in the SAML assertion to match the expectations of the SP.
- Filtering: The mapper can also be used to filter or select specific attributes from the SAML assertion. For example, if the IdP provides a wide range of attributes, but the SP only needs a subset of them, the mapper can be configured to include only the required attributes in the assertion sent to the SP.
- Value Mapping: It can map attribute values as well. For instance, if the IdP uses "userType=employee" and the SP expects "role=employee," the mapper can perform this value mapping.
Forwarding to SP: Once the attributes in the SAML assertion are mapped or transformed as necessary, the SAML assertion is forwarded to the service provider. The SP can then use these attributes for authorization and access control decisions.

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

Service Now can use this data for auto provisioning of users via jit provisioning provided Auto Provisioning User is enabled under the User Provisioning tab in the Identity Provider Configuration page.

Samples

SAML 2.0 Sample Request

SAML 2.0 Sample Response

<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
                 Destination="https://dev165684.service-now.com/navpage.do"
                 ID="_6db464f3-b783-4834-98ea-6ed1681dd2cd"
                 IssueInstant="2023-09-26T10:19:01.472Z"
                 Version="2.0"
                 >
    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">ccaa</saml2:Issuer>
    <saml2p:Status>
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </saml2p:Status>
    <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                     xmlns:xs="http://www.w3.org/2001/XMLSchema"
                     ID="_e4baa225-cd79-4ac2-93b3-0a5ab7ef2f87"
                     IssueInstant="2023-09-26T10:19:01.472Z"
                     Version="2.0"
                     >
        <saml2:Issuer>ccaa</saml2:Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
                <ds:Reference URI="#_e4baa225-cd79-4ac2-93b3-0a5ab7ef2f87">
                    <ds:Transforms>
                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                            <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"
                                                    PrefixList="xs"
                                                    />
                        </ds:Transform>
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
                    <ds:DigestValue>4BaEkbuyzytz0XkXo19cBeLjGnYrTOvPhxfv3NWyidc=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>vRw1lhio5G38L/inuAp9l9yjekbCCM4BduLykL7vg4wijlHmbrSMiNJNuqOu8vO79Aqruj6GBafGRD6Slqrco5vScsWbfH5LiHz5UejAh2sGsqbQHapYFPlZJ6ErauwFxbzGN7od5CYlZUgDPUdO1dF2jiwoYeqhs+aQOISsyoq9pcQ2yl35wmaUy6C388a+m54OzygQhwsQdxEeA1OqLDtAw3ulTxbKsjRw1hAa7zv4JKKO10HirrWwWXDe3dSsh2Z3um0sF6TxWjV5wKXKflXz1alNPcNBONTjTWOfwKD/a+agZITQ8jGJAo6vZXfF3bI7N0uo3dWF3ogK2jzpjg==</ds:SignatureValue>
        </ds:Signature>
        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">Ak@mail.com</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData NotOnOrAfter="2023-09-26T18:19:01.472Z"
                                               Recipient="https://dev165684.service-now.com/navpage.do"
                                               />
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions NotBefore="2023-09-26T10:16:01.472Z"
                          NotOnOrAfter="2023-09-26T10:22:01.472Z"
                          >
            <saml2:AudienceRestriction>
                <saml2:Audience>https://dev165684.service-now.com</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AuthnStatement AuthnInstant="2023-09-26T10:19:01.472Z"
                              SessionIndex="_e4baa225-cd79-4ac2-93b3-0a5ab7ef2f87"
                              >
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml2:AuthnContextClassRef>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
        <saml2:AttributeStatement>
            <saml2:Attribute Name="User Name"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >Ak@123</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="email"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >Ak@mail.com</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="firstName"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >Akash</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="lastName"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xs:string"
                                      >Patil</saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
    </saml2:Assertion>
</saml2p:Response>

API Based 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 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 Description

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 platform checks if the end user is authorized 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 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 platform responds back with a failure message in case of even one parameter mismatches 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 platform.

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

Mentioned below is a sample getToken method implemented in the managed application that wishes to use API SSO implementation. The url in the api call and the app_id and app_pass may vary from tenant to tenant

// Sample getToken method implementation in a Spring MVC Application
@RequestMapping("/getToken")
public String getToken(@RequestParam("auth_token") String auth_token, HttpServletRequest req) throws IOException {
	this.auth_token=auth_token;
	String ip=req.getRemoteAddr();
	Properties prop=new Properties();
	boolean allow_user=false;
	
	try (InputStream inputStream = getClass()
			.getClassLoader().getResourceAsStream("App.properties")) {
		
            	prop.load(inputStream);
            	String app_id=prop.getProperty("app_id");
    		String app_pass=prop.getProperty("app_pass");
    		String inputStr="app_id="+app_id+"&app_pass="+app_pass+"&user_session_string="+auth_token+"&user_ip="+ip;
    		String resp=apiCall("https://ssotester.cymmetri.io/api-sso/api/sso/validateToken", inputStr);
    		JSONObject respJSON = new JSONObject(resp);
    		allow_user=respJSON.getBoolean("allow_user");
	} catch (IOException e) {
		e.printStackTrace();
	}	
	
	if(allow_user)
	{
		return "Dashboard";
	}
	else
	{
		return "redirect:/Login.jsp";
	}
}
	
public String apiCall(String urlStr, String inputStr) throws IOException
{
	URL url = new URL(urlStr);

	// Open a connection(?) on the URL(??) and cast the response(???)
	HttpURLConnection connection = (HttpURLConnection) url.openConnection();

	connection.setDoOutput(true);
	connection.setRequestMethod("POST");
	connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
	// Now it's "open", we can set the request method, headers etc.
	connection.setRequestProperty("accept", "application/json");
	
	try(OutputStream os = connection.getOutputStream()) {
	    byte[] input = inputStr.getBytes("utf-8");
	    os.write(input, 0, input.length);			
	}
			
	StringBuilder response = new StringBuilder();
	try(BufferedReader br = new BufferedReader(
		  new InputStreamReader(connection.getInputStream(), "utf-8"))) {
		   
		    String responseLine = null;
		    while ((responseLine = br.readLine()) != null) {
		        response.append(responseLine.trim());
		    }
	}
	
	return response.toString();
}

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.

OpenID Connect Based SSO

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 Sign On 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 authorization 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 Authorization 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 Authorization 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 Platform: Cymmetri 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 (Authorization Server): Since Cymmetri platform acts as an Identity platform, it holds the capability to ensure that user session is valid, the user is authorized to access the managed application, among other authorization decisions, it plays the role of Authorization server in the OpenID Connect 1.0 process.
2. User Management Module (Resource server): Since the Cymmetri 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 Sign On, 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.

OpenID Connect Based SSO

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 Authorization 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 Authorization 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 Platform: Cymmetri 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 (Authorization Server): Since Cymmetri platform acts as an Identity platform, it holds the capability to ensure that user session is valid, the user is authorized to access the managed application, among other authorization decisions, it plays the role of Authorization server in the OpenID Connect 1.0 process.
2. User Management Module (Resource server): Since the Cymmetri 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 Sign On, 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.

SAML 2.0 Based SSO

Note: 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 bindings

The mechanisms within the SAML 2.0 protocol used for sharing Single Sign On messages are referred to as the SAML 2.0 bindings.

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.

SAML 2.0 Request-Response Cycle

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)

To start the configuration of the managed application for SAML 2.0 based SignOn mechanism, we must identify the flow supported by the managed application.

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

Service Provider Initiated Flow (SP Initiated Flow)

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 expected Protocol Binding, and the Issuer of the Request.
A redirect is made to the page handling Single Sign On requests on the Cymmetri platform (<baseurl-of-cymmetri-tenant/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 authorized 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 platform generates a SAML response XML body and send it as GET request query parameter (if the protocol binding in the SAML request is HTTP Redirect) or as a POST request body (if the protocol binding 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 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.

Service Provider(SP) Initiated Flow Configuration

The configuration parameters mentioned below are required to configure an application for Single Sign On using the Service Provider Initiated flow in the Cymmetri platform.

Prerequisites from the Managed Application

Entity ID/ 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 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 see an example demonstrating SP Initiated flow. We will be using a Service Now Instance for this example.

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 come back to the SAML 2.0 settings for our managed application in Cymmetri platform and start entering the fields one by one.

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

Since the metadata downloaded from ServiceNow 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 only 1 supported NameID format

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

NameID Formats:

unspecified: This is a generic and default selection of NameID format, typically this would mean that the Cymmetri 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.
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.

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.