OAuth2 Authentication & Authorization

Itential users can now import and use Integration Models that support OAuth 2.0 Authorization Code Grant Flow ("auth code flow"), which enables a client application to obtain authorized access to secured resources via access token.

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.

How to 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

How to 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

Troubleshooting Common Errors

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.