---
title: "IAM Integration"
description: "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."
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/iam-integration
generated: 2026-07-20
---
# IAM Integration

The Enterprise Stack integrates with external **Identity Providers (IdP)** for centralized user authentication and access management. See the [access and permissions overview](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/overview.md) 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

1. User authenticates with the IAM provider
2. IAM provider issues an OIDC token (JWT)
3. Client sends the token with the API request
4. Enterprise Stack validates the token
5. RBAC evaluates roles and permissions for the requested operation

## Configuring OIDC Login

OIDC login is configured in [`auth.conf`](https://docs.walt.id/enterprise-stack/setup/configurations/config-files/auth.md). Add an entry with `method = "oidc"` to the `authFlows` list.

### Minimal Configuration

```hocon
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
  }
]
```

**Info:**

For the complete list of OIDC configuration options including dynamic redirects and logout settings, see the [auth.conf reference](https://docs.walt.id/enterprise-stack/setup/configurations/config-files/auth.md#oidc-flow-fields-method--oidc).

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

1. User logs in via your IdP with roles (e.g., `tenant-admin`)
2. Enterprise Stack extracts roles from the ID token (via `externalRoleExtraction`)
3. Role mappings are evaluated to find matching Enterprise roles
4. 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)

```bash
# 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`.

#### Config File (Optional)

See [auth.conf - External Role Mapping](https://docs.walt.id/enterprise-stack/setup/configurations/config-files/auth.md#external-role-mapping-externalrolemapping) for config-based mappings.

### Key Features

- **Provider-agnostic** — Works with any OIDC provider
- **Conditional mappings** — Restrict by email domain or provider
- **Multi-tenant support** — Different mappings per tenant
- **Dynamic management** — Create, update, delete via API (no restart needed)

### Learn More

See the [External Role Mapping](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping.md) section for complete documentation:

- [Overview](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/overview.md) — Understand mapping concepts
- [Configure IdP](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/configure-idp.md) — Set up role claims in your IdP
- [Create Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/create-mappings.md) — Define mappings via API
- [Manage Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/manage-mappings.md) — List, update, delete mappings
- [Test Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/test-mappings.md) — Verify mappings work
- [Conditional Mappings](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/conditional-mappings.md) — Add restrictions

## IdP Configuration Requirements

For external role mapping to work, your IdP must include roles in the ID token. Common configurations:

| Provider | Role Claim Location |
|----------|---------------------|
| Keycloak | `realm_access.roles` |
| Azure AD | `roles` or `groups` |
| Okta | `groups` claim |
| Auth0 | Custom claims via Actions |

See [Configure IdP](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping/configure-idp.md) for detailed setup instructions for each provider.

## Related

- [Auth configuration (`auth.conf`)](https://docs.walt.id/enterprise-stack/setup/configurations/config-files/auth.md) — Complete auth.conf reference
- [External Role Mapping](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/external-role-mapping.md) — Complete mapping documentation
- [RBAC Model](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/rbac-model.md)
- [Roles](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/roles/overview.md)
- [Permissions](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/permissions/overview.md)