Entra ID Authentication#

Overview#

MicrosoftEntraIDProvider is the dedicated oauth2-proxy provider for Microsoft Entra ID (formerly Azure AD). It wraps OIDCProvider and adds Entra-specific behavior: multi-tenant allowed-tenant enforcement, group overage resolution via Microsoft Graph, and federated token (Workload Identity) authentication. The provider is fully OIDC-compliant — all standard OIDC parameters apply — but requires Entra-specific configuration for multi-tenant and advanced scenarios.

Entry point: providers/ms_entra_id.go

Note: This provider (provider = "entra-id") is distinct from the legacy azure provider, which is deprecated.

Configuration#

Full reference: Microsoft Entra ID provider docs

Provider-Specific Flags#

Defined in MicrosoftEntraIDOptions.

Issuer URL Patterns#

Scopes#

• openid — minimum for login 1
• openid User.Read — required when users have 200+ group memberships (group overage)
• openid profile email — required for personal Microsoft accounts

Issuer Validation & Tenant ID Extraction#

Current Behavior#

getTenantFromToken() extracts the tenant ID from the ID token's iss claim using a hardcoded regex:

^https://login\.microsoftonline\.com/([a-zA-Z0-9-]+)/v2\.0$

This extracted tenant ID drives two behaviors:

1. Multi-tenant validation — if --entra-id-allowed-tenant is set, the tenant is checked against the allowlist in ValidateSession().
2. Issuer format check — for multi-tenant deployments, the provider re-validates the issuer claim matches the https://login.microsoftonline.com/{tenant-id}/v2.0 template even when insecure_oidc_skip_issuer_verification=true 1.

Known Limitation: CIAM and Sovereign Clouds#

The regex exclusively matches login.microsoftonline.com, causing getTenantFromToken() to return an error for:

• CIAM / External tenants — issuers in the form https://<tenantId>.ciamlogin.com/<tenantId>/v2.0 2
• Sovereign clouds — national cloud deployments (Azure Government, Azure China, etc.) use different issuer host names 3

Tracking issue: #3476 | Pending fix: PR #3229

Pending Fix (PR #3229)#

PR #3229 proposes reading the tid claim from the ID token payload first, falling back to the iss regex only when tid is absent. Because Microsoft includes tid in all Entra ID tokens — including CIAM — this approach makes tenant extraction issuer-agnostic without requiring regex expansion or new configuration options.

Group Overage Handling#

Entra ID embeds group memberships in the ID token, but only up to 200 groups. When a user exceeds this limit, the token contains a _claim_names.groups key instead of a groups list — the "overage" signal 1.

Flow:

1. EnrichSession() calls checkGroupOverage(), which looks for _claim_names.groups in the token.
2. If overage is detected, addGraphGroupsToSession() fetches the full membership list from the Microsoft Graph API endpoint GET /v1.0/me/transitiveMemberOf?$select=id&$top=100, paginating via @odata.nextLink until all groups are collected.
3. Results are deduplicated and merged into session.Groups.

Prerequisite: The User.Read delegated scope must be granted — either via user consent at first login or admin pre-consent — and the scope config must include User.Read 1.

Federated Token (Workload Identity) Authentication#

When entra_id_federated_token_auth = true, oauth2-proxy authenticates to Entra ID using a Workload Identity federated token instead of a client_secret. This is the recommended approach for Kubernetes-hosted deployments.

How it works:

• redeemWithFederatedToken() reads the token from the file path in AZURE_FEDERATED_TOKEN_FILE (set by the Workload Identity mutating webhook).
• The token is sent as client_assertion with client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer in the token exchange request 4.
• Token refresh also uses the federated credential via redeemRefreshTokenWithFederatedToken().

Requirements 1:

1. App registration must have a federated identity credential configured with audience api://AzureADTokenExchange.
2. The Pod must carry Workload Identity annotations (azure.workload.identity/client-id and azure.workload.identity/use: "true").
3. Set entra_id_federated_token_auth = true; client_secret can be omitted.