mirror of
https://github.com/rommapp/docs.git
synced 2026-04-20 01:04:29 +08:00
docs: port Wave 1 OIDC provider guides (all 5)
All five OIDC provider walkthroughs now live under administration/oidc/, consistent in structure: prereqs → provider-side config → RomM env vars → email matching → test → optional role mapping. - administration/oidc/authelia.md: claims policy + client config - administration/oidc/authentik.md: 2025.10 email_verified property mapping, provider + application setup - administration/oidc/keycloak.md: previously orphaned; now linked from Navigation.md and the OIDC hub. Uses DISABLE_USERPASS_LOGIN (replacing the old doc's PASSWORD_AUTH_ENABLED which doesn't exist in the env template) - administration/oidc/pocketid.md: passkey-only flow - administration/oidc/zitadel.md: project/app setup, "User Info inside ID Token" fix for the "Email is missing from token" error All cross-link to the hub's role-mapping section and to troubleshooting/authentication.md. Builds clean with --strict.
This commit is contained in:
Claude
parent
222b751754
commit
be2b1a1127
@ -1,10 +1,99 @@
|
||||
---
|
||||
status: placeholder
|
||||
wave: 1
|
||||
title: OIDC with Authelia
|
||||
description: Wire RomM's SSO to Authelia — claims policy, client registration, RomM env vars.
|
||||
---
|
||||
|
||||
# OIDC with Authelia
|
||||
|
||||
!!! warning "Placeholder — RomM 5.0 docs overhaul"
|
||||
This page is part of the RomM 5.0 documentation overhaul (Wave 1) and
|
||||
has not been written yet. See the overhaul plan for status and ownership.
|
||||
[Authelia](https://www.authelia.com/) is a lightweight open-source authentication and authorisation server with two-factor auth and SSO. Good fit for homelabs that already proxy through a reverse proxy.
|
||||
|
||||
Before starting, read the [OIDC Setup overview](index.md) — it covers the RomM-side settings common to every provider.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
Authelia installed and running, with its OIDC provider enabled. Upstream guides:
|
||||
|
||||
- [Authelia getting started](https://www.authelia.com/integration/prologue/get-started/)
|
||||
- [OIDC provider configuration](https://www.authelia.com/configuration/identity-providers/openid-connect/provider/)
|
||||
|
||||
## 2. Add a claims policy
|
||||
|
||||
In Authelia's `configuration.yml` under `identity_providers.oidc.claims_policies`, add a policy that emits the claims RomM needs (name it whatever you like):
|
||||
|
||||
```yaml
|
||||
identity_providers:
|
||||
oidc:
|
||||
claims_policies:
|
||||
with_email:
|
||||
id_token:
|
||||
- email
|
||||
- email_verified
|
||||
- groups
|
||||
- alt_emails
|
||||
- preferred_username
|
||||
- name
|
||||
```
|
||||
|
||||
Background on why this is needed: [Authelia claims parameter restoration](https://www.authelia.com/integration/openid-connect/openid-connect-1.0-claims/#restore-functionality-prior-to-claims-parameter).
|
||||
|
||||
## 3. Register the RomM client
|
||||
|
||||
Under `identity_providers.oidc.clients`, add:
|
||||
|
||||
```yaml
|
||||
identity_providers:
|
||||
oidc:
|
||||
clients:
|
||||
- client_id: "<random>" # see note below
|
||||
client_name: "RomM"
|
||||
client_secret: "$pbkdf2-sha512$<random>" # see note below
|
||||
public: false
|
||||
authorization_policy: "two_factor" # or one_factor
|
||||
grant_types:
|
||||
- authorization_code
|
||||
redirect_uris:
|
||||
- "https://romm.example.com/api/oauth/openid"
|
||||
claims_policy: "with_email" # must match the policy name above
|
||||
scopes:
|
||||
- openid
|
||||
- email
|
||||
- profile
|
||||
- groups
|
||||
userinfo_signed_response_alg: "none"
|
||||
token_endpoint_auth_method: "client_secret_basic"
|
||||
```
|
||||
|
||||
Generating IDs and secrets: see [Authelia's FAQ](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret). Full client schema: [Authelia clients reference](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/).
|
||||
|
||||
## 4. Configure RomM
|
||||
|
||||
In the `romm` service environment:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- OIDC_ENABLED=true
|
||||
- OIDC_PROVIDER=authelia
|
||||
- OIDC_CLIENT_ID=<the client_id you picked>
|
||||
- OIDC_CLIENT_SECRET=<the plaintext client secret>
|
||||
- OIDC_REDIRECT_URI=https://romm.example.com/api/oauth/openid
|
||||
- OIDC_SERVER_APPLICATION_URL=https://auth.example.com
|
||||
- ROMM_BASE_URL=https://romm.example.com
|
||||
```
|
||||
|
||||
`OIDC_REDIRECT_URI` must match what you put in `redirect_uris` exactly — scheme, host, path, no trailing slash.
|
||||
|
||||
For role mapping from Authelia groups, see [OIDC Setup → Role mapping](index.md#role-mapping-50).
|
||||
|
||||
## 5. Set your email on RomM
|
||||
|
||||
In RomM → **Profile** → set your email to exactly the same address Authelia has for you. RomM matches OIDC users to existing accounts by email.
|
||||
|
||||
|
||||
|
||||
## 6. Test
|
||||
|
||||
Restart RomM and open `/login`. There should be a **Login with OIDC** button alongside the username/password form. Click it → you're bounced to Authelia → authenticate → you're bounced back and signed into RomM.
|
||||
|
||||
|
||||
|
||||
If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).
|
||||
|
||||
@ -1,10 +1,107 @@
|
||||
---
|
||||
status: placeholder
|
||||
wave: 1
|
||||
title: OIDC with Authentik
|
||||
description: Wire RomM's SSO to Authentik — property mapping for email_verified, provider, application, RomM env vars.
|
||||
---
|
||||
|
||||
# OIDC with Authentik
|
||||
|
||||
!!! warning "Placeholder — RomM 5.0 docs overhaul"
|
||||
This page is part of the RomM 5.0 documentation overhaul (Wave 1) and
|
||||
has not been written yet. See the overhaul plan for status and ownership.
|
||||
[Authentik](https://goauthentik.io/) is a full-featured open-source IdP with MFA, flows, and a sizeable audit/admin surface. Good fit for users who want more than Authelia offers.
|
||||
|
||||
Before starting, read the [OIDC Setup overview](index.md) — it covers the RomM-side settings common to every provider.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
Authentik installed and running. Upstream: [Docker Compose install guide](https://docs.goauthentik.io/docs/install-config/install/docker-compose).
|
||||
|
||||
Log in as admin and open **Admin Interface**.
|
||||
|
||||
|
||||
|
||||
## 2. Create a property mapping (Authentik 2025.10+)
|
||||
|
||||
!!! important "Authentik 2025.10 breaking change"
|
||||
In version 2025.10, Authentik changed the default of `email_verified` from `true` to `false`. RomM requires a verified email, so without this property mapping, authentication silently fails.
|
||||
|
||||
In **Customization → Property Mappings → Create → Scope Mapping**:
|
||||
|
||||
- **Name**: `RomM Email Verification`
|
||||
- **Scope name**: `email`
|
||||
- **Expression**:
|
||||
|
||||
```py
|
||||
return {
|
||||
"email": user.email,
|
||||
"email_verified": True,
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
Click **Create**. Upstream reference: [Authentik scope mappings](https://version-2025-10.goauthentik.io/add-secure-apps/providers/property-mappings/#scope-mappings-with-oauth2).
|
||||
|
||||
## 3. Create a provider
|
||||
|
||||
**Admin → Providers → Create**.
|
||||
|
||||
|
||||
|
||||
Choose **OAuth2/OpenID Provider**.
|
||||
|
||||
|
||||
|
||||
Configure:
|
||||
|
||||
- **Name**: `RomM OIDC Provider`
|
||||
- **Authorization flow**: implicit consent
|
||||
- **Redirect URIs**: `https://romm.example.com/api/oauth/openid`
|
||||
|
||||
Copy the generated **Client ID** and **Client Secret** — you'll use them as `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` on the RomM side.
|
||||
|
||||
|
||||
|
||||
Click **Create**.
|
||||
|
||||
## 4. Register the application
|
||||
|
||||
**Admin → Applications → Create**.
|
||||
|
||||
|
||||
|
||||
- **Name**: `RomM`
|
||||
- **Slug**: `romm`
|
||||
- **Provider**: the `RomM OIDC Provider` you just made.
|
||||
|
||||
|
||||
|
||||
Click **Create**.
|
||||
|
||||
## 5. Configure RomM
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- OIDC_ENABLED=true
|
||||
- OIDC_PROVIDER=authentik
|
||||
- OIDC_CLIENT_ID=<from Authentik>
|
||||
- OIDC_CLIENT_SECRET=<from Authentik>
|
||||
- OIDC_REDIRECT_URI=https://romm.example.com/api/oauth/openid
|
||||
- OIDC_SERVER_APPLICATION_URL=https://auth.example.com/application/o/romm
|
||||
- ROMM_BASE_URL=https://romm.example.com
|
||||
```
|
||||
|
||||
Note `OIDC_SERVER_APPLICATION_URL` points at the per-application URL (`/application/o/<slug>`) — not the Authentik root.
|
||||
|
||||
For role mapping from Authentik groups, see [OIDC Setup → Role mapping](index.md#role-mapping-50).
|
||||
|
||||
## 6. Set your email on RomM
|
||||
|
||||
In RomM → **Profile** → set your email to exactly the same address Authentik has for you.
|
||||
|
||||
|
||||
|
||||
## 7. Test
|
||||
|
||||
Restart RomM and open `/login`. Click the **Login with OIDC** button — you're redirected to Authentik, authenticate, and come back signed into RomM.
|
||||
|
||||
|
||||
|
||||
If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).
|
||||
|
||||
@ -1,10 +1,89 @@
|
||||
---
|
||||
status: placeholder
|
||||
wave: 1
|
||||
title: OIDC with Keycloak
|
||||
description: Wire RomM's SSO to Keycloak — realm, client, RomM env vars, optional role mapping.
|
||||
---
|
||||
|
||||
# OIDC with Keycloak
|
||||
|
||||
!!! warning "Placeholder — RomM 5.0 docs overhaul"
|
||||
This page is part of the RomM 5.0 documentation overhaul (Wave 1) and
|
||||
has not been written yet. See the overhaul plan for status and ownership.
|
||||
[Keycloak](https://www.keycloak.org/) is the heavyweight open-source IAM standard. Feature-complete, well-documented, widely deployed — the default choice when your SSO needs are serious.
|
||||
|
||||
Before starting, read the [OIDC Setup overview](index.md) — it covers the RomM-side settings common to every provider.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
Keycloak installed and running. Upstream: [Keycloak getting started](https://www.keycloak.org/getting-started).
|
||||
|
||||
Log into the **Admin Console** and either create a new realm for RomM or reuse an existing one.
|
||||
|
||||
## 2. Add a client
|
||||
|
||||
In the Admin Console, select your realm → **Clients** → **Create client**.
|
||||
|
||||
1. **Client type**: `OpenID Connect`.
|
||||
2. **Client ID**: `romm` (or anything unique). Click **Next**.
|
||||
3. On the capability page:
|
||||
- Enable **Client authentication**.
|
||||
- Leave only **Standard flow** enabled.
|
||||
- Click **Next**.
|
||||
4. Set URLs:
|
||||
- **Root URL**: `https://romm.example.com`
|
||||
- **Valid Redirect URIs**: `https://romm.example.com/api/oauth/openid`
|
||||
- **Web origins**: `https://romm.example.com`
|
||||
5. Save. Go to **Credentials** tab and copy the **Client Secret**.
|
||||
|
||||
## 3. Configure RomM
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- OIDC_ENABLED=true
|
||||
- OIDC_PROVIDER=keycloak
|
||||
- OIDC_CLIENT_ID=romm
|
||||
- OIDC_CLIENT_SECRET=<from Keycloak Credentials tab>
|
||||
- OIDC_REDIRECT_URI=https://romm.example.com/api/oauth/openid
|
||||
- OIDC_SERVER_APPLICATION_URL=https://keycloak.example.com/realms/<realm-name>
|
||||
- ROMM_BASE_URL=https://romm.example.com
|
||||
```
|
||||
|
||||
`OIDC_SERVER_APPLICATION_URL` must include the realm — `.../realms/<realm-name>` — not just the Keycloak root.
|
||||
|
||||
## 4. Set email on RomM + verify in Keycloak
|
||||
|
||||
In RomM → **Profile** → set your email to the same address Keycloak has for you.
|
||||
|
||||
On the Keycloak side, **Admin Console → Users**: mark each RomM user's email as **verified**. Users with unverified emails will be rejected on login.
|
||||
|
||||
## 5. Test
|
||||
|
||||
Restart RomM and open `/login`. Click **Login with Keycloak** — you're redirected to Keycloak, authenticate, and bounce back signed into RomM.
|
||||
|
||||
If a user already exists in RomM with a matching email, they're signed into that account. Otherwise RomM creates a new account with Viewer permissions.
|
||||
|
||||
If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).
|
||||
|
||||
## 6. (Optional) Disable local password logins
|
||||
|
||||
Force users through Keycloak:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- DISABLE_USERPASS_LOGIN=true
|
||||
```
|
||||
|
||||
!!! warning
|
||||
Before flipping this, confirm at least one Admin account can sign in via OIDC. Otherwise a broken OIDC flow locks you out.
|
||||
|
||||
## 7. (Optional) Role mapping
|
||||
|
||||
By default, new OIDC users come in as Viewers. To map Keycloak roles/groups to RomM roles:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- OIDC_CLAIM_ROLES=groups # or realm_access.roles, depending on your token
|
||||
- OIDC_ROLE_VIEWER=romm-viewer
|
||||
- OIDC_ROLE_EDITOR=romm-editor
|
||||
- OIDC_ROLE_ADMIN=romm-admin
|
||||
```
|
||||
|
||||
Configure Keycloak's client to include the role/group claim in the ID token (usually via a **Group Membership** or **Realm Role** client scope mapper). Values in the claim are compared against the `OIDC_ROLE_*` env vars on every login, so demoting in Keycloak takes effect on the user's next sign-in.
|
||||
|
||||
See [OIDC Setup → Role mapping](index.md#role-mapping-50) for the generic version.
|
||||
|
||||
@ -1,10 +1,54 @@
|
||||
---
|
||||
status: placeholder
|
||||
wave: 1
|
||||
title: OIDC with PocketID
|
||||
description: Wire RomM's SSO to PocketID for passkey-only login.
|
||||
---
|
||||
|
||||
# OIDC with PocketID
|
||||
|
||||
!!! warning "Placeholder — RomM 5.0 docs overhaul"
|
||||
This page is part of the RomM 5.0 documentation overhaul (Wave 1) and
|
||||
has not been written yet. See the overhaul plan for status and ownership.
|
||||
[PocketID](https://github.com/stonith404/pocket-id) is a minimalist OIDC provider that **only** supports passkey authentication — no passwords. Good fit when you want passwordless login end-to-end without the complexity of Keycloak or Authentik.
|
||||
|
||||
Before starting, read the [OIDC Setup overview](index.md) — it covers the RomM-side settings common to every provider.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
PocketID installed, running, and your admin passkey already registered. Upstream setup: [PocketID setup guide](https://github.com/stonith404/pocket-id#setup).
|
||||
|
||||
## 2. Add the client
|
||||
|
||||
In PocketID admin:
|
||||
|
||||
1. **Application Configuration** — make sure **Emails Verified** is ticked. RomM requires verified emails.
|
||||
2. Go to **OIDC Client** → **Add OIDC Client**.
|
||||
3. Fill in:
|
||||
- **Name**: `RomM`
|
||||
- **Callback URLs**: `https://romm.example.com/api/oauth/openid`
|
||||
4. **Save**. Stay on this page — the client secret only displays **once**. Copy both the Client ID and Client Secret now.
|
||||
|
||||
## 3. Configure RomM
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- OIDC_ENABLED=true
|
||||
- OIDC_PROVIDER=pocket-id
|
||||
- OIDC_CLIENT_ID=<from PocketID>
|
||||
- OIDC_CLIENT_SECRET=<from PocketID>
|
||||
- OIDC_REDIRECT_URI=https://romm.example.com/api/oauth/openid
|
||||
- OIDC_SERVER_APPLICATION_URL=https://id.example.com
|
||||
- ROMM_BASE_URL=https://romm.example.com
|
||||
```
|
||||
|
||||
`OIDC_SERVER_APPLICATION_URL` is the root URL of your PocketID instance.
|
||||
|
||||
## 4. Set your email on RomM
|
||||
|
||||
RomM → **Profile** → set your email to exactly the same address PocketID has for you.
|
||||
|
||||
|
||||
|
||||
## 5. Test
|
||||
|
||||
Restart RomM and open `/login`. Click **Login with OIDC** — you're redirected to PocketID, tap your passkey, and bounce back signed into RomM.
|
||||
|
||||
|
||||
|
||||
If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).
|
||||
|
||||
@ -1,10 +1,79 @@
|
||||
---
|
||||
status: placeholder
|
||||
wave: 1
|
||||
title: OIDC with Zitadel
|
||||
description: Wire RomM's SSO to Zitadel — project, application, user info inside ID token, RomM env vars.
|
||||
---
|
||||
|
||||
# OIDC with Zitadel
|
||||
|
||||
!!! warning "Placeholder — RomM 5.0 docs overhaul"
|
||||
This page is part of the RomM 5.0 documentation overhaul (Wave 1) and
|
||||
has not been written yet. See the overhaul plan for status and ownership.
|
||||
[Zitadel](https://zitadel.com/) is an enterprise-grade open-source IAM platform supporting OAuth2, OIDC, SAML, and passwordless. Good fit when you want an enterprise-ish IdP without running Keycloak.
|
||||
|
||||
Before starting, read the [OIDC Setup overview](index.md) — it covers the RomM-side settings common to every provider.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
Zitadel installed and running. Upstream: [self-hosted deployment docs](https://zitadel.com/docs/self-hosting/deploy/overview). Change the default organization password before you go further.
|
||||
|
||||
## 2. Create a project
|
||||
|
||||
Create a new project (e.g. `RomM`). This holds the client and its auth settings.
|
||||
|
||||
On the project's **General** tab, the toggles mean:
|
||||
|
||||
- **Assert Roles on Authentication** — not useful today; RomM 5.0 reads roles via `OIDC_CLAIM_ROLES` regardless. Leave off unless you're setting up role mapping.
|
||||
- **Check authorization on Authentication** — recommended. If off, anyone who can register in Zitadel can sign into RomM (as Viewer). Turn this on if Zitadel registration is open.
|
||||
- **Check for Project on Authentication** — only matters if you're separating users by Zitadel organization. Skip for a single RomM instance.
|
||||
|
||||
### 2.5 (Optional) Grant users to the project
|
||||
|
||||
If you enabled **Check authorization on Authentication**:
|
||||
|
||||
1. **Authorization** tab → **New**.
|
||||
2. Select user(s) → **Continue**.
|
||||
3. "No role has been created yet" is fine — just **Save**. The user appears in the authorization list with no roles.
|
||||
|
||||
## 3. Create the application
|
||||
|
||||
On the project's **General** tab, under **Applications**, click **New**. Tick **I'm a pro. Skip this wizard** for the fast path.
|
||||
|
||||
- **Name**: `RomM`
|
||||
- **Application Type**: `Web`
|
||||
- **Grant Types**: `Authorization Code`
|
||||
- **Response Types**: `Code`
|
||||
- **Authentication Method**: `Basic`
|
||||
- **Redirect URIs**: `https://romm.example.com/api/oauth/openid`
|
||||
- **Post Logout URIs**: `https://romm.example.com/`
|
||||
|
||||
Click **Create**. The **client secret is shown once** — copy it now.
|
||||
|
||||
## 4. Enable claims in the ID Token
|
||||
|
||||
Without this, RomM throws "Email is missing from token" on login.
|
||||
|
||||
Open the application's **Token Settings** tab → tick **User Info inside ID Token** → **Save**.
|
||||
|
||||
## 5. Configure RomM
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- OIDC_ENABLED=true
|
||||
- OIDC_PROVIDER=zitadel
|
||||
- OIDC_CLIENT_ID=<from Zitadel>
|
||||
- OIDC_CLIENT_SECRET=<from Zitadel>
|
||||
- OIDC_REDIRECT_URI=https://romm.example.com/api/oauth/openid
|
||||
- OIDC_SERVER_APPLICATION_URL=https://zitadel.example.com
|
||||
- ROMM_BASE_URL=https://romm.example.com
|
||||
```
|
||||
|
||||
Zitadel's OIDC discovery URL is at `<OIDC_SERVER_APPLICATION_URL>/.well-known/openid-configuration` — handy for debugging.
|
||||
|
||||
For role mapping from Zitadel, see [OIDC Setup → Role mapping](index.md#role-mapping-50).
|
||||
|
||||
## 6. Set email on RomM + Zitadel
|
||||
|
||||
In RomM → **Profile** → set your email to exactly the same address your Zitadel user has.
|
||||
|
||||
## 7. Test
|
||||
|
||||
Restart RomM and open `/login`. Click **Login with Zitadel** — you're redirected, authenticate, and bounce back signed into RomM.
|
||||
|
||||
If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user