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

# Microsoft Entra ID (OIDC)

The Microsoft Entra ID connector integrates the Maverics Orchestrator with Microsoft Entra ID (formerly Azure Active Directory) -- enabling OIDC-based single sign-on for your applications.

<Note>
  **Console terminology:** In the Maverics Console, this section is called
  **Identity Fabric**. The YAML configuration uses the `connectors` key to define
  identity provider integrations.
</Note>

## Overview

The Microsoft Entra ID connector uses OpenID Connect to federate authentication with Microsoft Entra ID and supports standard OIDC flows -- allowing you to bridge Microsoft Entra ID with applications that don't natively support modern identity protocols.

## Use Cases

* **Unify SSO across hybrid environments** -- Extend Microsoft Entra ID authentication to legacy and on-premises applications that don't support modern protocols, creating seamless SSO across your entire hybrid estate
* **Rationalize identity platforms** -- Consolidate redundant identity providers onto Microsoft Entra ID by orchestrating gradual user migration without disrupting access to existing applications
* **Identity resilience and failover** -- Configure Microsoft Entra ID as a primary or secondary IdP with automatic failover routing, ensuring authentication continuity if another provider experiences an outage
* **Bridge on-premises Active Directory** -- Connect on-premises AD (synced via Entra ID Connect) with cloud applications through OIDC federation, unifying access across directory boundaries

## Setup

