---
title: "Test Mappings"
description: "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."
stack: "Enterprise Stack (commercial) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/test-mappings
generated: 2026-07-20
---
# 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

**Option: CURL**

```bash
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"]
  }'
```

**Option: Response**

```json
{
  "resolvedRoleIds": [
    "waltid.tenant1.BW_ADMIN"
  ],
  "matchedMappings": [
    {
      "externalRole": "tenant-admin",
      "roleId": "waltid.tenant1.BW_ADMIN",
      "enabled": true
    }
  ]
}
```

**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:

```bash
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:

```json
{
  "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:

```bash
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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

### 1. Login via OIDC

```
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:

```bash
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:

```bash
# 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:

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

## Next Steps

- [Conditional Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/conditional-mappings.md) — Add email domain restrictions
- [Troubleshooting](../../../troubleshooting) — Common issues and solutions