diff --git a/docs/administration/oidc/authelia.md b/docs/administration/oidc/authelia.md index 50c6008..e3c857d 100644 --- a/docs/administration/oidc/authelia.md +++ b/docs/administration/oidc/authelia.md @@ -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: "" # see note below + client_name: "RomM" + client_secret: "$pbkdf2-sha512$" # 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= + - OIDC_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. + +![Set email](../../resources/authelia/1-user-profile.png) + +## 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. + +![Login with OIDC](../../resources/authelia/2-romm-login.png) + +If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md). diff --git a/docs/administration/oidc/authentik.md b/docs/administration/oidc/authentik.md index 4cbf0c3..aadcd22 100644 --- a/docs/administration/oidc/authentik.md +++ b/docs/administration/oidc/authentik.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**. + +![Authentik user dashboard](../../resources/authentik/1-user-dashboard.png) + +## 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, + } + ``` + +![Property Mapping](../../resources/authentik/propperty-mapping.png) + +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**. + +![Create a new provider](../../resources/authentik/2-create-provider.png) + +Choose **OAuth2/OpenID Provider**. + +![Select OAuth2 provider](../../resources/authentik/3-new-provider.png) + +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. + +![Provider settings](../../resources/authentik/4-provider-secrets.png) + +Click **Create**. + +## 4. Register the application + +**Admin → Applications → Create**. + +![Applications](../../resources/authentik/5-applications.png) + +- **Name**: `RomM` +- **Slug**: `romm` +- **Provider**: the `RomM OIDC Provider` you just made. + +![New application](../../resources/authentik/6-new-application.png) + +Click **Create**. + +## 5. Configure RomM + +```yaml +environment: + - OIDC_ENABLED=true + - OIDC_PROVIDER=authentik + - OIDC_CLIENT_ID= + - OIDC_CLIENT_SECRET= + - 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/`) — 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. + +![Set email](../../resources/authentik/7-user-profile.png) + +## 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. + +![Login with OIDC](../../resources/authentik/8-romm-login.png) + +If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md). diff --git a/docs/administration/oidc/keycloak.md b/docs/administration/oidc/keycloak.md index 1e255e1..1f0f1cc 100644 --- a/docs/administration/oidc/keycloak.md +++ b/docs/administration/oidc/keycloak.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= + - OIDC_REDIRECT_URI=https://romm.example.com/api/oauth/openid + - OIDC_SERVER_APPLICATION_URL=https://keycloak.example.com/realms/ + - ROMM_BASE_URL=https://romm.example.com +``` + +`OIDC_SERVER_APPLICATION_URL` must include the realm — `.../realms/` — 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. diff --git a/docs/administration/oidc/pocketid.md b/docs/administration/oidc/pocketid.md index b3ffacb..d0d7e42 100644 --- a/docs/administration/oidc/pocketid.md +++ b/docs/administration/oidc/pocketid.md @@ -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= + - OIDC_CLIENT_SECRET= + - 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. + +![Set email](../../resources/authelia/1-user-profile.png) + +## 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. + +![Login with OIDC](../../resources/pocketid/2-romm-login.png) + +If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md). diff --git a/docs/administration/oidc/zitadel.md b/docs/administration/oidc/zitadel.md index 3d69080..6b124ad 100644 --- a/docs/administration/oidc/zitadel.md +++ b/docs/administration/oidc/zitadel.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= + - OIDC_CLIENT_SECRET= + - 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 `/.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).