<Tabs>
  <Tab title="Console UI">
    To create a Microsoft Entra ID (OIDC) connector in the Maverics Console:

    1. Navigate to **Identity Fabric** in the Console sidebar.
    2. Click **Create** and select **Microsoft Entra ID (OIDC)**.
    3. Enter a **Name** -- this is the friendly name that identifies your provider.
    4. Enter the **OIDC Well Known URL** -- for Microsoft Entra ID, this follows the pattern `https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration`. Replace `{tenant-id}` with your Microsoft Entra ID directory (tenant) ID from the Azure portal. Use the v2.0 endpoint for standard OIDC support.
    5. Enter the **OAuth Client ID** -- the Application (client) ID from your Entra ID app registration in the Azure portal.
    6. Enter the **OAuth Client Secret** -- the client secret from your Entra ID app registration.
    7. Under **Redirect URLs**, add the callback URL where Entra ID will redirect after authentication. This URL must match a Redirect URI configured in the app registration under Authentication.
    8. Optionally configure **Logout Callback URLs** for single logout support.
    9. Optionally set **Scopes** (space-separated). Default scopes are typically `openid profile email`.
    10. The **PKCE** toggle is enabled by default. Disable it only if your Entra ID app registration is not configured to support Proof Key for Code Exchange.
    11. Optionally enable **Offline Access** for token refresh support (Proxy apps only).
    12. Optionally configure **Error Handling** rules to redirect users based on errors returned by the IdP during the OIDC callback. See [Callback Error Handling](#callback-error-handling) for details.
    13. Click **Save**.
  </Tab>

  <Tab title="Configuration">
    ```yaml theme={null}
    connectors:
      - name: azure
        type: azure
        oidcWellKnownURL: "https://login.microsoftonline.com/{{ env.AZURE_TENANT_ID }}/v2.0/.well-known/openid-configuration"
        oauthClientID: "{{ env.AZURE_CLIENT_ID }}"
        oauthClientSecret: <vault.azure_client_secret>
        oauthRedirectURL: "https://app.example.com/oidc/callback"
    ```

    <Note>
      The Microsoft Entra ID well-known URL includes a tenant ID in the path: `login.microsoftonline.com/{tenant-id}/v2.0/`. Use the v2.0 endpoint for standard OIDC support. Replace the tenant ID with your Microsoft Entra ID directory (tenant) ID from the Azure portal.
    </Note>

    ## Configuration Reference

    | Key                 | Type   | Required | Description                                                                                                                    |
    | ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
    | `name`              | string | Yes      | Unique connector identifier referenced in app policies                                                                         |
    | `type`              | string | Yes      | Must be `azure`                                                                                                                |
    | `oidcWellKnownURL`  | string | Yes      | OIDC discovery endpoint URL (tenant-specific)                                                                                  |
    | `oauthClientID`     | string | Yes      | OAuth 2.0 client (application) ID from the Azure portal                                                                        |
    | `oauthClientSecret` | string | Yes      | OAuth 2.0 client secret (use secret reference syntax)                                                                          |
    | `oauthRedirectURL`  | string | Yes      | Callback URL registered with the Microsoft Entra ID app registration                                                           |
    | `tls`               | string | No       | Named TLS profile for provider communication                                                                                   |
    | `errorHandling`     | object | No       | Configures how IdP errors during the OIDC callback are handled. See [Callback Error Handling](#callback-error-handling) below. |

    For the complete field reference including health checks, offline access, and PKCE settings, see [Identity Fabric](/reference/orchestrator/identity-fabric#configuration-reference).
  </Tab>
</Tabs>

## Callback Error Handling

When Microsoft Entra ID returns an error during the OIDC callback (e.g., the user forgot their password in an Azure AD B2C flow, or cancelled login), the Orchestrator can evaluate configurable rules to redirect the user to a specific URL based on the error.

Rules are evaluated in order -- the first matching rule wins. You can match on the `error` or `error_description` callback parameters using exact or substring matching. A default catch-all rule can be included to handle any unmatched errors.

<Tabs>
  <Tab title="Console UI">
    In the connector's **Error Handling** section:

    1. Click **Add Rule** to create a new error handling rule.
    2. Select a **Match On** value -- either **Error** or **Error Description** -- to choose which OIDC callback parameter to match against.
    3. Select a **Match Type** -- either **Contains** (substring match) or **Equals** (exact match).
    4. Enter the **Match Value** -- the string to match against the selected callback parameter (e.g., `AADB2C90118` for Azure AD B2C password reset flows).
    5. Enter the **Redirect URL** -- the URL to redirect the user to when this rule matches.
    6. Optionally check **Default** to make a rule the catch-all for any unmatched errors. A default rule does not require Match On, Match Type, or Match Value fields. Only one default rule is allowed.
    7. Drag rules to reorder them -- rules are evaluated top to bottom and the first match wins.
    8. Click **Save**.
  </Tab>

  <Tab title="Configuration">
    Rules are defined under `errorHandling.onCallbackError`:

    ```yaml theme={null}
    connectors:
      - name: azure
        type: azure
        oidcWellKnownURL: "https://login.microsoftonline.com/{{ env.AZURE_TENANT_ID }}/v2.0/.well-known/openid-configuration"
        oauthClientID: "{{ env.AZURE_CLIENT_ID }}"
        oauthClientSecret: <vault.azure_client_secret>
        oauthRedirectURL: "https://app.example.com/oidc/callback"
        errorHandling:
          onCallbackError:
            - contains: "AADB2C90118"
              matchOn: error_description
              redirectURL: "https://app.example.com/password-reset"
            - equals: server_error
              matchOn: error
              redirectURL: "https://app.example.com/error"
            - default: true
              redirectURL: "https://app.example.com/generic-error"
    ```

    ### Rule Reference

    Each rule in the `onCallbackError` list supports the following fields:

    | Key           | Type    | Required    | Description                                                                                                                                                                               |
    | ------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `contains`    | string  | Conditional | Matches when the target field contains this substring. Mutually exclusive with `equals`. Required unless `default` is `true`.                                                             |
    | `equals`      | string  | Conditional | Matches when the target field exactly equals this value. Mutually exclusive with `contains`. Required unless `default` is `true`.                                                         |
    | `matchOn`     | string  | Conditional | Which callback parameter to match against. Must be `error` or `error_description`. Required unless `default` is `true`.                                                                   |
    | `redirectURL` | string  | Yes         | The URL to redirect the user to when the rule matches.                                                                                                                                    |
    | `default`     | boolean | No          | When `true`, this rule acts as a catch-all for any error not matched by prior rules. When set, `contains`, `equals`, and `matchOn` must not be defined. Only one default rule is allowed. |

    <Note>
      If no rule matches the error and no `default` rule is defined, the Orchestrator falls back to the standard error handling behavior.
    </Note>
  </Tab>
</Tabs>

## Troubleshooting

* **Verify the `oidcWellKnownURL` is accessible** from the Orchestrator host -- ensure the tenant ID is correct and the v2.0 endpoint is used
* **Ensure the `oauthRedirectURL` matches exactly** what is registered in the Microsoft Entra ID app registration under Authentication > Redirect URIs
* **Check that the client secret reference resolves correctly** via your secret provider -- Microsoft Entra ID client secrets expire and need periodic rotation

## Related Pages

<CardGroup cols={2}>
  <Card title="Identity Fabric" icon="id-badge" href="/reference/orchestrator/identity-fabric">
    Overview of all identity providers
  </Card>

  <Card title="Okta" icon="shield-halved" href="/reference/orchestrator/identity-fabric/okta">
    OIDC connector for Okta
  </Card>

  <Card title="Generic OIDC" icon="key" href="/reference/orchestrator/identity-fabric/custom-oidc">
    Generic OpenID Connect connector
  </Card>

  <Card title="ADFS" icon="server" href="/reference/orchestrator/identity-fabric/adfs">
    OIDC connector for ADFS
  </Card>
</CardGroup>