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. Environment Variables (highest priority).
2. Azure Table Storage (fallback if no environment variable is found).

If no mapping exists, the original token is returned.

Configuration Steps

1. 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

2. Using Azure Table Storage

  • Step 1: Create a table named TokenMapping in your Azure Storage Account.
  • Step 2: Add entries where:
  • PartitionKey: Original token (e.g., Dev_Admins).
  • RowKey: Mapped token (e.g., Prod_Admins).

Example Table Entry:
| PartitionKey | RowKey |
|----------------|---------------|
| Dev_Admins | Prod_Admins |
| Test_User | Production_User|

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:
- Environment Variable:

AAD_TOKEN_MAPPING=Dev_Admins:Prod_Admins
- Azure Table Entry:
- PartitionKey: Dev_Admins
- RowKey: 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:
- 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. Check application logs for errors (e.g., invalid token formats, missing Azure tables).
  2. Use the TestTokenMapping unit tests to validate mappings in development.
  3. Verify permissions in the application UI to ensure tokens resolve correctly.

Troubleshooting

Issue Solution
Mappings not applied Ensure the AAD_TOKEN_MAPPING variable is set correctly or Azure Table entries exist.
Token resolution errors Check logs for provider initialization failures.
Azure Table not found Run the UpdateAppSchema function to create the table. Or create TokenMapping table manualy