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

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

#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

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:

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:

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.

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:

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

#Next Steps

• Configure IdP — Ensure your IdP includes roles in tokens
• Create Mappings — Define your first mapping