> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External Identity Providers

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.

<Note>
  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.
</Note>

## 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):

<Steps>
  <Step title="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)
  </Step>

  <Step title="Claim Mappings">
    Configure mappings for v1.0's WS-Federation claims:

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="Validation Settings">
    * Enable External Identity Provider: ✅
    * Validate Issuer: ✅
    * Validate Audience: ✅
    * Validate Lifetime: ✅
    * Allowed Clock Skew: 300 seconds
  </Step>
</Steps>

### Microsoft Entra ID v2.0 Configuration

For v2.0 endpoints (modern OIDC):

<Steps>
  <Step title="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)
  </Step>

  <Step title="Claim Mappings">
    v2.0 uses simple claim names:

    ```json theme={null}
    {
      "email": "preferred_username"
    }
    ```
  </Step>

  <Step title="Validation Settings">
    Same as v1.0 configuration above.
  </Step>
</Steps>

<Important>
  Key differences between v1.0 and v2.0:

  * **v1.0**: Requires `api://` audience prefix, trailing slash on issuer, uses WS-Federation claim URIs
  * **v2.0**: No `api://` prefix, no trailing slash, uses simple claim names
</Important>

## Testing Your Configuration

### Generate Test Tokens

**For v1.0:**

```bash theme={null}
az account get-access-token \
  --resource api://{CLIENT_ID} \
  --tenant {TENANT_ID} \
  --query accessToken -o tsv
```

**For v2.0:**

```bash theme={null}
az account get-access-token \
  --scope {CLIENT_ID}/.default \
  --tenant {TENANT_ID} \
  --query accessToken -o tsv
```

### Test API Access

```bash theme={null}
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

<Note>
  Currently, Airia supports one External IDP configuration per tenant. Choose the version that matches your primary token issuer.
</Note>