IAM Integration
The Enterprise Stack integrates with external Identity Providers (IdP) for centralized user authentication and access management. See the access and permissions overview to learn about the broader security architecture.
Supported providers include:
- Keycloak
- Microsoft Entra ID (Azure AD)
- Okta
- Auth0
- Any OpenID Connect (OIDC) compatible provider
In this setup:
- The IAM provider handles authentication
- The Enterprise Stack handles authorization using RBAC
Authentication Flow
- User authenticates with the IAM provider
- IAM provider issues an OIDC token (JWT)
- Client sends the token with the API request
- Enterprise Stack validates the token
- RBAC evaluates roles and permissions for the requested operation
Configuring OIDC Login
OIDC login is configured in auth.conf by adding an entry with method = "oidc" to the authFlows list.
The required fields are:
| Field | Description |
|---|---|
openIdConfigurationUrl | URL to your IdP's OpenID Connect discovery document (e.g. https://your-idp/.well-known/openid-configuration) |
clientId | OIDC client ID registered at your IdP |
clientSecret | OIDC client secret |
callbackUri | Callback URL handled by the Enterprise Stack after IdP login |
accountIdentifierClaim | Claim used to uniquely identify the external account (commonly sub) |
pkceEnabled | Enables PKCE — recommended for security |
See the auth.conf reference for the full configuration example and all available fields.
Mapping IAM Identities to Enterprise Roles
When a user logs in via OIDC, their external roles or groups need to be mapped to Enterprise Stack role IDs. This is done with externalRoleMapping in auth.conf.
Key settings:
| Field | Description |
|---|---|
enabled | Turns role mapping on or off |
strict | If true, login fails when no mapping matches. If false, unmapped roles are silently ignored |
mappings | List of { externalRole, roleId } pairs |
Each entry maps an external role value (as asserted by your IdP) to an Enterprise Stack role ID:
{ externalRole = "acme-wallet-operator", roleId = "waltid.acme.BW_OPERATOR" }
In multi-tenant deployments, use tenant-scoped role IDs (waltid.<tenant>.<role>) and define a mapping for each tenant explicitly.
See the auth.conf reference for a full example with multiple tenants.
The Enterprise Stack role IDs used in externalRoleMapping must already exist. Make sure you have created the roles before defining mappings.