OAuth 2.0

Your instance supports Open Authorization (OAuth) 2.0.

Configure OAuth 2.0 settings for these scenarios:

  • OAuth external client scenario: Your instance provides an endpoint for third-party clients to pull data from the instance.
  • OAuth provider scenario: Your instance pulls data from a third-party provider.
Attention: Using OAuth to allow your users to authenticate to the instance is not currently supported.

Both the simple security and high security frameworks support OAuth 2.0. High Security is recommended. See High Security Settings for information about which versions have high security already active and how to activate high security. You must have the security_admin role to manage the OAuth integration.

OAuth 2.0 concepts

The following table describes the key concepts of the OAuth 2.0 implementation.

Table 1. OAuth concepts
Concept Description
Resource Owner An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user. The resource owner is always a user account.
Client An application making protected resource requests on behalf of the resource owner and with its authorization.
Resource Server The server hosting the protected resources, capable of accepting and responding to protected resource requests.
Authorization Server The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.
Authorization Request The permission a client needs to access a protected resource. The authorization request is always an HTTP POST message containing the ID of the client acting on the resource owner's behalf and credentials authorizing the request.
Authorization Grant A credential representing the resource owner's authorization to access a resource. The authorization grant is either a user's login credentials or a refresh token.
Access Token A secure string that a client uses to access protected resources. An instance issues access tokens to clients that have a valid authorization grant. Each access token has a specific scope, lifespan, and other attributes.

By default, an instance issues access tokens with a 30 minute lifespan in the scenario where the instance is the OAuth provider. For third-party tokens, 30 days.

Refresh Token A credential that a client uses to obtain new access tokens without requiring additional user authorization. An instance issues a refresh token to a client when it is first authorized to have an access token.

By default, an instance issues refresh tokens with a 100 day lifespan in the scenario where the instance is the OAuth provider. For third-party tokens, 365 days.

OAuth process

In general, an instance uses the following workflow to authorize access to an OAuth-protected resource.

  1. The client requests authorization from the resource owner through the authorization server and the resource owner's login credentials or an authorization code.
  2. The authorization server provides the client with an authorization grant on behalf of the resource owner.
  3. The client requests an access token from the authorization server using the authorization grant. If valid, the authorization server grants the client an access token and refresh token.
  4. The client uses the access token to request the protected resource.
  5. The resource server validates the access token.
  6. If valid, the resource server grants the client access to the protected resource.

OAuth grant type

Grant type refers to
  • Authorization code: the consumer sends an authorization code to get an access token. You can specify this by creating an OAuth profile. This is also referred to as OAuth code flow.
  • Resource owner password credentials: the consumer of the resource already has the user credentials to get the access token. This is also referred to as password flow.

    The OAuth application supports both grant types.

Storage of authentication credentials

The OAuth client secret is stored as a password2 type field, which is encrypted in Triple DES. User passwords, which are used to check incoming endpoint requests, are stored as a hash value in the User table in a password type field (SHA 256).