From 2e478c767c69feb3fee3b50bc824d61b094908e5 Mon Sep 17 00:00:00 2001 From: HydrelioxGithub Date: Mon, 11 May 2026 20:57:55 +0200 Subject: [PATCH 1/4] Add VoidAuth OIDC documentation --- docs/administration/oidc/voidauth.md | 56 ++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/administration/oidc/voidauth.md diff --git a/docs/administration/oidc/voidauth.md b/docs/administration/oidc/voidauth.md new file mode 100644 index 00000000..14af9fc4 --- /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 will use the APP_URL provided in the compose.yml exemple for reference in this documentation : https://auth.example.com +Your RomM instance will be referenced as https://demo.romm.app . + +## 2. Create a new app + +Login as an admin in VoidAuth web interface. Create a new OIDC Apps (e.g. `RomM`). + +- **Name**: `RomM` +- **Home Page URL**: `https://romm.example.com` +- **Logo URL**: `https://github.com/HydrelioxGitHub/romm-docs/blob/main/.github/resources/isotipo.png?raw=true` +- **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** : This options could be checked or not as you wish. +- **Client ID**: Generate an ID using the button +- **Auth Method**: `Client Secred 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 on the `Create` button to valid 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). From b47548033516409d0d535eb64013d98df3601da6 Mon Sep 17 00:00:00 2001 From: Hydreliox Date: Tue, 12 May 2026 17:46:59 +0200 Subject: [PATCH 2/4] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/administration/oidc/voidauth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/administration/oidc/voidauth.md b/docs/administration/oidc/voidauth.md index 14af9fc4..f7d157a5 100644 --- a/docs/administration/oidc/voidauth.md +++ b/docs/administration/oidc/voidauth.md @@ -17,7 +17,7 @@ Your RomM instance will be referenced as https://demo.romm.app . Login as an admin in VoidAuth web interface. Create a new OIDC Apps (e.g. `RomM`). - **Name**: `RomM` -- **Home Page URL**: `https://romm.example.com` +- **Home Page URL**: `https://demo.romm.app` - **Logo URL**: `https://github.com/HydrelioxGitHub/romm-docs/blob/main/.github/resources/isotipo.png?raw=true` - **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** : This options could be checked or not as you wish. From f360294c94fc7773098dcb9b58b0a22301b840a7 Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Fri, 5 Jun 2026 15:34:41 -0400 Subject: [PATCH 3/4] changes from bot review --- docs/Navigation.md | 1 + docs/administration/index.md | 2 +- docs/administration/oidc/index.md | 5 +++-- docs/administration/oidc/voidauth.md | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/Navigation.md b/docs/Navigation.md index 04b79b61..3c8127e6 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 4542cc95..7372d92c 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 e52095c0..ef4f017f 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 index f7d157a5..e7d2e6d7 100644 --- a/docs/administration/oidc/voidauth.md +++ b/docs/administration/oidc/voidauth.md @@ -14,7 +14,7 @@ Your RomM instance will be referenced as https://demo.romm.app . ## 2. Create a new app -Login as an admin in VoidAuth web interface. Create a new OIDC Apps (e.g. `RomM`). +Login as an admin in VoidAuth web interface. Create a new OIDC Apps (e.g. `RomM`). - **Name**: `RomM` - **Home Page URL**: `https://demo.romm.app` From 103a006fd3ad8375824262e4832d9b05e13eaf38 Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi <3247106+gantoine@users.noreply.github.com> Date: Fri, 5 Jun 2026 16:44:14 -0400 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/administration/oidc/index.md | 2 +- docs/administration/oidc/voidauth.md | 20 ++++++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/administration/oidc/index.md b/docs/administration/oidc/index.md index ef4f017f..24d76703 100644 --- a/docs/administration/oidc/index.md +++ b/docs/administration/oidc/index.md @@ -39,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 index e7d2e6d7..7f72a38c 100644 --- a/docs/administration/oidc/voidauth.md +++ b/docs/administration/oidc/voidauth.md @@ -9,34 +9,34 @@ description: Wire up SSO to VoidAuth ## 1. Prerequisites -VoidAuth installed and running via their [self-hosted deployment docs](https://voidauth.app/#/?id=quick-start). We will use the APP_URL provided in the compose.yml exemple for reference in this documentation : https://auth.example.com -Your RomM instance will be referenced as https://demo.romm.app . +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 -Login as an admin in VoidAuth web interface. Create a new OIDC Apps (e.g. `RomM`). +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://github.com/HydrelioxGitHub/romm-docs/blob/main/.github/resources/isotipo.png?raw=true` +- **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** : This options could be checked or not as you wish. -- **Client ID**: Generate an ID using the button -- **Auth Method**: `Client Secred Basic` -- **Client Secret**: Generate a secret using the button +- **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 on the `Create` button to valid your app. +Don't forget to click the `Create` button to validate your app. ## 3. Configure ```yaml environment: - OIDC_ENABLED=true - - OIDC_PROVIDER=VoidAuth + - OIDC_PROVIDER=voidauth - OIDC_CLIENT_ID= - OIDC_CLIENT_SECRET= - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid