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