Skip to main content

azure-ad Guard

Guardazure-ad

azure-ad Guard

Available in Zilla Plus

Defines a guard with Azure AD support.

The azure-ad guard uses public keys to verify the integrity of access tokens when identifying authorized subjects and their associated roles scope. The token issuer and audience can also be constrained to prevent access tokens from other applications from being reused inappropriately.

Each verified access token has an expiration time, and an optional challenge window prior to the expiration time that can be used by specific protocol bindings to send a challenge to renew the access token before it expires.

Key Discovery & Rotation

The guard uses the issuer value to construct the discovery endpoint URL:

  • If issuer is omitted, organizations is used as default:
https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
  • If issuer is configured (options.issuer), a tenant-specific configuration is used:
https://login.microsoftonline.com/example.onmicrosoft.com/v2.0/.well-known/openid-configuration

From this discovery document, it extracts the jwks_uri to validate tokens.

The Azure AD guard detects public-private key rotations based on max-age, defaulting to a 24 hours refresh interval to ensure uninterrupted token validation.

guards:
  my_azure_ad_guard:
    type: azure-ad
    options:
      audience: 00000000-1111-2222-3333-444444444444

Manual configuration is also supported.

guards:
  my_azure_ad_guard:
    type: azure-ad
    options:
      issuer: example.onmicrosoft.com
      audience: 00000000-1111-2222-3333-444444444444
      version: v2.0
      challenge: 30

Configuration (* required)

store

string

The name of the store used by this guard.

options*

object

The azure-ad specific options.

options:
  issuer: example.onmicrosoft.com
  audience: 00000000-1111-2222-3333-444444444444
  version: v2.0
  challenge: 30

options.issuer

string | Default: organizations

Issuer.

options.audience

string

Audience claim.

options.version

enum [ v1.0, v2.0 ] | Default: v2.0

Azure AD version.

options.challenge

integer

Challenge period (seconds).

options.identity

string | Default: sub

Claim to extract the user's identity from the token.

options.roles

string | Default: roles

Claim to check for authorized roles.

options.attributes

object as map of named string properties

Additional claims to extract from the token as named attributes.

Gateway Version