Microsoft Entra ID Provider

This PR contains a proposal for a new implementation of Azure provider, that:

• Is a child type of OIDCPRovider
• Supports group overage, multi-tenancy and V2 endpoint only - see Make AzureProvider a child type of OIDCProvider #2384
• Prepares Azure provider to consume client assertion token exchange OIDC feature and thus support Azure Workload Identity.
• Has all Azure permissions and multi-tenancy considerations recognized and covered in docs.
• Replaces existing azure provider that is often misbehaving when it comes to permissions, groups and multi-tenancy.

Changes

New OIDC-compliant provider is added - ms-entra-id. Provider-specific configuration flags are:

• --ms-entra-id-allowed-tenant=<tenant-id> - When specified, multi-tenant app authentication only allows tokens incomming from specific tenants.

Remarks:

• There's no flag for Tenant ID - only OIDC issuer URL is needed
• There's no groupGraphField support - RFC whether this is a valuable feature now or can be added separately.

Usage

Detailed usage instructions with different scenarios, permissions, multi-tenancy considerations and examples with Azure Portal and Terraform are added to provider documentation.

Features

Outside of the generic OIDC behavior, provider implements the following:

• Group overage - custom implementation of EnrichSession() checks for group overage (If not disabled by --ms-entra-id-skip-graph-groups).
• Allowed tenants for multi tenant apps - Multi-tenant apps require --insecure-oidc-skip-issuer-verification flag to be set. Custom implementaion of ValidateSession() fills the security gap by comparing Tenant ID from incomming token with list specified in --ms-entra-id-multi-tenant-allowed-tenant.

Other considerations

Scope

This provider requires scope to be set explicitly (openid for azure only, and openid profile email for MS personal accounts). Default behavior adds groups scope when --allowed-group is set. This claim isn't supported by Azure (it's also incompliant with OIDC). Fix proposed separately: #2392

Missing e-mail in claim

When Azure user has no e-mail set (for example: it's created quickly for testing), oauth2-proxy fails with 500 with following:

[2024/01/14 20:32:23] [oauthproxy.go:853] Error creating session during OAuth2 callback: neither the id_token nor the profileURL set an email

When e-mail is added, everything works as expected.

How this was tested

This was carefully manually tested on Kubernetes with Traefik forward auth middleware. Following scenarios were covered:

• Single-tenant:
  • ✔ Minimal-permission app registration without groups claim enabled.
  • ✔ Minimal-permission app registration with groups claim enabled and with --allowed-group.
  • ✔ Group overage with --allowed-group + behavior for missing permissions.
• Multi-tenant:
  • ✔ Minimal-permission app registration without groups claim enabled, tested from 2 tenants & personal MS accounts
  • ✔ Minimal-permission app registration with groups claim enabled and with --allowed-group, tested from 2 tenants & personal MS account
  • ✔ Group overage with --allowed-group, tested from 2 tenants & personal MS account, check behavior for missing permissions.
  • ✔ ms-entra-id-multi-tenant-allowed-tenants - tested various combinations with 2 tenants & personal MS account
• Other tests
  • ✔ Docusaurus build

Implemented unit tests cover the corner cases - group overage & multi tenancy.

Related PRs and issues

• Azure Provider: return to using token's groups claim #1972 - PR by @hskiba , updates existing provider to call Graph API only when needed. I like using Microsoft Go SDK to interact with Graph API, and would love to have something similar in this provider when we decide to support graph group field.
• [WIP] Add client assertions auth for oidc base provider #2378 - PR by @tuunit , adds client assertion auth to generic OIDC provider. These changes will allow to use Azure Workload Identity.
• Make AzureProvider a child type of OIDCProvider #2384 - issue by @jjlakis , explains the differneces and outstandings in Azure vs. generic OIDC, describes background for this PR.