OAuth Clients

>What Is an OAuth Client?

>Prerequisites for Creating an OAuth Client

>OAuth Grant Types

>Adding an OAuth Client

>Viewing OAuth Client Details

>Actions for OAuth Clients

 

>Choosing a Grant Type
See Choosing an OAuth Grant Type

>About the Sentinel IDP
See Sentinel Identity Provider (IDP)

What Is an OAuth Client?

Open Authorization or OAuth provides a secure and standardized way for users and applications to grant third-party applications controlled access to their resources, promoting security, privacy, and ease of use in a modern web ecosystem.

The OAuth (Open Authorization) 2.0 authorization framework is a protocol that enables end users using an application to grant third-party applications (usually on another web site) limited access to their protected resources, such as user data or functionality, without sharing their end user credentials, such as user names and passwords.

An OAuth client refers to an application or service that can make requests for protected resources on behalf of the resource owner after the resource owner grants authorization. The resource owner can be the end user or the application itself (using machine-to-machine communication that does not involve the end user). There are two types of OAuth clients: confidential and public. Confidential clients are registered with a client secret, while public clients are not.

The OAuth client can be a web application, a mobile application, or even a command-line tool.

NOTE   When working with OAuth, you can use any relevant Sentinel REST API. You are not limited to the Sentinel EMS REST APIs.

Prerequisites for Creating an OAuth Client

The vendor user must have administrative rights in Sentinel EMS. For details, see Roles.

OAuth Grant Types

An OAuth grant type determines how an application obtains an access token to access protected resources. The following grant types are available:

Grant Type Description
Client Credentials

Used for server-to-server communication, where the client application sends its own credentials (client ID and client secret) to generate an access token. This is done in the back end on behalf of the client application without user intervention. (This grant type does not involve user authentication or authorization.) ClosedLearn when to use client credentials

The client credentials grant type is used when the selected Client Type is Confidential.

A typical use case is when the client application needs to access resources that are not specific to any user.
Authorization Code

Used primarily for server-side web applications, generating an access token using an authorization code is a two-step process that may or may not include PKCE (Proof Key for Code Exchange). ClosedLearn more about this two-step process

1.Authorization Request. The client application redirects to the authorization server's endpoint, which is a specific URL provided by the OAuth server that handles the initial step of the OAuth flow. The client application passes the necessary parameters, including the client ID, redirect URI, and scope. The end user is then presented with a login screen and logs in. After successful authentication, the authorization code is provided to the client application

2.Token Request. After the end user grants authorization, the authorization server redirects the call back to the client application's redirect URI with an authorization code. The client application then exchanges this authorization code for an access token by making a request to the authorization server's token endpoint, providing the authorization code, client ID, client secret, and redirect URI.

The Authorization Code grant type is very secure because the client application never sees the end user's credentials. This grant type also allows for the use of refresh tokens to obtain new access tokens without requiring end user interaction.

PKCE is an optional method that can be used in addition to the Authorization Code grant type when the selected Client Type is Public. PKCE uses a code challenge and verifier mechanism to ensure that the client making the token request is the same client that initiated the authorization process. This additional security layer helps prevent authorization code interception attacks, enhancing the security of OAuth authorization endpoints. ClosedLearn about the PKCE code challenges—Plain and S256

>Plain. The client application includes the plain code challenge in the authorization request. The code challenge is the same as the code verifier. It is recommended to use this method only when S256 is not possible.

This challenge is much less secure than S256 because if the authorization code is intercepted, the attacker can use that code to obtain an access token.

>S256. The code challenge is the SHA-256 hash of the code verifier, encoded using base64url. The client application includes the S256 code challenge in the authorization request.

This challenge provides a greater level of security compared to the plain challenge. Even if the authorization code is intercepted, the attacker cannot derive the code verifier from the code challenge.

Adding an OAuth Client

To add an OAuth client:

1.From the navigation pane, select Identies & Access > OAuth Clients to view the OAuth Clients page.

2.Click the Add OAuth Client button.

3.Fill in the OAuth client attributes. The available options change according to your selections.

Confidential Client Type with Client Credentials Grant Type

Confidential Client Type with Authorization Code Grant Type

Public Client Type with Authorization Code Grant Type

The following table explains the attributes that are used to create an OAuth client:

Attribute Description Required/Optional Valid Values
Name

The name of the OAuth client.

Required

>Alphanumeric

>1 to 255 characters

>Must be unique
Client ID

The OAuth client ID defined in Sentinel EMS. If not specified, then the value is automatically generated when the OAuth client is created. The client ID, whether user-defined or auto-generated, is automatically prefixed with 'app-'.

You can click Copy to copy the client ID to the Clipboard.

Required

>Special characters supported: _ (underscore) and - (hyphen )
Client Type

Determines the level of trust and security associated with the client application.

>Confidential

A confidential client is a client application that can securely store and maintain its client credentials, such as a client ID and client secret. ClosedLearn more

These credentials are used to securely authenticate the client application with the authorization server during the OAuth flow, ensuring that only authorized clients can access protected resources.

Typical uses include server-side applications or applications that run on trusted devices, such as a web server or a mobile app with a secure back end.

>Public

A public client is a client application that cannot securely store its client credentials. ClosedLearn more

These credentials are typically embedded in the client application's code or configuration files, making them easily accessible to anyone who has access to the client application. When a public client initiates the OAuth flow, it relies on other mechanisms, such as redirect URIs, to establish its identity and obtain access tokens.

Typical uses include client-side applications, such as JavaScript-based applications running in a web browser or mobile apps running on end user devices, as well as on-premises applications.

Required

One of the following:

>Confidential

>Public

Grant Type

(Editable only if Client Type is Confidential.)

Determines how an application can obtain an access token to access protected resources.

>

Client Credentials

Used for server-to-server communication, where the client application sends its own credentials (client ID and client secret) to generate an access token. This is done in the back end on behalf of the client application without user intervention. (This grant type does not involve user authentication or authorization.) ClosedLearn when to use client credentials

The client credentials grant type is used when the selected Client Type is Confidential.

A typical use case is when the client application needs to access resources that are not specific to any user.

>

Authorization Code

Used primarily for server-side web applications, generating an access token using an authorization code is a two-step process that may or may not include PKCE (Proof Key for Code Exchange). ClosedLearn more about this two-step process

1.Authorization Request. The client application redirects to the authorization server's endpoint, which is a specific URL provided by the OAuth server that handles the initial step of the OAuth flow. The client application passes the necessary parameters, including the client ID, redirect URI, and scope. The end user is then presented with a login screen and logs in. After successful authentication, the authorization code is provided to the client application

2.Token Request. After the end user grants authorization, the authorization server redirects the call back to the client application's redirect URI with an authorization code. The client application then exchanges this authorization code for an access token by making a request to the authorization server's token endpoint, providing the authorization code, client ID, client secret, and redirect URI.

The Authorization Code grant type is very secure because the client application never sees the end user's credentials. This grant type also allows for the use of refresh tokens to obtain new access tokens without requiring end user interaction.

 Required

One of the following:

>Client Credentials.

•Available only for the Confidential client type.

•Default grant type for the Confidential client type.

>Authorization Code.

•Available for both the Confidential client type and Public client type.

•For the Public client type, the grant type is always Authorization Code.
Redirect URIs

(Visible only if the grant type is Authorization Code.)

A redirect URI serves as a callback URL where the end user is redirected after successfully authenticating and authorizing the client application (for example, a web page or a location in the client application). ClosedLearn more

The Redirect URI allows the client application to securely exchange the authorization code or access token with the OAuth server, enabling the client application to access protected resources on behalf of the user.

 Required

>Maximum: 5 redirect URIs

>Maximum: 255 characters

>Cannot contain the following characters: # % ^ { } | [ ] \

Web Origins

(Visible only if the grant type is Authorization Code.)

Specifies the origin of a web application (represented by a URL). Web origins are used to ensure that the client application making cross-origin requests to the authorization server is authorized to access the protected resources. ClosedLearn more

Web origins are used for redirect URI validation to ensure that the OAuth authorization request and response are sent between trusted parties with matching origins.

During the OAuth flow, when the user is redirected from the authorization server back to the OAuth client (after granting or denying access), the authorization server checks whether the redirect URI provided by the client matches one of the registered redirect URIs for that client.

The redirect URI must have the same web origin (protocol, domain, and port) as one of the registered URIs. This security mechanism ensures that the OAuth response is sent back to the intended client application.

You can mitigate Cross-Site Request Forgery (CSRF) and Cross-Origin Resource Sharing (CORS) vulnerabilities by implementing the following:

>CSRF protection: OAuth clients often use a state parameter to protect against CSRF attacks. This parameter is typically a random value generated by the client and included in the authorization request. When the authorization server redirects the user back to the client, the client checks that the returned state parameter matches the one it originally sent. This helps ensure that the authorization response comes from a legitimate source.

>CORS considerations: If the OAuth client is a web application that makes cross-origin requests to an OAuth-protected resource server (such as an API), you can use CORS headers to control which origins are allowed to access the resource server. The web origin of the OAuth client must match one of the allowed origins in the CORS policy.

 Optional

>Maximum: 5 web origins

>Maximum: 255 characters

>Must match the registered web origin of the OAuth client
PKCE Code Challenge Method

(Visible only if Client Type is Public.)

PKCE (Proof Key for Code Exchange) is an optional method that can be used in addition to the Authorization Code grant type. ClosedLearn more about PKCE and its Plain and S256 code challenges

PKCE uses a code challenge and verifier mechanism to ensure that the client making the token request is the same client that initiated the authorization process. This additional security layer helps prevent authorization code interception attacks, enhancing the security of OAuth authorization endpoints.

>Plain. The client application includes the plain code challenge in the authorization request. The code challenge is the same as the code verifier. It is recommended to use this method only when S256 is not possible.

This challenge is much less secure than S256 because if the authorization code is intercepted, the attacker can use that code to obtain an access token.

>S256. The code challenge is the SHA-256 hash of the code verifier, encoded using base64url. The client application includes the S256 code challenge in the authorization request.

This challenge provides a greater level of security compared to the plain challenge. Even if the authorization code is intercepted, the attacker cannot derive the code verifier from the code challenge.

 Optional

One of the following:

>Plain

>S256

Description

Additional information about the OAuth client.

 Optional

>Alphanumeric

>0 to 255 characters

3.Click Save. The Add OAuth Client page closes, and the OAuth client is added to the list on the OAuth Clients page.

Viewing OAuth Client Details

From the navigation pane in the vendor portal, select Identities & Access > OAuth Clients to view the OAuth Clients page. The following information can be viewed after creating an OAuth client:

>OAuth Client Details

>OAuth Client Attributes Tab

>Credentials Tab

OAuth Client Details

The following information is available for each OAuth client on the OAuth Clients page.

Attribute Description
Status

The status of the OAuth client can be one of the following:

>Enabled: The OAuth client is enabled and can be used to create access tokens.

>Disabled: The OAuth client is disabled and cannot be used to create access tokens. To use the OAuth client, you must enable it.
Request Status

On rare occasions, it may take some time to process an OAuth client request.

During this time, the Request Status attribute is added to the OAuth Client Attributes tab, informing you that the request is in progress. After the request is successfully completed, this attribute is removed.

While the request is in progress, you cannot edit or delete the OAuth client, but you can copy the OAuth client if needed.
Name

The name of the OAuth client.
Client ID

The OAuth client ID defined in Sentinel EMS. If not specified, then the value is automatically generated when the OAuth client is created. The client ID, whether user-defined or auto-generated, is automatically prefixed with 'app-'.

You can click Copy to copy the client ID to the Clipboard.
Client Type

Determines the level of trust and security associated with the client application.

>Confidential

A confidential client is a client application that can securely store and maintain its client credentials, such as a client ID and client secret. ClosedLearn more

These credentials are used to securely authenticate the client application with the authorization server during the OAuth flow, ensuring that only authorized clients can access protected resources.

Typical uses include server-side applications or applications that run on trusted devices, such as a web server or a mobile app with a secure back end.

>Public

A public client is a client application that cannot securely store its client credentials. ClosedLearn more

These credentials are typically embedded in the client application's code or configuration files, making them easily accessible to anyone who has access to the client application. When a public client initiates the OAuth flow, it relies on other mechanisms, such as redirect URIs, to establish its identity and obtain access tokens.

Typical uses include client-side applications, such as JavaScript-based applications running in a web browser or mobile apps running on end user devices, as well as on-premises applications.

Grant Type

(Editable only if Client Type is Confidential.)

Determines how an application can obtain an access token to access protected resources.

>

Client Credentials

Used for server-to-server communication, where the client application sends its own credentials (client ID and client secret) to generate an access token. This is done in the back end on behalf of the client application without user intervention. (This grant type does not involve user authentication or authorization.) ClosedLearn when to use client credentials

The client credentials grant type is used when the selected Client Type is Confidential.

A typical use case is when the client application needs to access resources that are not specific to any user.

>

Authorization Code

Used primarily for server-side web applications, generating an access token using an authorization code is a two-step process that may or may not include PKCE (Proof Key for Code Exchange). ClosedLearn more about this two-step process

1.Authorization Request. The client application redirects to the authorization server's endpoint, which is a specific URL provided by the OAuth server that handles the initial step of the OAuth flow. The client application passes the necessary parameters, including the client ID, redirect URI, and scope. The end user is then presented with a login screen and logs in. After successful authentication, the authorization code is provided to the client application

2.Token Request. After the end user grants authorization, the authorization server redirects the call back to the client application's redirect URI with an authorization code. The client application then exchanges this authorization code for an access token by making a request to the authorization server's token endpoint, providing the authorization code, client ID, client secret, and redirect URI.

The Authorization Code grant type is very secure because the client application never sees the end user's credentials. This grant type also allows for the use of refresh tokens to obtain new access tokens without requiring end user interaction.
Redirect URIs

(Visible only if the grant type is Authorization Code.)

A redirect URI serves as a callback URL where the end user is redirected after successfully authenticating and authorizing the client application (for example, a web page or a location in the client application). ClosedLearn more

The Redirect URI allows the client application to securely exchange the authorization code or access token with the OAuth server, enabling the client application to access protected resources on behalf of the user.
Web Origins

(Visible only if the grant type is Authorization Code and at least one web origin is defined.)

Specifies the origin of a web application (represented by a URL). Web origins are used to ensure that the client application making cross-origin requests to the authorization server is authorized to access the protected resources. ClosedLearn more

Web origins are used for redirect URI validation to ensure that the OAuth authorization request and response are sent between trusted parties with matching origins.

During the OAuth flow, when the user is redirected from the authorization server back to the OAuth client (after granting or denying access), the authorization server checks whether the redirect URI provided by the client matches one of the registered redirect URIs for that client.

The redirect URI must have the same web origin (protocol, domain, and port) as one of the registered URIs. This security mechanism ensures that the OAuth response is sent back to the intended client application.

You can mitigate Cross-Site Request Forgery (CSRF) and Cross-Origin Resource Sharing (CORS) vulnerabilities by implementing the following:

>CSRF protection: OAuth clients often use a state parameter to protect against CSRF attacks. This parameter is typically a random value generated by the client and included in the authorization request. When the authorization server redirects the user back to the client, the client checks that the returned state parameter matches the one it originally sent. This helps ensure that the authorization response comes from a legitimate source.

>CORS considerations: If the OAuth client is a web application that makes cross-origin requests to an OAuth-protected resource server (such as an API), you can use CORS headers to control which origins are allowed to access the resource server. The web origin of the OAuth client must match one of the allowed origins in the CORS policy.
PKCE Code Challenge Method

(Visible only if Client Type is Public and an option is selected.)

PKCE (Proof Key for Code Exchange) is an optional method that can be used in addition to the Authorization Code grant type. ClosedLearn more about PKCE and its Plain and S256 code challenges

PKCE uses a code challenge and verifier mechanism to ensure that the client making the token request is the same client that initiated the authorization process. This additional security layer helps prevent authorization code interception attacks, enhancing the security of OAuth authorization endpoints.

>Plain. The client application includes the plain code challenge in the authorization request. The code challenge is the same as the code verifier. It is recommended to use this method only when S256 is not possible.

This challenge is much less secure than S256 because if the authorization code is intercepted, the attacker can use that code to obtain an access token.

>S256. The code challenge is the SHA-256 hash of the code verifier, encoded using base64url. The client application includes the S256 code challenge in the authorization request.

This challenge provides a greater level of security compared to the plain challenge. Even if the authorization code is intercepted, the attacker cannot derive the code verifier from the code challenge.
Description

(Visible only if defined.)

Additional information about the OAuth client.
Creation Date The date and time that the OAuth client was created in MM-DD-YYYY HH:MM format.
Last Modified Date

(Visible only if the OAuth client was modified.)

The date and time that changes were last made to the OAuth client in MM-DD-YYYY HH:MM format.

OAuth Client Attributes Tab

The following table explains the attributes displayed in the OAuth Client Attributes tab when you expand a line item for an OAuth client.

Attribute Description
Status

The status of the OAuth client can be one of the following:

>Enabled: The OAuth client is enabled and can be used to create access tokens.

>Disabled: The OAuth client is disabled and cannot be used to create access tokens. To use the OAuth client, you must enable it.
Request Status

On rare occasions, it may take some time to process an OAuth client request.

During this time, the Request Status attribute is added to the OAuth Client Attributes tab, informing you that the request is in progress. After the request is successfully completed, this attribute is removed.

While the request is in progress, you cannot edit or delete the OAuth client, but you can copy the OAuth client if needed.
Name

The name of the OAuth client.
Client ID

The OAuth client ID defined in Sentinel EMS. If not specified, then the value is automatically generated when the OAuth client is created. The client ID, whether user-defined or auto-generated, is automatically prefixed with 'app-'.

You can click Copy to copy the client ID to the Clipboard.
Client Type

Determines the level of trust and security associated with the client application.

>Confidential

A confidential client is a client application that can securely store and maintain its client credentials, such as a client ID and client secret. ClosedLearn more

These credentials are used to securely authenticate the client application with the authorization server during the OAuth flow, ensuring that only authorized clients can access protected resources.

Typical uses include server-side applications or applications that run on trusted devices, such as a web server or a mobile app with a secure back end.

>Public

A public client is a client application that cannot securely store its client credentials. ClosedLearn more

These credentials are typically embedded in the client application's code or configuration files, making them easily accessible to anyone who has access to the client application. When a public client initiates the OAuth flow, it relies on other mechanisms, such as redirect URIs, to establish its identity and obtain access tokens.

Typical uses include client-side applications, such as JavaScript-based applications running in a web browser or mobile apps running on end user devices, as well as on-premises applications.

Grant Type

(Editable only if Client Type is Confidential.)

Determines how an application can obtain an access token to access protected resources.

>

Client Credentials

Used for server-to-server communication, where the client application sends its own credentials (client ID and client secret) to generate an access token. This is done in the back end on behalf of the client application without user intervention. (This grant type does not involve user authentication or authorization.) ClosedLearn when to use client credentials

The client credentials grant type is used when the selected Client Type is Confidential.

A typical use case is when the client application needs to access resources that are not specific to any user.

>

Authorization Code

Used primarily for server-side web applications, generating an access token using an authorization code is a two-step process that may or may not include PKCE (Proof Key for Code Exchange). ClosedLearn more about this two-step process

1.Authorization Request. The client application redirects to the authorization server's endpoint, which is a specific URL provided by the OAuth server that handles the initial step of the OAuth flow. The client application passes the necessary parameters, including the client ID, redirect URI, and scope. The end user is then presented with a login screen and logs in. After successful authentication, the authorization code is provided to the client application

2.Token Request. After the end user grants authorization, the authorization server redirects the call back to the client application's redirect URI with an authorization code. The client application then exchanges this authorization code for an access token by making a request to the authorization server's token endpoint, providing the authorization code, client ID, client secret, and redirect URI.

The Authorization Code grant type is very secure because the client application never sees the end user's credentials. This grant type also allows for the use of refresh tokens to obtain new access tokens without requiring end user interaction.
Redirect URIs

(Visible only if the grant type is Authorization Code.)

