---
title: "Overview"
description: "External Role Mapping bridges your Identity Provider's role system with the Enterprise Stack's permission model. This page explains the core concepts and how the mapping process works."
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/overview
generated: 2026-07-20
---
# Overview

External Role Mapping bridges your Identity Provider's role system with the Enterprise Stack's permission model. This page explains the core concepts and how the mapping process works.

## Key Concepts

### External Roles

External roles are role identifiers that come from your Identity Provider (IdP). They appear in the ID token after a user authenticates:

```json
{
  "sub": "user-uuid",
  "email": "alice@company.com",
  "realm_access": {
    "roles": ["tenant-admin", "user"]
  }
}
```

In this example, `tenant-admin` and `user` are external roles.

### Enterprise Roles

Enterprise roles are defined within the Enterprise Stack and contain specific permissions. They follow a hierarchical naming pattern:

```
{organization}.{tenant}.{role-name}
```

For example: `waltid.tenant1.BW_ADMIN`

### Mappings

A mapping connects an external role to an Enterprise role:

| External Role | → | Enterprise Role |
|---------------|---|-----------------|
| `tenant-admin` | → | `waltid.tenant1.BW_ADMIN` |
| `wallet-operator` | → | `waltid.tenant1.BW_OPERATOR` |

## Mapping Resolution

When a user authenticates via OIDC, the Enterprise Stack:

1. **Extracts external roles** from the ID token claims
2. **Queries active mappings** within the relevant scope
3. **Evaluates conditions** (if any) for each mapping
4. **Collects Enterprise role IDs** from all matching mappings
5. **Loads permissions** from the matched Enterprise roles
6. **Grants access** based on combined permissions

```text
ID Token                     Mappings                    Permissions
───────────                  ────────                    ───────────
realm_access.roles:          tenant-admin                BW_ADMIN permissions:
  - tenant-admin       ───▶  → waltid.t1.BW_ADMIN  ───▶  - ES_WALLET_CREATE
  - user                     user                        - ES_WALLET_READ
                             → (no mapping)              - ES_KEY_CREATE
                                                         - ...
```

## Scope Hierarchy

Mappings are scoped to specific targets in your organization hierarchy:

```text
Organization (waltid)
├── Tenant A (waltid.tenantA)
│   ├── Role: BW_ADMIN    ← Mapping can target this
│   └── Role: BW_OPERATOR ← Or this
├── Tenant B (waltid.tenantB)
│   └── Role: BW_USER
└── Org-level Role (waltid.GLOBAL_ADMIN)
```

When resolving mappings, the system checks:
1. Mappings on the specific role
2. Mappings on the tenant scope
3. Mappings on the organization scope

## Multiple Mappings

A single external role can map to multiple Enterprise roles, and a user can have multiple external roles:

```text
User's External Roles     Mappings                      Effective Permissions
─────────────────────     ────────                      ─────────────────────
[tenant-admin]      ───▶  tenant-admin → BW_ADMIN  ───▶ All BW_ADMIN permissions
                                                        +
[wallet-reader]     ───▶  wallet-reader → READER  ───▶  All READER permissions
```

The user receives the **union** of all permissions from all matched roles.

## Direct vs Mapped Roles

Users can have both:
- **Direct roles**: Explicitly assigned to their Enterprise account
- **Mapped roles**: Automatically granted based on external role mapping

The effective permissions are the combination of both.

```text
User Permissions = Direct Role Permissions + Mapped Role Permissions
```

## Mapping Lifecycle

Mappings can be:
- **Created** — Define a new external-to-enterprise mapping
- **Enabled/Disabled** — Toggle without deleting
- **Updated** — Modify conditions or settings
- **Deleted** — Remove permanently

Changes take effect on the **next login**. Existing sessions retain their original permissions until the token expires.

## Provider-Agnostic Design

The mapping system is designed to work with any OIDC provider:

| Provider | How to Configure Roles |
|----------|----------------------|
| **Keycloak** | Realm roles appear in `realm_access.roles` by default |
| **Azure AD** | App roles in `roles` claim, groups in `groups` claim |
| **Okta** | Groups in `groups` claim, or custom claims |
| **Auth0** | Custom claims via Rules or Actions |

The Enterprise Stack extracts roles from the configured claim paths and matches them against your mappings.

## Next Steps

- [Configure IdP](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/configure-idp.md) — Ensure your IdP includes roles in tokens
- [Create Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/create-mappings.md) — Define your first mapping