Configure External OAuth Integrations

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Applies from 2026.2.1.0

Many organizations are building their own tools and integrations using Alation’s public APIs. If you are doing this, you’ll need a way to authenticate those tools so they can “talk” to Alation securely. Your organization may have strict security rules requiring all such connections to be managed in one place, usually through a central identity provider (IdP) like Microsoft Entra ID or Okta.

To support this, Alation can be integrated with your IdP to validate the OAuth 2.0 tokens. This means that inside Alation, you don’t have to create OAuth client apps and store sensitive client identifiers and secrets. Instead, you use your existing security controls to manage access, rotate credentials, and keep all security logs in one central location.

In this configuration, Alation functions as an OAuth resource server. Rather than managing the authentication handshake itself, Alation validates and verifies incoming JWT tokens (JSON Web Tokens) using your IdP’s public JWKS (JSON Web Key Set) endpoint.

Note

Currently, external OAuth tokens are supported only for Alation’s core platform public endpoints. Core public endpoints refer to the majority of APIs that interface directly with the Alation data catalog. This functionality does not include support for the Alation AI API at this time.

You need the role of Server Admin to configure an external OAuth integration.

In this topic:

• Supported OAuth Types

• Supported Identity Providers

• Example Use Cases

• The External OAuth Authentication and Authorization Flow

• Configuration Process Overview

• Step 1: Register an Application in Your IdP

• Step 2: Create an External Token Validation Profile in Alation

• Edit an External Token Validation Profile

• Migrate to External Token Management

Supported OAuth Types

Alation supports two distinct OAuth 2.0 flow types for external token validation, allowing you to secure both automated and interactive access patterns within the integrations:

• Machine-based flows (Machine-to-Machine) are designed for service-to-service integrations where a system user, such as a script or data pipeline, performs actions without human intervention.

• User-initiated flows enable applications to act on behalf of a specific Alation user, ensuring that the API session maintains the appropriate end-user context and individual permission levels.

When setting up an external OAuth profile, Server Admins can select the flow type required for their specific integration.

Supported Identity Providers

Alation supports several identity providers (IdPs). Support levels vary based on official certification and testing.

Supported Identity Providers

Provider	Support Level	Description
Microsoft Entra ID	Supported and certified	Fully tested and certified for seamless integration with Alation’s external token validation.
Okta	Supported	Supported
Auth0	Supported	Supported
Other JWT-based IdPs	Best effort	Other providers may function if they adhere to standard OAuth 2.0 and JWT specifications, but they are not officially supported or certified.

Example Use Cases

By transitioning to IdP-managed OAuth client validation, organizations can solve critical security and operational challenges. This alignment ensures that Alation adheres to the same rigorous standards as the rest of your application stack.

• Centralize Credential Lifecycle Management

• Enforce Enterprise-Wide Conditional Access

• Unify Auditing and Compliance

• Accelerate Incident Response and Revocation

• Align with Zero-Trust Architecture

Centralize Credential Lifecycle Management

• Objective: Eliminate the administrative burden of manual credential rotation.

• Outcome: Security teams rotate secrets and certificates entirely within the IdP. Since Alation does not store these credentials, the risk of local credential leakage is removed, and application teams no longer need to perform manual updates within the Alation UI.

Enforce Enterprise-Wide Conditional Access

• Objective: Apply high-level security policies to API and integration access.

• Outcome: Organizations can enforce Multi-Factor Authentication (MFA), IP allow-listing, and device trust requirements directly at the IdP level. This ensures OAuth clients are subject to the same access controls as standard users.

Unify Auditing and Compliance

• Objective: Create a single, authoritative audit trail for all authentication events.

• Outcome: All client registrations and credential events, including creation, rotation, and deactivation, are consolidated into the IdP’s centralized audit logs, simplifying compliance reporting and forensic analysis.

Accelerate Incident Response and Revocation

• Objective: Instantly terminate access during a security event.

• Outcome: Security teams can revoke or disable an OAuth client directly within the IdP. Access can be cut off immediately across all Alation entry points without requiring a separate login or configuration change inside Alation.

Align with Zero-Trust Architecture

• Objective: Shift away from locally issued application credentials.

• Outcome: IdP-managed clients ensure that every API request is authenticated and authorized via centrally governed identity policies, fulfilling the verify explicitly principle of Zero-Trust models.

The External OAuth Authentication and Authorization Flow

This section outlines the OAuth authentication and authorization flow between the identity provider (IdP), the client application, and Alation.

Initial Configuration

Client authentication requires prior OAuth integration setup:

1. An IdP administrator registers a client application in the IdP.

2. An Alation Server administrator configures the external OAuth integration in Alation using the IdP details.

3. Alation stores the OAuth profile configuration in its Identity and Access Management (IAM) service.

Token Issuance

After configuration, authentication follows this process:

1. The client requests an access token from the IdP.

2. The IdP issues a JWT access token.

3. The client sends an API request to Alation’s public API, including the JWT as a bearer token.

Token Validation

When Alation receives the request, it validates the token:

1. Alation checks whether the OAuth client configuration is cached and whether the cached JWKS (JSON Web Key Set) keys are valid.

   Note

   If the client or keys are not cached or are invalid, Alation initiates validation and fetches valid JWKS keys from the IdP.

2. Alation validates the token’s issuer and audience claims.

User Handling

Alation then determines how to associate the token claims with a user:

• If using user-initiated mode, Alation attaches the claim set directly to the user.

• If using machine-to-machine mode, Alation maps the claim set to a system user.

Authorization and Response

After successful validation and user resolution:

1. Alation authorizes the request based on the user’s role.

2. If authorized, Alation returns the API response.

This flow ensures that only properly authenticated and authorized clients can access Alation’s public APIs using externally issued OAuth tokens.

