#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

OIDC login is configured in auth.conf. Add an entry with method = "oidc" to the authFlows list.

#Minimal Configuration

authFlows = [
  {
    method = "oidc"
    config = {
      openIdConfigurationUrl = "https://your-idp/.well-known/openid-configuration"
      clientId = "your_client_id"
      clientSecret = "your_client_secret"
      callbackUri = "https://your-enterprise-host/auth/account/oidc/callback"
      pkceEnabled = true
      externalRoleExtraction = {
        enabled = true
        realmRolesClaimPath = "realm_access.roles"
      }
    }
    success = true
  }
]

For the complete list of OIDC configuration options including dynamic redirects and logout settings, see the auth.conf reference.

#Mapping IAM Roles to Enterprise Permissions

When users authenticate via OIDC, their external roles can be automatically mapped to Enterprise Stack permissions. This is called External Role Mapping.

#How It Works

User logs in via your IdP with roles (e.g., tenant-admin)
Enterprise Stack extracts roles from the ID token (via externalRoleExtraction)
Role mappings are evaluated to find matching Enterprise roles
User receives permissions from all matched Enterprise roles

#Managing Role Mappings

External role mappings can be managed via REST API (recommended) or config file.

#REST API (Recommended)

# Create a mapping: external role → Enterprise role
curl -X PUT \
  'https://{host}/v1/waltid.tenant1.BW_ADMIN/roles-api/roles/external-mappings/tenant-admin' \
  -H 'Authorization: Bearer {token}' \
  -d '{"enabled": true}'

This maps the external role tenant-admin to the Enterprise role waltid.tenant1.BW_ADMIN.