diff --git a/docs/Navigation.md b/docs/Navigation.md index 04b79b6..3c8127e 100644 --- a/docs/Navigation.md +++ b/docs/Navigation.md @@ -34,6 +34,7 @@ search: - [Keycloak](administration/oidc/keycloak.md) - [PocketID](administration/oidc/pocketid.md) - [Zitadel](administration/oidc/zitadel.md) + - [VoidAuth](administration/oidc/voidauth.md) - [Scanning & Watcher](administration/scanning-and-watcher.md) - [Scheduled Tasks](administration/scheduled-tasks.md) - [Server Stats](administration/server-stats.md) diff --git a/docs/administration/index.md b/docs/administration/index.md index 4542cc9..7372d92 100644 --- a/docs/administration/index.md +++ b/docs/administration/index.md @@ -16,7 +16,7 @@ The end-user equivalent (how to actually play the games, build collections, uplo - **[Users & Roles](users-and-roles.md)**: roles, the scope model, how permissions add up - **[Invitations & Registration](invitations-and-registration.md)**: invite links, public signup, first-user setup - **[Authentication](authentication.md)**: session config, password reset, Client API Tokens for devices -- **[OIDC Setup](oidc/index.md)**: Authelia, Authentik, Keycloak, PocketID, Zitadel, SSO + role mapping +- **[OIDC Setup](oidc/index.md)**: Authelia, Authentik, Keycloak, PocketID, Zitadel, VoidAuth, SSO + role mapping ### Content & library diff --git a/docs/administration/oidc/index.md b/docs/administration/oidc/index.md index e52095c..24d7670 100644 --- a/docs/administration/oidc/index.md +++ b/docs/administration/oidc/index.md @@ -5,7 +5,7 @@ description: Wire up to an OpenID Connect provider for SSO and centralised user # OIDC Setup -OpenID Connect (OIDC) lets users sign in through an external identity provider: Authelia, Authentik, Keycloak, PocketID, Zitadel, Okta, Auth0, or anything standards-compliant. Single sign-on across your homelab, no app-specific password to manage, centralised MFA, and map OIDC groups/claims to roles. +OpenID Connect (OIDC) lets users sign in through an external identity provider: Authelia, Authentik, Keycloak, PocketID, Zitadel, Okta, Auth0, VoidAuth, or anything standards-compliant. Single sign-on across your homelab, no app-specific password to manage, centralised MFA, and map OIDC groups/claims to roles. !!! note "OIDC is optional" @@ -28,6 +28,7 @@ Pick your provider and follow the step-by-step instructions. They all end with t - [Keycloak](keycloak.md) - [PocketID](pocketid.md) - [Zitadel](zitadel.md) +- [VoidAuth](voidauth.md) Not listed? Most standards-compliant OIDC providers work: Okta, Auth0, Google Workspace, Microsoft Entra, etc. Use one of the above as a template and consult your provider's docs for the registration side. @@ -38,7 +39,7 @@ Whichever provider you pick, set these in the `romm` service's environment: ```yaml environment: - OIDC_ENABLED=true - - OIDC_PROVIDER= + - OIDC_PROVIDER= - OIDC_CLIENT_ID= - OIDC_CLIENT_SECRET= - OIDC_SERVER_APPLICATION_URL=https://auth.example.com diff --git a/docs/administration/oidc/voidauth.md b/docs/administration/oidc/voidauth.md new file mode 100644 index 0000000..7f72a38 --- /dev/null +++ b/docs/administration/oidc/voidauth.md @@ -0,0 +1,56 @@ +--- +title: OIDC with VoidAuth +description: Wire up SSO to VoidAuth +--- + +# OIDC with VoidAuth + +[VoidAuth](https://voidauth.app/) is an open-source SSO authentication and user management provider that stands guard in front of your self-hosted application. Before starting, read the [OIDC Setup overview](index.md), as it covers the RomM-side settings common to every provider. + +## 1. Prerequisites + +VoidAuth installed and running via their [self-hosted deployment docs](https://voidauth.app/#/?id=quick-start). We'll use the `APP_URL` from the example `compose.yml` in those docs as `https://auth.example.com`. +Your RomM instance will be referenced as `https://demo.romm.app`. + +## 2. Create a new app + +Log in as an admin in the VoidAuth web interface. Create a new OIDC app (e.g. `RomM`). + +- **Name**: `RomM` +- **Home Page URL**: `https://demo.romm.app` +- **Logo URL**: `https://docs.romm.app/resources/romm/isotipo.png` +- **Group**: You could add a group that the user must belong to get access to your RomM instance. If left empty, any user created in your VoidAuth instance will be allowed. +- **Skip Consent** and **MFA Required**: These options can be enabled or left disabled as you prefer. +- **Client ID**: Generate an ID using the button. +- **Auth Method**: `Client Secret Basic` +- **Client Secret**: Generate a secret using the button. +- **Redirect URLs**: add `https://demo.romm.app/api/oauth/openid` +- **Response Types**: check `code` +- **Grant Types**: check `authorization_code` and `refresh_token` +- **Post Logout URL**: `https://demo.romm.app/` + +Don't forget to click the `Create` button to validate your app. + +## 3. Configure + +```yaml +environment: + - OIDC_ENABLED=true + - OIDC_PROVIDER=voidauth + - OIDC_CLIENT_ID= + - OIDC_CLIENT_SECRET= + - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid + - OIDC_SERVER_APPLICATION_URL=https://auth.example.com + - OIDC_SERVER_METADATA_URL=https://auth.example.com/oidc/.well-known/openid-configuration + - ROMM_BASE_URL=https://demo.romm.app +``` + +VoidAuth's OIDC discovery URL can be found at the top of your OIDC App page, by clicking on OIDC Endpoints. + +For role mapping from VoidAuth, see [OIDC Setup → Role mapping](index.md#role-mapping). + +## 4. Test + +Restart, navigate to `/login` and click the **Login with VoidAuth** button. You're redirected to VoidAuth → authenticate → bounced back and signed in! + +If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).