Skip to content

Dynamically grant permissions to Entra ID Security Groups based on environment with TokenMappings

Configuration Scope: Environment-Specific

This setting is environment-specific and must be configured separately in each environment (dev, test, prod). Changes here will not be included in configuration exports.

The Token Mapping feature allows administrators to dynamically resolve tokens (e.g., group names, user IDs) to their actual values in different environments (e.g., development, production). This ensures flexibility and consistency when managing permissions across environments.

When to Use This Feature

  • Map development group names to production group names.
  • Resolve placeholder user IDs to actual IDs in specific environments.
  • Centralize token management for permissions, reducing hard-coded values.

How Token Mapping Works

Tokens are resolved in the following order:

  1. Stored token mappings (managed in the Admin Panel).
  2. Environment variables (AAD_TOKEN_MAPPING).

If no mapping exists, the original token is returned.

If a token exists in both stored mappings and AAD_TOKEN_MAPPING, the stored mapping is used.

Configuration Steps

Use this method to manage token mappings per environment through the application UI.

  1. Navigate to the Admin Panel (/#/adminPanel).
  2. Open the Token Mapping tab.
  3. Add or update mappings in the format:
  4. Token: the placeholder value used in configuration (e.g. Dev_Admins)
  5. Mapped value: the real value for this environment (e.g. Prod_Admins or an Entra ID group name)
  6. Save your changes.

Scope

Token mappings are environment-specific. Configure them separately in each environment (dev/test/prod).

2. Using Environment Variables

  • Step 1: Set the AAD_TOKEN_MAPPING environment variable in your application’s hosting environment (e.g., Azure App Service, local development).
  • Step 2: Use the format [OriginalToken]:[MappedToken], separating entries with semicolons (;).

Example:

AAD_TOKEN_MAPPING=Dev_Admins:Prod_Admins;Test_User:Production_User
  • Dev_Admins → Maps to Prod_Admins
  • Test_User → Maps to Production_User

DevOps

image.png OR image.png

Older deployments documented token mappings as an Azure Storage Table named TokenMapping.

For current versions, manage token mappings through the Admin Panel (Token Mapping tab) instead of editing storage directly.

Examples

Example 1: Mapping Group Names

Scenario: A role assignment uses the group Dev_Admins in development but needs to map to Prod_Admins in production.

Configuration:

  • Admin Panel (Token Mapping):
  • Token: Dev_Admins
  • Mapped value: Prod_Admins

Alternatively, set the environment variable:

AAD_TOKEN_MAPPING=Dev_Admins:Prod_Admins

Result: Users in Prod_Admins will receive permissions assigned to Dev_Admins.

Example 2: Resolving User IDs

Scenario: A user ID Test_User in development maps to Production_User in production.

Configuration: You can configure this in the Admin Panel (Token Mapping) or via the environment variable:

AAD_TOKEN_MAPPING=Test_User:Production_User

Result: Permissions assigned to Test_User will apply to Production_User.

Note: Use user Entra ID, do not use UPN or Email or LoginName. Example: Test_User:125a335b-191f-4853-8990-b1f9db1dba1a

Verifying Mappings

  1. In the Admin Panel, confirm the mapping exists in Token Mapping for the current environment.
  2. Check application logs for errors (e.g., invalid token formats, provider initialisation failures).
  3. Verify permissions in the application UI to ensure tokens resolve correctly.

Troubleshooting

Issue Solution
Mappings not applied Ensure a mapping exists in the Admin Panel (Token Mapping) or AAD_TOKEN_MAPPING is set correctly.
Token resolution errors Check logs for provider initialization failures.
Can't edit mappings Ensure you have System Administrator access and are using the correct environment.