Configure OAuth Apps in Identity Providers for External OAuth Integrations

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

This topic provides a step-by-step process for setting up an OAuth application in different identity providers, such as Entra ID, Auth0, and Okta, for an external OAuth integration:

• Manage Tokens in Microsoft Entra ID

• Manage Tokens in Auth0

• Manage Tokens in Okta

Manage Tokens in Microsoft Entra ID

Create an App Registration

First, you need to create an identity for your application.

1. Log in to the Microsoft Entra admin center.

2. Navigate to Identity(Microsoft Entra ID) > Manage > Applications > App registrations > New registration.

3. Name: Enter a descriptive name.

4. Supported account types: Select Accounts in this organizational directory only (Single tenant) unless you need multi-tenant support.

5. Redirect URI: Select Web and enter your application’s callback URL (for example, https://localhost:5001/signin-oidc).

   Note

   This is required for the Authorization Code flow.

6. Click Register.

Expose an API & Define Scopes

To ensure the token has your specific audience (aud), you must expose an API:

1. In your app registration, go to Expose an API.

2. Click Add next to Application ID URI. It usually defaults to api://<client-id>. You can leave it or give it a friendly name. This URI becomes your aud value.

3. Click Add a scope:

   • Scope name: alation_access:role_any

   • Who can consent: Admins and users.

   • Admin consent display name: Access the API as a user.

   • State: Enabled.

4. Click Add scope.

Configure Grant Flows

Authorization Code Flow (User + App)

1. Go to Authentication.

2. Under Implicit grant and hybrid flows, ensure that both boxes (Access tokens and ID tokens) remain unchecked (standard Authorization Code flow with PKCE is more secure).

3. Ensure your Redirect URI is correct.

Client Credentials Flow (Machine-to-Machine)

1. Go to Certificates & secrets.

2. Select New client secret, add a description, and set an expiration.

3. Copy the value immediately. You will not see it again.

4. Go to API permissions > Add a permission > APIs my organization uses.

5. Select your own app and choose Delegated permissions.

6. Select your scope and click Add permissions.

7. Click Grant admin consent for [Your Org]. (Without this, the client credentials flow will fail.)

Collect the Endpoint Information

Your application needs to know where to send requests to get tokens.

1. Go to the Overview page of your app registration.

2. Click on the Endpoints tab at the top.

3. You will see a drawer open with several URLs. You need:

   • OAuth 2.0 authorization endpoint (v2): For the Auth Code flow.

   • OAuth 2.0 token endpoint (v2): For both flows to exchange codes/secrets for tokens.

Example Curl Commands to Generate Tokens

Client Credentials Grant

curl --location 'https://login.microsoftonline.com/734e600a-8184-4d74-9548-b1dcf317f0ff/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: *****' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=api://aae36d60-fe54-4a9d-975c-17978a43a73f/.default'

Authorization Code Grant After Generating the Code

• Use a unique api scope in the authorize request if you need only an access token. For example, api://aae37d40-fe54-4a8d-974c-17969a43a73f/alation_access:role_any

• Use a unique api and profile offline_access scope if you need an access token and refresh token. For example, api://aae37d40-fe54-4a8d-974c-17969a43a73f/alation_access:role_any openid profile offline_access

curl --location 'https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ****' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code_verifier=<code_verifier>' \
--data-urlencode 'redirect_uri=<redirect_uri>' \
--data-urlencode 'code=<code>'

Manage Tokens in Auth0

Create an Application

First, define the app that will perform the login:

1. Log in to the Auth0 Dashboard.

2. Go to Applications > Applications > Create Application.

3. Enter a descriptive Name.

4. Application Type: Select Regular Web Application. This allows for both Auth Code and Client Credentials flows.

5. Under the Settings tab:

   • Allowed Callback URLs: Enter your app’s redirect URI (for example, https://localhost:5001/callback).

   • Allowed Logout URLs: Enter your logout redirect (optional).

6. Scroll down and click Save Changes.

7. Record your Client ID and Client Secret, as you will need these for both flows.

Create and Expose the API

In Auth0, the audience (aud) is strictly tied to an API object.

1. Go to Applications > APIs > Create API.

2. Enter a name.

3. Identifier: Enter a unique URI (https://<client_id>). Example: https://KF2SUq5h7a9DUoF7z4tsIQdYoYrdpLvD. This is your aud value.

4. Click Create.

5. Go to the Permissions tab and define your scopes:

   • Permission (Scope): alation_access:role_any

   • Description: Access as any role.

   • Click Add.

6. To use refresh tokens, go to the Settings tab of this API and toggle Allow Offline Access to ON.

Configure Grant Flows

Authorization Code Flow (User Login)

To ensure the token has your API as the audience and includes a refresh token:

1. In your code, your authorization request must include:

   • audience=https://<client_id>

     • Example: https://KF2SUq5h7a9DUoF7z4tsIQdYoYrdpLvD (The API identifier from Create and Expose the API).

   • scope=openid profile alation_access:role_any offline_access (Space-separated).

Client Credentials Flow (Machine-to-Machine)

1. Go to Applications > APIs and select your API.

2. Click the Machine to Machine Applications tab.

3. Find your app in the list and toggle the switch to Authorized.

4. Select the specific scopes (alation_access:role_any) you want this app to have.

5. Click Update.

Collect the Endpoint Information

Auth0 follows the OIDC standard for discovery.

1. Go to Applications > Applications and select your app.

2. Scroll to the bottom and click Advanced Settings.

3. Select the Endpoints tab.

   • OAuth Authorization Endpoint: For Auth Code flow.

   • OAuth Token Endpoint: For both flows.

   • OpenID Configuration: https://<your_domain>/.well-known/openid-configuration. This JSON file lists every URL your app needs.

Adding a Custom Claim to the Token to Map the Username in Alation

1. Go to Actions > Library > Build Custom.

2. Enter a name, for example, Add Email to Access Token.

3. Trigger: Login / Post Login.

4. Paste this code into the editor.

5. Click Deploy.

6. Go to Actions > Triggers > Login/post-login.

7. Drag your new Add Email action into the flow diagram between Start and Complete.

8. Click Apply.

Important

In Auth0, custom claims in the access token must be name-spaced with a URI (for example, https://myapp.com/email) to prevent conflict with OIDC standard claims.

The namespace should be your identifier, for example: https://KF2SUq5h7a9DUoF7z4tsIQdYoYrdpLvD

exports.onExecutePostLogin = async (event, api) => {
    const namespace = 'https://my-api.example.com'; // Use your API Identifier
    if (event.user.email)
    {
      api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
      }
};

Example Curl Commands to Generate Tokens

Client Credentials Grant

curl --location 'https://dev-r740qkog.us.auth0.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ****' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=https://KF5SUq5h7a3DUoF7z9tsIQdYoYrdpLvD'

Authorization Code Grant After Generating the Code

• The scope in the authorize request should be openid profile email alation_access:role_any offline_access

• The authorize request should have the audience as one of the parameters

curl --location 'https://dev-r740qkog.us.auth0.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ****' \
--data-urlencode 'code_verifier=<code_verifier>' \
--data-urlencode 'code=<code>' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://oauthdebugger.com/debug'

Manage Tokens in Okta

Configuring Okta for both Authorization Code and Client Credentials flows is unique because, unlike Entra ID, Okta strongly separates “internal” org tokens from “API-facing” tokens using Custom Authorization Servers.

Create an Application

1. Log in to your Okta Admin Console.

2. Go to Applications > Applications > Create App Integration.

3. Select OIDC - OpenID Connect and Web Application. Click Next.

4. Grant type: Check both Authorization Code and Client Credentials.

   • Also check Refresh Token if you want to use offline_access.

5. Sign-in redirect URIs: Enter your app’s callback (for example, https://localhost:5001/callback).

6. Assignments: Select Allow everyone in your organization to access for testing.

7. Click Save and copy your Client ID and Client Secret.

Set Up the Authorization Server (Exposing the API)

In Okta, to get a custom audience (aud) and custom scopes in a JWT, you must use a Custom Authorization Server (often called API Access Management).

1. Go to Security > API.

2. You will see a default server. You can use it or click Add Authorization Server to create a new one.

3. Audience: Set this to your unique API identifier (for example, api://my-unique-api). This value will be the aud in your token.

4. Click Save.

5. Go to the Scopes tab and click Add Scope:

   1. Name: alation_access:role_any

   2. Click Create.

Configure Token Claims (Getting Email in the Token)(optional)

By default, Okta’s access tokens are slim. To add the user’s email:

1. In your Authorization Server, go to the Claims tab.

2. Click Add Claim.

3. Name: email.

4. Include in token type: Select Access Token.

5. Value type: Select Expression.

6. Value: user.email.

7. Include in: Select Any scope (or limit it to the email scope).

8. Click Create.

Define Access Policies (Crucial for Client Credentials)

Client Credentials flow in Okta will fail unless an Access Policy specifically allows it.

1. In your Authorization Server, go to the Access Policies tab.

2. Click Add Policy (for example, M2M Policy) and assign it to All Clients.

3. Click Add Rule under that policy:

   1. Rule Name: Allow Client Credentials.

   2. IF Grant type is: Check Client Credentials.

   3. AND Scopes requested: Select Any scopes or your specific custom scope.

   4. Click Create Rule.

Collect the Endpoint Information

1. In Security > API, click on your Authorization Server.

2. Go to the Settings tab.

3. Copy the Metadata URI.

   • It looks like: https://{yourOktaDomain}/oauth2/{authServerId}/.well-known/oauth-authorization-server

4. Open that URL in your browser to find the token_endpoint and authorization_endpoint.

Example Curl Commands to Generate Tokens

Client Credentials Grant

curl --location 'https://integrator-5651799.okta.com/oauth2/auszbh8wouJpEl3Xp697/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ****' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=alation_access:role_any'

Authorization Code Grant After Generating the Code

The scope in the authorize request should be openid email alation_access:role_any offline_access.

curl --location 'https://integrator-5651799.okta.com/oauth2/auszbh8wouJpEl3Xp697/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ****' \
--data-urlencode 'code_verifier=<code>' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://oauthdebugger.com/debug' \
--data-urlencode 'code=<code>'