#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

┌────────────────────┐      ┌─────────────────────┐      ┌────────────────────┐
│   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:

#Get Started

1. Overview — Understand mapping concepts and flow
2. Configure IdP — Set up your Identity Provider to include roles in tokens
3. Create Mappings — Define role mappings via API
4. Manage Mappings — List, update, and delete mappings
5. Test Mappings — Verify mappings before deploying
6. Conditional Mappings — 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:

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:

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

#Quick Example

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

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 — Configure OIDC providers
• Roles — Create and manage Enterprise roles
• Permissions — Available permission types