OAuth2 authentication and authorization

The OAuth 2.0 Authorization Code Grant Flow is a secure method for an application to get authorized access to protected resources. This process involves exchanging an authorization code for an access token, which acts as a key to the protected resources.

In Itential, this flow lets you configure integrations that securely connect to services using OAuth 2.0. The Itential Platform automatically manages the entire exchange process, from getting the initial authorization code to automatically refreshing the access token.

Configure OAuth

This section provides configuration examples for the most common OAuth 2.0 use cases.

Before you begin

Obtain the client ID and secret from your OAuth provider
Identify the authorization and token URLs for your OAuth provider
Determine the required scopes for your integration
Configure the redirect URI in your OAuth provider settings

Basic OAuth 2.0

This is the most common use case, covering the essentials of setting up a connection that requires a user's consent.

To set up basic OAuth 2.0:

Define your OAuth 2.0 schema: In your integration's OpenAPI definition, configure the securitySchemes object with type: oauth2 and flows: authorizationCode.
Add URLs and scopes: Specify the authorizationUrl (where users grant permission) and the tokenUrl (where Itential exchanges the code for a token). List the available scopes that your provider offers.

{
  "components": {
    "securitySchemes": {
      "OAuth2Security": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://account.box.com/api/oauth2/authorize",
            "scopes": {
              "root_readonly": "Read all files and folders in Box",
              "root_readwrite": "Read and write all files and folders in Box"
            },
            "tokenUrl": "https://api.box.com/oauth2/token"
          }
        }
      }
    }
  }
}

Configure the integration instance: In Itential's Admin Essentials, provide the client_id and client_secret from your OAuth 2.0 provider.
Set the redirect URI: On your OAuth 2.0 provider's side, configure the redirect URI to {{iap}}/admin/oauth/. For example, if your Itential Platform is at https://itential.iap.com/, the redirect URI is https://itential.iap.com/admin/oauth/. Don't forget the trailing slash.
Specify scopes: Optionally, set the scope string in the integration instance to request a subset of permissions. Use a space-separated string, like root_readonly manage_app_users.

OAuth 2.0 with refresh tokens

This scenario is automatically handled by the Itential Platform. If your provider sends a refresh token along with the access token, Itential stores it and uses it to automatically renew the session when the access token expires. No extra configuration is needed on the Itential side.

Follow the same steps as the basic setup. Ensure that your token URL is correct and that the OAuth 2.0 provider is configured to issue refresh tokens.

Automatic reauthentication

If your authentication server provides a refresh token, Itential automatically handles reauthentication using your configured token URL.

OAuth 2.0 with custom headers or parameters

If your OAuth 2.0 provider requires custom headers or parameters during the token exchange, you may need to modify the OpenAPI specification. Contact Itential Support for advanced configuration options.

Authorization code flow schema

An example import of an Integration Model with an authorizationCode type in its securitySchemes is presented below.

{
  ...
  "components": {
    "securitySchemes": {
      "OAuth2Security": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://account.box.com/api/oauth2/authorize",
            "scopes": {
              "manage_app_users": "Provision and manage app users",
              "manage_data_retention": "Manage data retention polices",
              "manage_enterprise_properties": "Manage enterprise properties",
              "manage_groups": "Manage an enterprise's groups",
              "manage_legal_hold": "Manage Legal Holds",
              "manage_managed_users": "Provision and manage managed users",
              "manage_webhook": "Create webhooks programmatically through the API",
              "root_readonly": "Read all files and folders stored in Box",
              "root_readwrite": "Read and write all files and folders stored in Box"
            },
            "tokenUrl": "https://api.box.com/oauth2/token"
          }
        }
      }
    }
  }
}

For "Auth Code Flow" the given type of the scheme must be oauth2 and it must have an authorizationCode object within the flows object. The authorizationUrl is the URL the user will be sent to in order to authorize the grant (i.e., retrieve the auth code). That URL will then redirect the user back to Itential Platform with an authorization code, which Itential Platform will automatically exchange at the tokenUrl for an access token.

The scopes is an enumerated list of scope_name: description of all scopes the OAuth provider offers, from which the user may choose a subset for the access token. From Admin Essentials, the user can declare this subset in the configuration of the integration instance.

Set up the integration instance

The framework of an integration instance is shown in Figure 1. To configure, you need to give the integration the client_id and client_secret from your OAuth2 provider.

Make sure you supply the OAuth provider with the redirect_uri of {{iap}}/admin/oauth/. For example, if Itential Platform is at https://itential.iap.com/, then you need to set the redirect_uri as https://itential.iap.com/admin/oauth/ (Reminder: Do not forget the trailing /).

Optionally, specify your desired scopes of the access token in the scope as a space-separated string. Using the schema model above, a valid scope setting could be manage_app_users, manage_data_retention and manage_webhook.

Once you have configured your integration instance, click Save to retain your changes.

Figure 1: Integration Auth Code Flow
Figure 1 Integration Auth Code Flow

Retrieve an access token

To obtain an access token, click the Get Access Token button (Figure 2) which sends you to the OAuth2 provider you are interfacing with to "Approve Access". Remember, you must supply the OAuth2 provider with the redirect URL of {{iap}}/admin/oauth/. The example in Figure 3 uses the BoxDev OAuth2 provider, but this works for any OAuth2 provider.

Figure 2: Get Access Token

Figure 3: OAuth2 Provider Confirmation

Once access is granted, you are redirected back to Itential Platform and a success notification will display (Figure 4) to confirm the access token was retrieved.

Figure 4: Retrieved Access Token
Success Banner - Access Token Retrieved

Troubleshooting

If you fail to retrieve the access token, there are a few likely reasons:

Invalid client_id or client_secret. Double-check with your OAuth provider that these values are correct.
Invalid scope. If you attempt to request a scope that does not exist, the OAuth provider may outright refuse your request.
Invalid token_url. You may change the token_url for a given instance after creation. If it points to a different URL than expected, then the access token request will fail.