---
title: "External Role Mapping"
description: "External Role Mapping automatically assigns Enterprise Stack permissions to users based on their roles in an external Identity Provider (IdP). When users authenticate via OIDC, their IdP roles are mapped to Enterprise…"
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
generated: 2026-07-20
---
# External Role Mapping

External Role Mapping automatically assigns Enterprise Stack permissions to users based on their roles in an external Identity Provider (IdP). When users authenticate via OIDC, their IdP roles are mapped to Enterprise roles, granting them the appropriate permissions without manual role assignment.

## Why Use External Role Mapping?

- **Centralized Access Control** — Manage user permissions in your existing IAM system
- **Automatic Provisioning** — Users get correct permissions on first login
- **Consistent Security** — Single source of truth for role definitions
- **Reduced Administration** — No need to manually assign Enterprise roles to each user

## How It Works

```text
┌────────────────────┐      ┌─────────────────────┐      ┌────────────────────┐
│   Identity         │      │   Enterprise        │      │   Enterprise       │
│   Provider (IdP)   │      │   Stack API         │      │   Permissions      │
│                    │      │                     │      │                    │
│  User logs in      │─────▶│  Validates token    │─────▶│  Grants mapped     │
│  with role:        │      │  Extracts roles     │      │  permissions       │
│  "tenant-admin"    │      │  from claims        │      │                    │
│                    │      │                     │      │  Role: BW_ADMIN    │
│  ID Token contains:│      │  Finds mapping:     │      │  Permissions:      │
│  realm_access:     │      │  tenant-admin →     │      │  - wallet:create   │
│    roles:          │      │  waltid.tenant1     │      │  - wallet:read     │
│    - tenant-admin  │      │  .BW_ADMIN          │      │  - ...             │
└────────────────────┘      └─────────────────────┘      └────────────────────┘
```

1. User authenticates with IdP (Keycloak, Okta, Azure AD, etc.)
2. IdP issues an ID token containing the user's roles
3. User presents the token to Enterprise Stack
4. Enterprise Stack extracts roles from the token
5. Role mappings are evaluated to find matching Enterprise roles
6. User receives permissions from all matched Enterprise roles

## Supported Identity Providers

External Role Mapping works with any OIDC-compliant Identity Provider:

| Provider | Role Claim Location |
|----------|---------------------|
| Keycloak | `realm_access.roles` or `resource_access.{client}.roles` |
| Microsoft Entra ID | `roles` or `groups` |
| Okta | `groups` or custom claims |
| Auth0 | Custom claims via Rules/Actions |
| Google Workspace | Custom claims |
| Any OIDC Provider | Configurable claim path |

## Get Started

1. [Overview](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/overview.md) — Understand mapping concepts and flow
2. [Configure IdP](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/configure-idp.md) — Set up your Identity Provider to include roles in tokens
3. [Create Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/create-mappings.md) — Define role mappings via API
4. [Manage Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/manage-mappings.md) — List, update, and delete mappings
5. [Test Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/test-mappings.md) — Verify mappings before deploying
6. [Conditional Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/conditional-mappings.md) — Add conditions like email domain restrictions

## Configuration Options

External role mappings can be managed in two ways:

### Option 1: REST API (Recommended)

Create and manage mappings dynamically via API — no config changes or restarts needed:

```bash
curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings/tenant-admin' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{ "enabled": true }'
```

### Option 2: Config File (Optional)

Add `externalRoleMapping` to `auth.conf`:

```hocon
externalRoleMapping = {
  enabled = true
  strict = false
  mappings = [
    { externalRole = "admin", roleId = "org.tenant1.ADMIN" }
  ]
}
```

**Info:**

The `externalRoleMapping` config section is **optional**. If omitted, it defaults to `enabled=false`. API-based mappings are recommended for production.

## Quick Example

Map Keycloak role `tenant-admin` to Enterprise role `waltid.tenant1.BW_ADMIN`:

```bash
curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings/tenant-admin' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{ "enabled": true }'
```

Now when a user logs in via OIDC with the `tenant-admin` role, they automatically receive all permissions from `BW_ADMIN`.

## Related

- [IAM Integration](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/iam-integration.md) — Configure OIDC providers
- [Roles](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/roles/overview.md) — Create and manage Enterprise roles
- [Permissions](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/permissions/overview.md) — Available permission types