Skip to main content
External Identity Providers enable organizations to authenticate users and execute pipelines using JWT tokens issued by their own identity management systems. This allows API access and pipeline execution using existing corporate authentication tokens without requiring separate Airia credentials.
External Identity Provider support is separate from SSO. SSO enables user login to the Airia web interface, while External IDP enables API access and pipeline execution using externally-issued tokens.

​
Before You Begin

To complete this configuration, you will need:
  • Platform Admin role in Airia
  • Application Administrator role in Microsoft Entra ID (or equivalent in your IDP)
  • Your organization’s Tenant ID and ability to create app registrations

​
Creating App Registration in Microsoft Entra

To use Microsoft Entra ID as an external identity provider:
  1. Create a new App Registration in Azure Portal → Azure Active Directory → App registrations
    • Name: Airia External Identity Provider
    • Account types: Choose single or multi-tenant based on your needs
    • Redirect URI: Leave blank (not required for token validation)
  2. Expose an API (required for v1.0, optional for v2.0)
    • Navigate to “Expose an API” and set Application ID URI to api://{CLIENT_ID}
    • Add a scope named access_as_user
  3. Note these values from the Overview page:
    • Application (Client) ID
    • Directory (Tenant) ID

​
Configuring External IDP in Airia

Navigate to Settings → External Identity Provider in the Airia platform.

​
Microsoft Entra ID v1.0 Configuration

For v1.0 endpoints (traditional Azure AD):
1

Basic Settings

  • Display Name: Microsoft Entra ID V1
  • Issuer URL: https://sts.windows.net/{TENANT_ID}/ (trailing slash required)
  • JWKS URL: https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys
  • Audience: api://{CLIENT_ID} (api:// prefix required)
2

Claim Mappings

Configure mappings for v1.0’s WS-Federation claims:
{
  "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
  "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
  "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
  "sub": "http://schemas.microsoft.com/identity/claims/objectidentifier"
}
3

Validation Settings

  • Enable External Identity Provider: ✅
  • Validate Issuer: ✅
  • Validate Audience: ✅
  • Validate Lifetime: ✅
  • Allowed Clock Skew: 300 seconds

​
Microsoft Entra ID v2.0 Configuration

For v2.0 endpoints (modern OIDC):
1

Basic Settings

  • Display Name: Microsoft Entra ID V2
  • Issuer URL: https://login.microsoftonline.com/{TENANT_ID}/v2.0 (no trailing slash)
  • JWKS URL: https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys
  • Audience: {CLIENT_ID} (no api:// prefix)
2

Claim Mappings

v2.0 uses simple claim names:
{
  "email": "preferred_username"
}
3

Validation Settings

Same as v1.0 configuration above.

​
Testing Your Configuration

​
Generate Test Tokens

For v1.0: 
az account get-access-token \
  --resource api://{CLIENT_ID} \
  --tenant {TENANT_ID} \
  --query accessToken -o tsv
For v2.0: 
az account get-access-token \
  --scope {CLIENT_ID}/.default \
  --tenant {TENANT_ID} \
  --query accessToken -o tsv

​
Test API Access

curl -X POST \
  "https://your-airia-instance.com/v2/PipelineExecution/TemporaryPipeline" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: your-tenant-id" \
  -d @pipeline.json

​
Common Issues

​
v1.0 Troubleshooting

  • Invalid Issuer: Ensure trailing slash is present (https://sts.windows.net/{TENANT_ID}/)
  • Invalid Audience: Include the api:// prefix (api://{CLIENT_ID})
  • Missing User Info: Use full WS-Federation URI claim mappings

​
v2.0 Troubleshooting

  • Invalid Audience: Remove the api:// prefix (use {CLIENT_ID} only)
  • Invalid Issuer: Remove trailing slash (https://login.microsoftonline.com/{TENANT_ID}/v2.0)
  • Missing Email: Map to preferred_username or upn claim

​
General Issues

  • Token Expired: Check exp claim in decoded token
  • JWKS URL Not Accessible: Verify network access to login.microsoftonline.com
  • Clock Skew: Increase “Allowed Clock Skew” if time sync issues exist

​
Additional Settings

JWT Pass-Through: Enable to pass the original JWT token to downstream services and agents. User Provisioning: Users are automatically created (Just-In-Time provisioning) on first authentication using token claims for email, first name, and last name.

​
Choosing Between v1.0 and v2.0

  • Use v1.0 for legacy applications expecting WS-Federation claims or requiring api:// audience format
  • Use v2.0 for new applications following modern OIDC standards with simpler claim names
Currently, Airia supports one External IDP configuration per tenant. Choose the version that matches your primary token issuer.