Skip to content

Entra ID Token Rotation Guide

Overview

MazeVault provides automated lifecycle management for Microsoft Entra ID (Azure AD) enterprise application credentials. This includes automatic discovery, expiry monitoring, dual-secret rotation with grace periods, and ordered post-rotation deployment to Azure Key Vault, Kubernetes, agent-managed runtime files, IIS app pools, Spring applications, and webhooks.

Key Features

  • Automatic Discovery: Sync app registrations and credentials from Entra ID
  • Expiry Monitoring: Alerts at 30-day and 7-day thresholds
  • Dual-Secret Rotation: New credential created before old one is removed
  • Grace Period: Configurable period (default 30 days) where both credentials are valid
  • Ordered Rollout Actions: Publish the new credential to external stores and then refresh or recycle consumers in a defined sequence
  • Multi-Target Propagation: Sync to Azure Key Vault, Kubernetes Secrets, Spring Actuator, webhooks, and agents
  • Full Audit Trail: Every rotation recorded with timestamps and status

Getting Started

1. Configure Entra ID Integration

Navigate to Integrations → Add Integration → Microsoft Entra ID.

Provide: - Tenant ID: Your Azure AD tenant ID - Client ID: Service principal client ID - Client Secret or Managed Identity: Authentication method

MazeVault validates both interactive and background authentication before saving the integration. If onboarding uses delegated or OBO access, also configure a compatible background authentication method for sync, preflight, and rotation jobs.

2. Sync App Registrations

After configuring the integration, click Sync to discover all app registrations in your tenant. MazeVault will import: - App registration metadata - Client secrets with expiry dates - Certificate credentials

3. View Credential Status

The Entra Dashboard shows: - Total active credentials - Credentials expiring in 7/30/90 days - Credentials in grace period - Most urgent credentials requiring attention

4. Configure Rotation

For each credential, you can configure: - Auto-rotation: Enable automatic rotation before expiry - Days before expiry: When to trigger rotation (default: 30 days) - Grace period: How long to keep both credentials active (default: 30 days) - Key Vault targets: Primary and secondary Key Vault secrets for secret storage - Kubernetes targets: Namespace, secret name, and key to update - Agent file targets: Managed runtime files on connected Windows or Linux agents - IIS recycle targets: Windows IIS app pools to recycle after file deployment - Spring endpoints: Spring Actuator refresh endpoints - Webhook URLs: Notification or deployment webhooks

5. Manual Rotation

Click the Rotate button on any credential to trigger immediate rotation. The process:

  1. Creates a new credential in Entra ID
  2. Executes post-rotation deployment actions in order
  3. Stores the new secret in configured Key Vaults, Kubernetes Secrets, or agent-managed files
  4. Refreshes or recycles consuming applications
  5. Sends webhook notifications if configured
  6. Marks old credential for grace period cleanup

Post-Rotation Deployment Actions

MazeVault executes post-rotation actions in order after it creates the new Entra credential. For production rollouts, use this sequence:

  1. Publish the new secret to external stores or runtime files.
  2. Reload or recycle the consuming application.
  3. Finish with webhook notifications if downstream systems need confirmation.

Supported action types:

  • Azure Key Vault: Write the rotated value into a Key Vault secret version.
  • Kubernetes Secret: Update a namespace/secret/key tuple with the new value.
  • Agent File Sync (agent_secret_sync): Write the rotated value into a file on a connected MazeVault agent host.
  • IIS App Pool Recycle (iis_recycle): Recycle a Windows IIS app pool through a connected MazeVault agent.
  • Spring Actuator Refresh: Call /actuator/refresh after publishing the new secret.
  • Webhook: POST an event to a downstream deployment or notification endpoint.

Agent File Sync (agent_secret_sync)

Use agent_secret_sync when the rotated client secret must be written directly into an application configuration file.

Required fields:

  • agent_id: Connected MazeVault agent ID. This is the recommended target because preflight can verify agent readiness.
  • target_path: Absolute path to the runtime configuration file on the managed host.
  • secret_key: Field name or entry key that receives the rotated secret.
  • file_format: Renderer format such as json, yaml, or env.

Operator notes:

  • Put this step before any application refresh or recycle step.
  • Legacy direct agent_url targeting remains supported for compatibility, but MazeVault marks it as manual review because it cannot probe the target automatically.
  • The target agent must have file-system access to the destination path.

Example:

[
    {
        "type": "agent_secret_sync",
        "order": 10,
        "on_failure": "abort",
        "agent_id": "11111111-1111-1111-1111-111111111111",
        "config": {
            "target_path": "C:\\inetpub\\app\\appsettings.json",
            "secret_key": "Entra:ClientSecret",
            "file_format": "json"
        }
    }
]

IIS App Pool Recycle (iis_recycle)

Use iis_recycle when the consumer runs on IIS and must reload the updated secret after the file sync step completes.

Required fields:

  • agent_id: Connected Windows MazeVault agent with IIS management permissions.
  • app_pool: IIS application pool name to recycle.

Operator notes:

  • Place this step after agent_secret_sync so IIS only recycles after the new credential is present on disk.
  • Legacy site_name is still accepted for compatibility, but MazeVault normalizes it to app_pool.

Example:

[
    {
        "type": "agent_secret_sync",
        "order": 10,
        "on_failure": "abort",
        "agent_id": "11111111-1111-1111-1111-111111111111",
        "config": {
            "target_path": "C:\\inetpub\\app\\appsettings.json",
            "secret_key": "Entra:ClientSecret",
            "file_format": "json"
        }
    },
    {
        "type": "iis_recycle",
        "order": 20,
        "on_failure": "continue",
        "agent_id": "11111111-1111-1111-1111-111111111111",
        "config": {
            "app_pool": "DefaultAppPool"
        }
    }
]

Preflight and Rollout Guidance

  • Use Dry Run before a production rotation to validate Entra authentication, Key Vault reachability, and agent readiness.
  • If preflight reports manual review required for a direct agent_url, confirm host reachability and Windows/IIS permissions before rotation.
  • If a non-aborting deployment step fails, MazeVault marks the execution for operator attention instead of reporting a fully healthy rollout.
  • Review execution history after rollout. MazeVault records human-readable delivery step names and rollout summaries for faster incident triage.
  • Use the Project Rotations tab as the cross-resource summary view. It now shows inline readiness for Entra credentials and the related certificate rotation resources that share the same rollout surface.

Rotation Inventory Cleanup on Removal

  • Removing an Entra integration or a locally managed app registration now removes the corresponding rotation resource entries in the same lifecycle operation.
  • Upgrade cleanup also removes stale historical Entra rotation rows from older releases, keeping the Project Rotations inventory aligned with the actual Entra objects.

6. Monitor Rotation History

View the complete rotation history for any credential or app registration, including: - Rotation type (manual/automatic) - Duration - Steps completed - Any errors encountered

Lifecycle States

State Description
Active Credential is valid and in use
Expiring Soon Credential expires within threshold
Rotating Rotation in progress
Grace Period Both old and new credentials are valid
Expired Credential has expired
Cleaned Up Old credential removed after grace period

Security

  • All credential values are encrypted at rest with AES-256-GCM
  • Graph API calls use exponential backoff with retry
  • OData filter inputs are sanitized to prevent injection
  • RBAC permissions: entra:read, entra:write, entra:rotate

Troubleshooting

Rotation Failed

Check the rotation history for error details. Common causes: - Insufficient Graph API permissions - Key Vault access denied - Agent offline or unreachable during file deployment - IIS permissions missing on the Windows target agent - Network connectivity issues

Credentials Not Syncing

Verify: - Integration is enabled - Service principal has Application.ReadWrite.All permission - Tenant ID and Client ID are correct