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 and enables organizations to 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.

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

How external identity providers work

When a user attempts to access the Kubernetes API server:

  • 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

Conceptual diagram showing how external identity provider-based authentication works with AKS clusters.

Identity providers

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

  • GitHub: Authenticate using GitHub identities or GitHub Actions

  • Generic OIDC providers: Any provider implementing OIDC standards

  • Custom identity solutions: Organization-specific OIDC implementations

Note

Microsoft Entra ID isn't supported as an external identity provider through structured authentication. Use the existing AKS-managed Microsoft Entra integration for Microsoft Entra ID authentication.

Identity provider requirements

External identity providers must:

  • Support OIDC standards

  • Provide publicly accessible OIDC discovery endpoints

  • Issue JWT tokens with appropriate claims

  • Be accessible from AKS cluster nodes for token validation

Key concepts

JWT authenticators

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:

  • 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

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

  • 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

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

Next steps

  • Last updated on