Use external identity providers with AKS structured authentication (preview)

Azure Kubernetes Service (AKS) supports structured authentication, which allows you to configure external identity providers for authenticating users to the Kubernetes API server. This feature is based on the upstream Kubernetes structured authentication configuration. AKS implements this functionality through JSON Web Token (JWT) authenticators that validate tokens from external identity providers according to your configuration. With structured authentication, organizations can integrate AKS with their existing identity infrastructure beyond Microsoft Entra ID.

Structured authentication extends AKS beyond traditional Microsoft Entra ID integration by supporting industry-standard OpenID Connect (OIDC) identity providers. This feature allows you to:

• Authenticate users with external identity providers like GitHub, or any OIDC-compliant provider

• Maintain centralized identity management across your organization

• Implement custom claim validation and user mapping rules

• Support multiple identity providers simultaneously on a single cluster

The feature is based on the Kubernetes structured authentication configuration, which moved to beta in Kubernetes 1.30. AKS implements this functionality through JSON Web Token (JWT) authenticators that validate tokens from external identity providers according to your configuration.

How external identity providers work

When a user attempts to access the Kubernetes API server using structured authentication with an external identity provider, the authentication and authorization flow is as follows:

• Authentication: The following steps validate the user's identity:
  • Token presentation: The user presents a JWT token from their configured identity provider.
  • Token validation: The API server validates the token's signature, issuer, audience, and expiration.
  • Claim processing: Custom claim validation rules are applied to ensure the token meets your requirements.
  • User mapping: Claims are mapped to Kubernetes user identity (username, groups, and extra attributes).
• Authorization: Standard Kubernetes Role-Based Access Control (RBAC) determines what actions the authenticated user can perform.

Supported identity providers

While AKS structured authentication allows any OIDC-compliant identity provider, common providers include:

• GitHub: Authenticate using GitHub identities or GitHub Actions.
• Generic OIDC providers: Any provider implementing OIDC standards.
• Custom identity solutions: Organization-specific OIDC implementations.

Requirements for external identity providers

External identity providers must meet the following requirements to work with AKS structured authentication:

• Support OIDC standards.
• Provide publicly accessible OIDC discovery endpoints.
• Issue JWT tokens with appropriate claims.
• Be accessible from AKS cluster nodes for token validation.

JWT authenticators for AKS structured authentication

A JWT authenticator is a configuration object that defines how AKS validates and processes tokens from an external identity provider. For example, AKS expects an ID token (JWT) whose aud (audience) claim matches the audience value you configure for the authenticator, such as "my-api", or an OAuth client ID. Each JWT authenticator includes the following components:

• Issuer configuration: Specifies the OIDC issuer URL and the expected audience values for tokens.
• Claim validation rules: Uses CEL (Common Expression Language) expressions to enforce custom validation logic on token claims.
• Claim mappings: Defines how JWT claims are mapped to Kubernetes user attributes such as username, groups, and extra fields.
• User validation rules: Applies extra validation logic after claim mapping to further restrict or allow access.

CEL expressions for claim validation and mapping

Structured authentication uses CEL expressions for flexible claim validation and mapping. CEL provides a secure sandbox environment for evaluating custom logic against JWT claims.

Example CEL expressions:

// Validate that the 'sub' claim exists
has(claims.sub)

// Map username with AKS prefix
'aks:jwt:' + claims.sub

// Map groups from comma-separated string
claims.groups.split(',').map(g, 'aks:jwt:' + g)

// Conditional mapping based on claim verification
'aks:jwt:' + (claims.email_verified ? claims.email : claims.sub)

Security best practices

Keep the following security best practices in mind when using external identity providers with AKS structured authentication:

• Use strong claim validation: Implement comprehensive validation rules to ensure only authorized tokens are accepted.
• Limit token scope: Configure your identity provider to issue tokens with minimal necessary claims.
• Regular rotation: Rotate client secrets and certificates regularly.
• Monitor access: Enable resource logs and turn on kube-apiserver logs to inspect any potential issues with the configured JWT authenticators and track authentication events.
• Test configurations: Validate your JWT authenticator configuration in a nonproduction environment first.

Security considerations

Keep the following security considerations in mind when using external identity providers with AKS structured authentication:

• Prefix requirements: All usernames and groups mapped through structured authentication must be prefixed with aks:jwt: to prevent conflicts with other authentication methods and system accounts.
• Network access: Identity provider endpoints must be accessible from:
  • AKS cluster nodes for token validation.
  • Client systems for token acquisition.
  • Any network paths involved in the authentication flow.
• Validation layers: Structured authentication provides multiple validation layers:
  • Token signature validation ensures token authenticity.
  • Standard claim validation verifies issuer, audience, and expiration.
  • Custom claim validation applies your organization's specific requirements.
  • User validation final checks after claim mapping.

Related content

For more information about structured authentication and related features, see the following resources:

• Configure structured authentication for AKS
• Kubernetes structured authentication configuration
• CEL expressions in Kubernetes
• OpenID Connect specification