member-console/docs/identity-provider-setup.md

title, audience, summary

title	audience	summary
Identity Provider Setup	admin developer	Configure an OIDC identity provider (Keycloak-focused) so the console can authenticate users and assign the operator role.

Identity Provider Setup

This guide covers configuring your OIDC identity provider to work with the member console. The examples use Keycloak but the concepts apply to any OIDC-compliant provider.

Prerequisites

• An OIDC identity provider with a client configured for Authorization Code + PKCE flow
• The client ID and secret configured in mc-config.yaml (or equivalent flags)
• Refresh tokens issued to the client (Keycloak's default). Two things use them: every five minutes a signed-in session re-derives its identity and roles from a fresh ID token, so a role removed, an account disabled, or a session ended at the provider takes effect here within that bound; and sign-out mints a fresh ID token for a valid id_token_hint, so the provider ends its session without asking. Without a refresh token a session keeps its sign-in roles for its lifetime and the provider prompts at sign-out. The roles claim must be present in the ID token a refresh returns, not only the one sign-in returns (Keycloak's mappers do both).
• end_session_endpoint published in the provider's discovery document (OpenID Connect RP-Initiated Logout 1.0). The console refuses to start without it.
• revocation_endpoint published in the discovery document (RFC 7009), so the console can revoke the refresh token at sign-out. Optional; without it the console warns once at startup and skips revocation.

Standard OIDC Claims

The member console reads the following standard claims from the ID token:

Claim	Used for
sub	Unique user identifier (OIDC subject)
email	User's primary email
email_verified	Whether the email is verified
name	Display name
preferred_username	Username (used for org slug derivation)

On first login, the member console auto-provisions a person, organization, and workspace from these claims.

Role-Based Access: Operator Role

The member console uses a single application-level role to gate access to the operator panel:

• Role name: operator-member
• Where it's checked: internal/server/operator.go and operator_partials.go

How roles are extracted

The member console extracts roles from the ID token, the token OIDC defines for the client to consume, after it has passed signature and nonce verification. The access token is not read: OAuth2 leaves its format opaque, so parsing it would only work with providers that happen to issue JWT access tokens. Within the ID token the console reads every claim location an identity provider might use to carry roles, rather than trusting only one:

1. roles (top-level array)
2. groups (top-level array)
3. realm_access.roles (Keycloak realm roles)
4. resource_access.<client-id>.roles (Keycloak client-scoped roles, read only for this app's configured client ID; roles belonging to other clients are never included)

The member console reads all four locations and merges their roles into one deduplicated list: a role that appears in more than one location is kept once, at the position where it first appears (the locations are read in the order listed above, and within a location, in the order the claim lists them). Because every location is read, a deployment can put operator-member in whichever claim its identity provider produces and the member console still recognizes it.

If the ID token carries none of the four locations at all, the identity provider is not mapping roles into the ID token. The console logs a warning naming the signed-in email and this document on every such login; without it, the only symptom would be an operator who cannot get into the operator panel. A location that is present but empty is an ordinary member with no roles and is not logged.

Keycloak setup

There are two ways to make the operator-member role visible in the ID token:

Option A: Client role with a protocol mapper (recommended)

1. Go to Clients > member-console > Roles
2. Create a role named operator-member
3. Assign it to the desired user(s) under Users > (user) > Role Mappings > member-console
4. Ensure there is a protocol mapper that emits client roles into a top-level roles claim in the ID token:
   • Mapper type: User Client Role
   • Client ID: member-console
   • Token Claim Name: roles
   • Claim JSON Type: String
   • Multivalued: On
   • Add to ID token: On (Add to access token is not required)

This is the approach used by the test stack's Keycloak seed (test/seed/keycloak/seed-keycloak.sh).

Option B: Realm role

1. Go to Realm Roles
2. Create a role named operator-member
3. Assign it to the desired user(s)
4. Enable Add to ID token on the realm roles mapper (Client scopes > roles > Mappers > realm roles); it is off by default, so without this step the role reaches only the access token, which the console does not read. The role then appears in realm_access.roles in the ID token.

This is simpler but mixes application roles with realm-level roles.

Other identity providers

For providers other than Keycloak, ensure that the ID token includes operator-member in one of the four checked claim locations (roles, groups, realm_access.roles, or resource_access.<client-id>.roles). Most providers support custom claims or group mappings that can achieve this.

Temporal Authorization

Temporal requires its own role setup for JWT-based authorization. See Temporal Authorization Setup for the full Temporal permissions configuration.

Test Environment

The test stack's Keycloak seed (test/seed/keycloak/seed-keycloak.sh) pre-configures:

• A member-console client with the operator-member client role defined
• The admin user mapped to the operator-member role
• Protocol mappers that emit roles into the ID token (and the access token)

To use the test environment:

cd test
docker compose up -d
member-console start

Login with admin / admin at http://localhost:8081 — this is Keycloak's own admin console, a separate system from member-console itself. The console's operator login (alice / password) is covered in the README quickstart.

Run app OIDC on a dedicated realm, not Keycloak's master admin realm. The member-facing "Identity and Access" link opens Keycloak's account console; on the master admin realm that console errors ("Something went wrong") because the minted token carries no aud: account claim. The test stack therefore creates and runs on a dedicated test realm, where the account console works out of the box — do the same in production. See status/issues.md.

Note: The first member-console start after a fresh docker compose up -d used to fail with a Temporal auth error. This is fixed — compose now gates Temporal on its database and Keycloak being healthy, and member-console retries the initial Temporal connection. See status/issues.md.