Skip to content

docs: clarify OIDC role mapping requires a mapped group #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gantoine merged 3 commits into from
Jul 18, 2026
Merged

docs: clarify OIDC role mapping requires a mapped group #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
58b5397
docs: clarify OIDC role mapping requires a mapped group
gantoine Jul 18, 2026
784fbf0
run fmt
gantoine Jul 18, 2026
638ab5c
docs: silence false-positive MD046 on OIDC admonition code block
gantoine Jul 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 23 additions & 3 deletions docs/administration/oidc/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- markdownlint-disable MD046 -->
<!-- prettier-ignore -->
!!! 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.

<!-- markdownlint-enable MD046 -->

## Autologin

Expand Down
38 changes: 19 additions & 19 deletions docs/resources/snippets/env-vars.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
21 changes: 21 additions & 0 deletions docs/troubleshooting/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading