Establishing an OAuth Provider

Overview

OAuth is an open standard for providing secured delegated access. In short, Decisions can take actions or access resources from a server on behalf of the user without them having to share their credentials. The identity provider (IdP) can issue tokens to Decisions with the user's approval. Before using an API with OAuth, two things must first occur an OAuth Provider must be established, and an OAuth Token must be created. The following document discusses the method used to set up an OAuth Provider for proper Integration with Decisions.

The following document ONLY discusses Provider setup. For information on Creating Tokens for an OAuth Integration, see Creating OAuth Tokens.

The following discusses the required configurations for an OAuth Provider. For assistance in finding the specific parameters for an OAuth Provider, please seek documentation or Developer settings for that specific service integrated with Decisions.

Adding a Provider

To gain access to OAuth Settings and the ability to create an OAuth Token, users must first establish an OAuth Provider. This setting is established in the System > Integrations > Providers Folder by selecting the ADD OAUTH PROVIDER button within the Folder.

Setting	Description
Name	Name to distinguish the OAuth provider.
Description	A brief description or explanation of the OAuth provider. This helps users understand the purpose or functionality of the OAuth provider when configuring it within the platform.
OAuth Version	The version of OAuth to use. OAuth1x - The first version of OAuth follows a different authentication Flow. OAuth2 - The newer version is widely used for modern authentication and authorization. Note: Besides providing different configuration options, it is important to ensure that the selected OAuth version is compatible with the OAuth Server. For more information, see the documentation for the specific Server being integrated with or that particular Server's Settings or the Key/Token locations for the App. Though both OAuth1x and OAuth2 have nearly identical Provider Setting options, selecting OAuth2 provides a few additional options for configuration.
Token Request URL	The URL is where the platform requests a temporary token during the OAuth1 authentication process.
Authorize URL	The URL where the platform redirects the user for authorization. Once the user grants permission, the platform receives a verifier code.
Access Token URL	The URL where the platform exchanges the temporary token and the verifier code for a long-lived access token during the OAuth1x authentication process.
Default Consumer Key	The default consumer key is associated with the platform. It identifies the platform when making requests to the OAuth provider.
Default Consumer Secret Key	It is used, along with the consumer key, to authenticate the platform with the OAuth provider.
Get Base API URL from Authorization Response	If selected, the platform will retrieve the base API URL from the authorization response in OAuth2. This helps identify the API endpoints for accessing resources.
Token Refresh URL (Optional)	If provided, the URL where the platform can request a new access token using a refresh token, allowing extended access without user re-authorization in OAuth2.
Callback URL	The URL where the user is redirected after successful authorization in OAuth2, along with the authorization code. Example: {BasePortalURL}/HandleTokenResponse
Use Proof Key for Code Exchange (PKCE)	If selected, the platform uses PKCE to enhance security during the authorization code exchange process in OAuth2.
URL Encode Refresh Token During Refresh	If selected, the platform URL encodes the refresh token when requesting a new access token during token refresh in OAuth2.
Omit Code During Refresh	If selected, the platform omits the authorization code when requesting a new access token with a refresh token during token refresh in OAuth2.
Client Authentication Type	The method used for client authentication when communicating with the OAuth provider. Options: Client Secret (POST), Private Key JWT.
Private Key JWT	The platform uses a JSON Web Token (JWT) with a private key for client authentication in OAuth2.
Get a Private Key from Path	The platform obtains the private key from the specified path or location in OAuth2 if selected.
Private Key File	Upload the private key file for JWT-based authentication in OAuth2 in the file upload area.
Private Key Password	If the private key is password-protected, enter the password to access it in OAuth2.
Private Key Signing Algorithm	The algorithm used to sign the JWT with the private key in OAuth2. RS256, RS384, and RS512 represent different signature strengths.
Key Identifier (KID)	A unique identifier that helps match the correct key or certificate used for secure communication with the OAuth provider.

Setting

Description

Name

Name to distinguish the OAuth provider.

Description

A brief description or explanation of the OAuth provider. This helps users understand the purpose or functionality of the OAuth provider when configuring it within the platform.

OAuth Version

The version of OAuth to use.
OAuth1x - The first version of OAuth follows a different authentication Flow.
OAuth2 - The newer version is widely used for modern authentication and authorization.

Note: Besides providing different configuration options, it is important to ensure that the selected OAuth version is compatible with the OAuth Server. For more information, see the documentation for the specific Server being integrated with or that particular Server's Settings or the Key/Token locations for the App.

Though both OAuth1x and OAuth2 have nearly identical Provider Setting options, selecting OAuth2 provides a few additional options for configuration.

Token Request URL

The URL is where the platform requests a temporary token during the OAuth1 authentication process.

Authorize URL

The URL where the platform redirects the user for authorization. Once the user grants permission, the platform receives a verifier code.

Access Token URL

The URL where the platform exchanges the temporary token and the verifier code for a long-lived access token during the OAuth1x authentication process.

Default Consumer Key

The default consumer key is associated with the platform. It identifies the platform when making requests to the OAuth provider.

Default Consumer Secret Key

It is used, along with the consumer key, to authenticate the platform with the OAuth provider.

Get Base API URL from Authorization Response

If selected, the platform will retrieve the base API URL from the authorization response in OAuth2. This helps identify the API endpoints for accessing resources.

Token Refresh URL (Optional)

If provided, the URL where the platform can request a new access token using a refresh token, allowing extended access without user re-authorization in OAuth2.

Callback URL

The URL where the user is redirected after successful authorization in OAuth2, along with the authorization code.
Example: {BasePortalURL}/HandleTokenResponse

Use Proof Key for Code Exchange (PKCE)

If selected, the platform uses PKCE to enhance security during the authorization code exchange process in OAuth2.

URL Encode Refresh Token During Refresh

If selected, the platform URL encodes the refresh token when requesting a new access token during token refresh in OAuth2.

Omit Code During Refresh

If selected, the platform omits the authorization code when requesting a new access token with a refresh token during token refresh in OAuth2.

Client Authentication Type

The method used for client authentication when communicating with the OAuth provider. Options: Client Secret (POST), Private Key JWT.

Private Key JWT

The platform uses a JSON Web Token (JWT) with a private key for client authentication in OAuth2.

Get a Private Key from Path

The platform obtains the private key from the specified path or location in OAuth2 if selected.

Private Key File

Upload the private key file for JWT-based authentication in OAuth2 in the file upload area.

Private Key Password

If the private key is password-protected, enter the password to access it in OAuth2.

Private Key Signing Algorithm

The algorithm used to sign the JWT with the private key in OAuth2.
RS256, RS384, and RS512 represent different signature strengths.

Key Identifier (KID)

A unique identifier that helps match the correct key or certificate used for secure communication with the OAuth provider.

Description	Version	Developer Task
Added ability to use a JSON Web Token (JWT) with a private key for client authentication in OAuth2	8.13	[DT-038223]
Add Optional KID Value Into Header of Generated JWT From OAuth Integration Settings	8.15	[DT-038962]

Description

Version

Developer Task

Added ability to use a JSON Web Token (JWT) with a private key for client authentication in OAuth2

8.13

[DT-038223]

Add Optional KID Value Into Header of Generated JWT From OAuth Integration Settings

8.15

[DT-038962]

Establishing an OAuth Provider

Overview

Adding a Provider

OAuth Provider Settings

OAuth Provider Settings

Feature Changes

What's Next