Sentinel EMS Workflow with OAuth Clients
This page describes the various workflows that you can use when defining OAuth clients in Sentinel EMS and using OAuth with the Sentinel REST APIs. The Sentinel identity provider (Sentinel IDP) is used either exclusively or partially in all of these flows.
Client Credentials Grant Type Flow for Use with the Sentinel Identity Provider
In this service-to-service flow, the vendor's back-end service uses client credentials to request an access token on behalf of the application. This flow returns an access token with administrator privileges that enables the application to consume the Sentinel REST APIs. The client credentials grant type flow is relevant only for confidential OAuth clients.
Recommended for:
Server-side web applications, where the API is called on behalf of the application.
Prerequisites and Initial Setup
1.The vendor administrator must add an OAuth client using either the Sentinel EMS vendor portal (described in Adding an OAuth Client) or using the Sentinel EMS APIs.
2.After creating the OAuth client, the vendor administrator must retrieve the Client ID and Client Secret, and the Sentinel Identity Provider (IDP) endpoints from the Sentinel EMS vendor portal or using the Sentinel EMS APIs.
Client Credentials Flow: Implementation with the Sentinel Identity Provider
1.The vendor's back-end service can fetch the client credentials from an environment variable, a secure location, or another service.
2.The vendor's back-end service must obtain the JWT from the Sentinel identity provider using the client credential OAuth flow.
3.The vendor's back-end service consumes the Sentinel EMS REST API using JWT.
Best practices:
>Store client credentials securely.
>Optionally run periodic jobs from the vendor service to get new JWT before the JWT expire. For example, after 75% of the time has elapsed.
>Use a singleton class for access token handling. Ensure that token creation happens with synchronization to handle concurrent requests.
Authorization Code Grant Type Flow for Use with the Sentinel Identity Provider
In this flow, the vendor uses the Sentinel identity provider to authenticate users and to issue an access token that enables users to log in and use the vendor application. The main difference between this flow and Authorization Code Grant Type Flow for Use with the Vendor Identity Provider (IdP) is that only Sentinel identity provider is used, not the vendor identity provider.
Recommended for:
>Server-side web applications, where the API is called on behalf of the user.
>Single-page applications, where the API is called on behalf of the end user. In this case, you must create an OAuth public client that uses the Authorization Code grant type with PKCE.
>On-premises applications, where the API is called on behalf of the end user. In this case, you must create an OAuth public client that uses the Authorization Code grant type with PKCE.
Prerequisites and Initial Setup
1.The vendor administrator must add an OAuth client using either the Sentinel EMS vendor portal (described in Adding an OAuth Client) or using the Sentinel EMS APIs.
2.After creating the OAuth client, the vendor administrator must retrieve the Client ID, Client Secret (for confidential clients only), and the Sentinel Identity Provider (IDP) endpoints from the Sentinel EMS vendor portal or using the Sentinel EMS APIs.
To ensure a seamless user experience when using the vendor application,
Authorization Code Grant Type Flow: Implementation with the Sentinel Identity Provider
1.The vendor developer uses the authorization code flow when initiating the authentication process with the Sentinel identity provider. End users see the login page from the Sentinel identity provider, which is customized with the vendor's branding, and enter their login credentials for authentication purposes.
2.The vendor application must initiate the authentication workflow using the Sentinel IDP endpoint to fetch the Sentinel JWT for the logged-in user. The vendor application must obtain the Sentinel JWT for the logged in user, so that an access token can be generated for the Sentinel identity provider.
3.After retrieving the access token, the application can consume the Sentinel REST APIs with the JWT for the user.
4.The application must store the JWT for the user for at least the open session. Make sure to refresh the access token before it expires. To ensure a seamless customer experience, you might refresh the token after 75% of the time has elapsed. You can also refresh the token when the token expires. The implementation depends on your application requirements.
Authorization Code Grant Type Flow for Use with the Vendor Identity Provider (IdP)
In this flow, Sentinel IDP is configured with the vendor identity provider details, so that users are authenticated using only the vendor identity provider. This flow issues an access token that enables users to log in and use the vendor application.
To access Sentinel REST APIs, the vendor application uses a Sentinel JWT that was issued by the Sentinel identity provider, as described in Authorization Code Grant Type Flow: Implementation with the Vendor Identity Provider (IdP) below.
The main difference between this flow and Authorization Code Grant Type Flow for Use with the Sentinel Identity Provider is that both the vendor identity provider and Sentinel IDP are used. Additionally, the vendor developer must ensure that the Sentinel JWT for the user is issued by the Sentinel identity provider prior to any Sentinel API calls.
Recommended for:
>Server-side web applications that authenticate users with the vendor identity provider, where the API is called on behalf of the user.
>Single-page applications that authenticate users with the vendor identity provider, where the API is called on behalf of the user. In this case, you must create an OAuth public client that uses the Authorization Code grant type with PKCE.
>On-premises applications that authenticate users with the vendor identity provider, where the API is called on behalf of the user. In this case, you must create an OAuth public client that uses the Authorization Code grant type with PKCE.
Prerequisites and Initial Setup
1.The vendor identity provider must be configured in Sentinel EMS for federation purposes. Contact Thales Customer Support to set up your vendor identity provider for you.
2.Each application user that is provisioned in the vendor's system must also be provisioned (without a password) in Sentinel EMS. Make sure to use the same Sentinel EMS instance as the vendor identity provider. For Sentinel EMS vendor users (not end users or channel partners), make sure to associate the required roles as well.
3.The vendor administrator must add an OAuth client using either the Sentinel EMS vendor portal (described in Adding an OAuth Client) or using the Sentinel EMS APIs. For Confidential Client Type applications, the vendor administrator must retrieve the Client ID and Client Secret after creating the OAuth client.
4.The vendor administrator retrieves the Sentinel Identity Provider (IDP) endpoints from the Sentinel EMS vendor portal or using the Sentinel EMS APIs.
Authorization Code Grant Type Flow: Implementation with the Vendor Identity Provider (IdP)
1.The vendor developer initiates the authentication process with the vendor's identity provider. End users then see the vendor application's login page and enter their login credentials.
To enable the application to open the vendor's login page, the vendor developer must append the kc_idp_hint parameter to the authorization endpoint URI
The kc_idp_hint parameter query value must be set as the identity provider name that was shared with Thales Customer Support during the SSO setup, not its display name. The value can be retrieved using the Users endpoint (Identities & Access > Vendor User) as described in the Sentinel EMS REST API Reference. If the identity provider name cannot be found, contact Thales Customer Support.
Example:
https://idp.example.com/auth/realms/123456-abcde/protocol/openid-connect/auth?kc_idp_hint=identity-provider-name
2.The vendor application must obtain the Sentinel JWT for the logged in user, so that an access token can be used to consume Sentinel REST APIs. To obtain the Sentinel JWT, the authorization code flow is initiated with the Sentinel identity provider, which then redirects to the vendor identity provider. This flow can be initiated wherever it is required in the application, not just when the user logs in. For example, if an area of the application requires data from a Sentinel REST API, the flow must be initiated before the Sentinel REST API call.
3.After retrieving the access token, the application can consume the REST API with the JWT for the user.
4.The application must store the JWT for the user for at least the open session. The access token must be refreshed before it expires to ensure a seamless customer experience. For example, the token might be refreshed after 75% of the time has elapsed. The token can also be refreshed when the token expires. The implementation depends on your application requirements.
Selecting an OAuth Grant Type
You can select a suitable OAuth Grant Type for your application by using the following flowchart. This flowchart outlines the decision-making process for selecting a grant type based on whether your application is public or confidential. Use this flowchart to determine the best grant type based on your specific requirements.
For details, see Client Type.
NOTE This flowchart is relevant only when using Sentinel REST APIs for Sentinel EMS and Licensing.