A redirect URI serves as a callback URL where the end user is redirected after successfully authenticating and authorizing the client application (for example, a web page or a location in the client application). ClosedLearn more

The Redirect URI allows the client application to securely exchange the authorization code or access token with the OAuth server, enabling the client application to access protected resources on behalf of the user.
Web Origins

(Visible only if the grant type is Authorization Code and at least one web origin is defined.)

Specifies the origin of a web application (represented by a URL). Web origins are used to ensure that the client application making cross-origin requests to the authorization server is authorized to access the protected resources. ClosedLearn more

Web origins are used for redirect URI validation to ensure that the OAuth authorization request and response are sent between trusted parties with matching origins.

During the OAuth flow, when the user is redirected from the authorization server back to the OAuth client (after granting or denying access), the authorization server checks whether the redirect URI provided by the client matches one of the registered redirect URIs for that client.

The redirect URI must have the same web origin (protocol, domain, and port) as one of the registered URIs. This security mechanism ensures that the OAuth response is sent back to the intended client application.

You can mitigate Cross-Site Request Forgery (CSRF) and Cross-Origin Resource Sharing (CORS) vulnerabilities by implementing the following:

>CSRF protection: OAuth clients often use a state parameter to protect against CSRF attacks. This parameter is typically a random value generated by the client and included in the authorization request. When the authorization server redirects the user back to the client, the client checks that the returned state parameter matches the one it originally sent. This helps ensure that the authorization response comes from a legitimate source.

>CORS considerations: If the OAuth client is a web application that makes cross-origin requests to an OAuth-protected resource server (such as an API), you can use CORS headers to control which origins are allowed to access the resource server. The web origin of the OAuth client must match one of the allowed origins in the CORS policy.
PKCE Code Challenge Method

(Visible only if Client Type is Public and an option is selected.)

PKCE (Proof Key for Code Exchange) is an optional method that can be used in addition to the Authorization Code grant type. ClosedLearn more about PKCE and its Plain and S256 code challenges

PKCE uses a code challenge and verifier mechanism to ensure that the client making the token request is the same client that initiated the authorization process. This additional security layer helps prevent authorization code interception attacks, enhancing the security of OAuth authorization endpoints.

>Plain. The client application includes the plain code challenge in the authorization request. The code challenge is the same as the code verifier. It is recommended to use this method only when S256 is not possible.

This challenge is much less secure than S256 because if the authorization code is intercepted, the attacker can use that code to obtain an access token.

>S256. The code challenge is the SHA-256 hash of the code verifier, encoded using base64url. The client application includes the S256 code challenge in the authorization request.

This challenge provides a greater level of security compared to the plain challenge. Even if the authorization code is intercepted, the attacker cannot derive the code verifier from the code challenge.
Description

(Visible only if defined.)

Additional information about the OAuth client.
Creation Date The date and time that the OAuth client was created in MM-DD-YYYY HH:MM format.
Last Modified Date

(Visible only if the OAuth client was modified.)

The date and time that changes were last made to the OAuth client in MM-DD-YYYY HH:MM format.

Credentials Tab

The following table explains the attributes displayed in the Credentials tab when you expand a line item for an OAuth client whose Client Type is Confidential.

Attribute Description
Client Authenticator The type of data used to authenticate the OAuth client. Currently, the value is always Client ID & Client Secret.
Client ID

The OAuth client ID defined in Sentinel EMS. If not specified, then the value is automatically generated when the OAuth client is created. The client ID, whether user-defined or auto-generated, is automatically prefixed with 'app-'.

You can click Copy to copy the client ID to the Clipboard.
Client Secret

Relevant only for confidential clients.

A secret used in the authentication process to enable the application to communicate with the authorization server.

You can click Copy to copy the client secret to the Clipboard.

Actions for OAuth Clients

The following table lists the actions available for OAuth client:

Action Description
Edit button Edit

Updates the information of an existing OAuth client. For details on editing OAuth clients, see Editing an Entity.
Copy button Copy

Duplicates an existing OAuth client, enabling you to edit the copy and create a new OAuth client.
Disable button Disable

Disables an OAuth client.

Delete button Delete

Deletes an OAuth client.