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.

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

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

Console UI
Configuration

To create a Microsoft Entra ID (OIDC) connector in the Maverics Console:

Navigate to Identity Fabric in the Console sidebar.
Click Create and select Microsoft Entra ID (OIDC).
Enter a Name — this is the friendly name that identifies your provider.
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.
Enter the OAuth Client ID — the Application (client) ID from your Entra ID app registration in the Azure portal.
Enter the OAuth Client Secret — the client secret from your Entra ID app registration.
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.
Optionally configure Logout Callback URLs for single logout support.
Optionally set Scopes (space-separated). Default scopes are typically openid profile email.
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.
Optionally enable Offline Access for token refresh support (Proxy apps only).
Optionally configure Error Handling rules to redirect users based on errors returned by the IdP during the OIDC callback. See Callback Error Handling for details.
Click Save.

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"

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.

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 below.

For the complete field reference including health checks, offline access, and PKCE settings, see Identity Fabric.

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.

Console UI
Configuration

In the connector’s Error Handling section:

Click Add Rule to create a new error handling rule.
Select a Match On value — either Error or Error Description — to choose which OIDC callback parameter to match against.
Select a Match Type — either Contains (substring match) or Equals (exact match).
Enter the Match Value — the string to match against the selected callback parameter (e.g., AADB2C90118 for Azure AD B2C password reset flows).
Enter the Redirect URL — the URL to redirect the user to when this rule matches.
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.
Drag rules to reorder them — rules are evaluated top to bottom and the first match wins.
Click Save.

Rules are defined under errorHandling.onCallbackError:

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.

If no rule matches the error and no default rule is defined, the Orchestrator falls back to the standard error handling behavior.

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

Identity Fabric

Overview of all identity providers

Okta

OIDC connector for Okta

Generic OIDC

Generic OpenID Connect connector

ADFS

OIDC connector for ADFS

Console Administration

Orchestration

Overview

Use Cases

Setup

Configuration Reference

Callback Error Handling

Rule Reference

Troubleshooting

Identity Fabric

Okta

Generic OIDC

ADFS

Console Administration

Orchestration

​Overview

​Use Cases

​Setup

​Configuration Reference

​Callback Error Handling

​Rule Reference

​Troubleshooting

​Related Pages

Identity Fabric

Okta

Generic OIDC

ADFS

Overview

Use Cases

Setup

Configuration Reference

Callback Error Handling

Rule Reference

Troubleshooting

Related Pages