Configuration Process Overview

To complete the configuration for external OAuth token management, Server Admins must coordinate settings between their chosen Identity Provider (IdP) and the Alation platform:

• Step 1: Register an Application in Your IdP

• Step 2: Create an External Token Validation Profile in Alation

Step 1: Register an Application in Your IdP

When you begin developing the authentication module for your integration, you establish the Alation configuration that supports external token management. The process begins by registering a client application in your Identity Provider (IdP) and collecting the specific metadata for the Alation token validation profile.

The technical requirements for this initial setup vary depending on your chosen IdP. For detailed instructions on preparing your environment, refer to Configure OAuth Apps in Identity Providers for External OAuth Integrations.

Step 2: Create an External Token Validation Profile in Alation

Once you have created the client app and gathered the necessary metadata from your identity provider, create the validation profile in Alation:

1. On the Authentication tab of the Admin Settings, in the External OAuth Validations section, click Add.

2. Fill in the fields in the Configure External Token Validation Settings dialog.

3. Click Save to save the profile.

Once the profile is saved, Alation is ready to process external tokens. When your integration calls the IdP endpoint to generate an access token, Alation will automatically invoke this validation flow. Alation verifies the token against the IdP’s configuration and then authorizes or denies access to the requested Alation resource based on the mapped identity and assigned role.

External Token Validation Settings

The table below describes the fields required to configure an external token validation profile in Alation.

External Token Validation Profile Settings

Field Name	Description and Instructions
Name	Enter a unique identifier for the profile (for example, entra_external_oauth_profile). The name can contain letters, numbers, and the characters -, _, and &, but it must start and end with a letter character.
Token Client Identifier	Provide the Client ID issued by your OAuth provider (for example, 1d7def74-26bd-4f27-950e-bc11924e0865).
OAuth Issuer	Enter the issuer URL from your IdP (for example, for Entra ID this would be https://sts.windows.net/784e800a-8988-4d74-9348-b1dcf312f0ff/). Why it’s needed: The system must verify that the JWT originates from your specific corporate tenant. Without validating the issuer claim, the system could potentially accept structurally valid tokens from an unauthorized IdP.
OAuth Audience(s)	Input the audience value(s) from your IdP configuration. Enter multiple audiences as comma-separated values. Why it’s needed: This prevents “token replay” attacks, where a token generated for one application is intercepted and used to access another. For example, if the IdP issued a token with an audience of graph.microsoft.com, Alation would reject it because the IdP intended the token for Microsoft Graph, not Alation.
Machine-Based Flows (Checkbox)	Enabled by default to support service-to-service access without end-user context.
Claim for System User Mapping	Specify the JWT claim used to identify the system user, such as appid. Machine-based flows require a claim (such as appid or client_id) to map the token to an Alation system user. This field is mandatory even if you are configuring user-initiated flows.
System User Role	Select a role from the dropdown (for example, Server Admin). Alation will auto-create a system user and assign this role upon successful validation. Fill this field even if you are configuring user-initiated flows.
User-Involved Flows (Checkbox)	Select this to enable access using tokens with an end-user context mapped to a specific Alation user.
Claim for Username Mapping	Specify the JWT claim used to identify the individual Alation user, such as unique_name. The value should map to an existing username in Alation. Alation maps to the username field in Alation, not anything else. Fill this field only if you’re configuring user-initiated flows. Why it’s needed: User-initiated flow requires a claim (such as unique_name, email, or UPN) to map the JWT to an existing user. This mapping allows Alation to associate the incoming request with the correct Alation user.
Public JSON Web Key Set (JWKS) URL	Enter the public endpoint provided by your IdP used to verify token signatures. Why it’s needed: Since Alation does not issue tokens or store your IdP’s private keys, it relies on the JSON Web Key Set (JWKS) to confirm that the token has not been tampered with and that the trusted IdP signed it.

Edit an External Token Validation Profile

If your security requirements change or you need to update your Identity Provider (IdP) metadata, you can modify an existing validation profile at any time. Common reasons for editing include updating the Public JWKS URL or changing the System User Role assigned to a specific integration.

To edit a profile:

1. On the Authentication tab of the Admin Settings, in the External OAuth Validations section, locate the profile you want to change.

2. Click the three dots in the rightmost column for this profile.

3. Modify the necessary fields in the Edit External Token Validation Settings dialog.

   Note

   • You can’t change the Name or the Token Client Identifier of the profile.

   • If you are shifting from a machine-to-machine flow to a user-involved flow, ensure the Claim for Username Mapping matches the claim provided in your IdP’s new token configuration.

4. Click Save to apply the changes.

Migrate to External Token Management

Transitioning from locally managed OAuth clients to external token validation allows you to shift security responsibilities to your Identity Provider (IdP) without disrupting existing integrations. Because Alation’s internal OAuth stack and the new external validation profiles coexist, you can migrate your applications incrementally. You can keep the old internal OAuth client active while you test this new profile.

To ensure a smooth transition, consider a phased approach:

1. Register your existing integration as a new client application in your IdP.

2. In Alation, create a corresponding external OAuth profile using the metadata from your IdP.

3. Ensure that the System User Role or User Mapping in your new external profile matches the permissions of the old local client to prevent authorization errors.

4. Modify your integration’s authentication module to point to the IdP’s token endpoint instead of Alation’s local token endpoint, updating the logic to handle the new JWT access token format issued by your IdP.

5. Run the integration and verify that Alation correctly maps the external token to the intended user or system role. Confirm that the token is being validated against the external JWKS endpoint.

6. Once the integration is confirmed stable using external tokens, delete the locally managed client and its associated secrets to fulfill your organization’s centralized security policy.