diff --git a/docs/administration/oidc/index.md b/docs/administration/oidc/index.md index 867ada2..490728b 100644 --- a/docs/administration/oidc/index.md +++ b/docs/administration/oidc/index.md @@ -70,13 +70,33 @@ environment: - OIDC_ROLE_ADMIN=romm-admin,platform-admins # group values → Admin ``` -On every login, the claim named by `OIDC_CLAIM_ROLES` is read (often `groups`, sometimes `realm_access.roles` on Keycloak, check your provider's token output). If a value matches `OIDC_ROLE_ADMIN`, the user becomes an Admin; otherwise they're a User in the default permission group. +On every login, the claim named by `OIDC_CLAIM_ROLES` is read (often `groups`, sometimes `realm_access.roles` on Keycloak, check your provider's token output). If a value matches `OIDC_ROLE_ADMIN`, the user becomes an Admin. Roles are re-evaluated on **every login**, so demoting someone on the IdP side takes effect the next time they sign in. + -!!! note "Legacy role variables" - `OIDC_ROLE_VIEWER` and `OIDC_ROLE_EDITOR` still exist for backwards compatibility but no longer map to distinct roles. Matching users now resolve to **User**. Use permission groups for finer-grained access, as only `OIDC_ROLE_ADMIN` still changes the role. +!!! warning "Once `OIDC_CLAIM_ROLES` is set, users must match a mapped group" + As soon as `OIDC_CLAIM_ROLES` is configured, RomM expects every user to match at least one mapped role group. A user whose claim matches **none** of the configured groups is rejected at login with: + + ```json + {"detail":"User has not been granted any roles for this application."} + ``` + + To let non-admin users in, map their group to the **User** role with `OIDC_ROLE_VIEWER` (or `OIDC_ROLE_EDITOR`): + + ```yaml + environment: + - OIDC_CLAIM_ROLES=groups + - OIDC_ROLE_ADMIN=romm-admin,platform-admins # → Admin + - OIDC_ROLE_VIEWER=platform-users # non-admins → User (grants access) + ``` + + `OIDC_ROLE_VIEWER` and `OIDC_ROLE_EDITOR` no longer map to distinct roles — matching users all resolve to **User** — but they're still how you grant those users access when role claims are enabled. Point them at a group that all your non-admin users belong to. Use [permission groups](../users-and-roles.md#permission-groups) for finer-grained access; only `OIDC_ROLE_ADMIN` changes the role. + + If you *don't* set `OIDC_CLAIM_ROLES` at all, role mapping is skipped entirely and everyone is provisioned as a **User** in the default permission group. + + ## Autologin diff --git a/docs/resources/snippets/env-vars.md b/docs/resources/snippets/env-vars.md index c93e9d9..07bd40a 100644 --- a/docs/resources/snippets/env-vars.md +++ b/docs/resources/snippets/env-vars.md @@ -51,25 +51,25 @@ ### OpenID Connect -| Variable | Default | Required | Description | -| ----------------------------- | -------------------- | :------: | ------------------------------------------------------------------ | -| `OIDC_ENABLED` | `false` | | Enable OpenID Connect authentication | -| `OIDC_AUTOLOGIN` | `false` | | Skip the OIDC button on the login page and auto-redirect | -| `OIDC_ALLOW_REGISTRATION` | `true` | | Allow new accounts to be created automatically on first OIDC login | -| `OIDC_PROVIDER` | | | Name of the OIDC provider in use | -| `OIDC_CLIENT_ID` | | | Client ID for OIDC authentication | -| `OIDC_CLIENT_SECRET` | | | Client secret for OIDC authentication | -| `OIDC_REDIRECT_URI` | | | Absolute redirect URI for OIDC authentication | -| `OIDC_SERVER_APPLICATION_URL` | | | Absolute URL of the OIDC server application | -| `OIDC_SERVER_METADATA_URL` | | | URL to the OIDC provider metadata endpoint | -| `OIDC_CLAIM_ROLES` | | | OIDC claim containing user roles | -| `OIDC_ROLE_VIEWER` | | | Role value mapping to viewer permissions | -| `OIDC_ROLE_EDITOR` | | | Role value mapping to editor permissions | -| `OIDC_ROLE_ADMIN` | | | Role value mapping to admin permissions | -| `OIDC_TLS_CACERTFILE` | | | Path to file containing trusted CA certificates | -| `OIDC_USERNAME_ATTRIBUTE` | `preferred_username` | | Attribute on OIDC user info used as the username | -| `OIDC_RP_INITIATED_LOGOUT` | `false` | | Enable RP-initiated logout flow | -| `OIDC_END_SESSION_ENDPOINT` | | | OIDC end-session endpoint override URL | +| Variable | Default | Required | Description | +| ----------------------------- | -------------------- | :------: | ------------------------------------------------------------------------------------------- | +| `OIDC_ENABLED` | `false` | | Enable OpenID Connect authentication | +| `OIDC_AUTOLOGIN` | `false` | | Skip the OIDC button on the login page and auto-redirect | +| `OIDC_ALLOW_REGISTRATION` | `true` | | Allow new accounts to be created automatically on first OIDC login | +| `OIDC_PROVIDER` | | | Name of the OIDC provider in use | +| `OIDC_CLIENT_ID` | | | Client ID for OIDC authentication | +| `OIDC_CLIENT_SECRET` | | | Client secret for OIDC authentication | +| `OIDC_REDIRECT_URI` | | | Absolute redirect URI for OIDC authentication | +| `OIDC_SERVER_APPLICATION_URL` | | | Absolute URL of the OIDC server application | +| `OIDC_SERVER_METADATA_URL` | | | URL to the OIDC provider metadata endpoint | +| `OIDC_CLAIM_ROLES` | | | OIDC claim containing user roles | +| `OIDC_ROLE_VIEWER` | | | Group value granting the User role (grants non-admins login when `OIDC_CLAIM_ROLES` is set) | +| `OIDC_ROLE_EDITOR` | | | Group value granting the User role (same effect as viewer) | +| `OIDC_ROLE_ADMIN` | | | Role value mapping to admin permissions | +| `OIDC_TLS_CACERTFILE` | | | Path to file containing trusted CA certificates | +| `OIDC_USERNAME_ATTRIBUTE` | `preferred_username` | | Attribute on OIDC user info used as the username | +| `OIDC_RP_INITIATED_LOGOUT` | `false` | | Enable RP-initiated logout flow | +| `OIDC_END_SESSION_ENDPOINT` | | | OIDC end-session endpoint override URL | ### Metadata Providers diff --git a/docs/troubleshooting/authentication.md b/docs/troubleshooting/authentication.md index 9987482..9673b62 100644 --- a/docs/troubleshooting/authentication.md +++ b/docs/troubleshooting/authentication.md @@ -75,6 +75,27 @@ You configured `OIDC_CLAIM_ROLES` but it's not being honoured. Roles are re-evaluated on every login with no cache to bust, so log out and back in to test the fix. +### `User has not been granted any roles for this application.` + +A newly created (non-admin) user logs in and is rejected with: + +```json +{ "detail": "User has not been granted any roles for this application." } +``` + +You set `OIDC_CLAIM_ROLES`, which makes RomM require every user to match at least one mapped role group. Admins work because they match `OIDC_ROLE_ADMIN`, but users in no mapped group are turned away. + +Fix: map your non-admin group to the **User** role with `OIDC_ROLE_VIEWER` (or `OIDC_ROLE_EDITOR`), pointing at a group all your regular users belong to: + +```yaml +environment: + - OIDC_CLAIM_ROLES=groups + - OIDC_ROLE_ADMIN=romm-admin,platform-admins + - OIDC_ROLE_VIEWER=platform-users # grants login to non-admins +``` + +`OIDC_ROLE_VIEWER`/`OIDC_ROLE_EDITOR` all resolve to **User** (not distinct roles anymore), but they're still what grants access when role claims are enabled. See [Role mapping](../administration/oidc/index.md#role-mapping). + ### "Email is missing from token" (Zitadel-specific) On Zitadel, open the application → **Token Settings** → tick **User Info inside ID Token** → Save.