#Test Mappings

Before relying on external role mappings in production, test them to ensure they work correctly. The Enterprise Stack provides a resolution endpoint for this purpose.

#Resolution Endpoint

Test which Enterprise roles would be assigned for a given set of external roles:

POST /v1/{scope}/roles-api/roles/external-mappings/resolve

This endpoint simulates the mapping process without requiring an actual OIDC login.

#Basic Test

CURL

Response

curl -X POST \
  'https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalRoles": ["tenant-admin"]
  }'

Request Body

Field	Type	Required	Description
`externalRoles`	string	Yes	List of external roles to test
`email`	string	No	Test email for condition evaluation
`providerId`	string	No	Test specific provider

#Test Multiple Roles

Test how multiple external roles resolve:

curl -X POST \
  'https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve' \
  -H 'Authorization: Bearer {token}' \
  -d '{
    "externalRoles": ["tenant-admin", "wallet-operator", "viewer"]
  }'

Response shows all matched Enterprise roles:

{
  "resolvedRoleIds": [
    "waltid.tenant1.BW_ADMIN",
    "waltid.tenant1.BW_OPERATOR"
  ],
  "matchedMappings": [
    {
      "externalRole": "tenant-admin",
      "roleId": "waltid.tenant1.BW_ADMIN"
    },
    {
      "externalRole": "wallet-operator", 
      "roleId": "waltid.tenant1.BW_OPERATOR"
    }
  ],
  "unmatchedRoles": ["viewer"]
}

Note: viewer appears in unmatchedRoles because no mapping exists for it.

#Test with Email Conditions

If you have mappings with email domain conditions, test them:

curl -X POST \
  'https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve' \
  -H 'Authorization: Bearer {token}' \
  -d '{
    "externalRoles": ["contractor"],
    "email": "john@contractor.com"
  }'

The mapping for contractor might only match if the email domain is allowed.

#Test Provider-Specific Mappings

If mappings are restricted to specific providers:

curl -X POST \
  'https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve' \
  -H 'Authorization: Bearer {token}' \
  -d '{
    "externalRoles": ["admin"],
    "providerId": "keycloak-prod"
  }'

#Verification Checklist

Before deploying to production, verify:

#1. All Expected Roles Map Correctly

# Test each external role you expect users to have
for role in tenant-admin wallet-operator viewer; do
  echo "Testing: $role"
  curl -s -X POST "https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve" \
    -H "Authorization: Bearer {token}" \
    -d "{\"externalRoles\": [\"$role\"]}" | jq '.resolvedRoleIds'
done

#2. No Unexpected Mappings

# Test roles that should NOT map
curl -X POST "https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve" \
  -H "Authorization: Bearer {token}" \
  -d '{"externalRoles": ["unknown-role"]}'

Expected: resolvedRoleIds should be empty.

#3. Conditions Work

# Test with matching email domain
curl -X POST "https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve" \
  -H "Authorization: Bearer {token}" \
  -d '{"externalRoles": ["employee"], "email": "user@company.com"}'

# Test with non-matching email domain  
curl -X POST "https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve" \
  -H "Authorization: Bearer {token}" \
  -d '{"externalRoles": ["employee"], "email": "user@other.com"}'

#4. Provider Restrictions Work

# Test with correct provider
curl -X POST "https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve" \
  -H "Authorization: Bearer {token}" \
  -d '{"externalRoles": ["admin"], "providerId": "keycloak"}'

# Test with wrong provider
curl -X POST "https://{host}/v1/waltid/roles-api/roles/external-mappings/resolve" \
  -H "Authorization: Bearer {token}" \
  -d '{"externalRoles": ["admin"], "providerId": "okta"}'

#End-to-End Testing

After verifying with the resolution endpoint, test with actual OIDC login:

GET https://{host}/auth/account/oidc/auth

Complete login in the IdP with a test user.

#2. Check Effective Permissions

After login, verify the user's permissions:

curl -X GET \
  'https://{host}/v1/permissions/list-role-and-permissions' \
  -H 'Authorization: Bearer {user-token}'

Response should show:

mappedRoleIds — Roles from external mapping
directRoleIds — Directly assigned roles (if any)
effectivePermissions — Combined permissions

#3. Test API Access

Verify the user can perform expected operations:

# Should succeed if user has wallet:create permission
curl -X POST 'https://{host}/v1/{target}/wallet-service-api/wallets/create' \
  -H 'Authorization: Bearer {user-token}' \
  -d '{...}'

#Debugging Failed Mappings

If mappings don't work as expected:

Check the ID token — Are roles present in the expected claim?
Verify claim path — Does Enterprise Stack config match IdP output?
Check mapping exists — Use list endpoint to verify
Check mapping is enabled — enabled: true?
Check conditions — Are email domain or provider conditions met?
Check target role exists — Does the Enterprise role ID exist?

#Next Steps

Conditional Mappings — Add email domain restrictions
Troubleshooting — Common issues and solutions

Last updated on May 4, 2026

Manage Mappings Conditional Mappings