Merge pull request #60 from Ricardo-Osorio/oidc-with-keycloak

Add page to help setup OIDC with keycloak

Author: gantoine

docs/Getting-Started/OIDC-Setup.md

@@ -2,9 +2,13 @@
 
 OpenID Connect (OIDC) allows you to authenticate to RomM using external identity providers, enabling Single Sign-On (SSO) and centralized user management. This setup eliminates the need to manage separate credentials for RomM.
 
-## What is OIDC?
+## What is OAuth2?
 
-OIDC is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user's identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
+OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user’s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
+
+## What is OpenID Connect (OIDC)?
+
+OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user’s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
 
 ## How It Works
 
@@ -33,6 +37,10 @@ A simple OIDC provider that exclusively supports passkey authentication - no pas
 
 An enterprise-grade, open-source identity and access management platform supporting OAuth2, OIDC, SAML, and passwordless authentication.
 
+### [Keycloak](../OIDC-Guides/OIDC-Setup-With-Keycloak.md)
+
+A popular open-source OIDC provider with extensive features for identity and access management.
+
 ## General Setup Requirements
 
 Regardless of which provider you choose, you'll need to configure these environment variables in RomM:

docs/OIDC-Guides/OIDC-Setup-With-Authelia.md

@@ -6,14 +6,6 @@
 
 Authelia is an open-source authentication and authorization server providing two-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion for reverse proxies by allowing, denying, or redirecting requests. Authelia can be deployed alongside your other services to centralize identity management.
 
-### What is OAuth2?
-
-OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user’s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
-
-### What is OpenID Connect (OIDC)?
-
-OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user’s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
-
 ## Setting up a Provider and Application in Authelia
 
 ### Step 1: Install and Configure Authelia

docs/OIDC-Guides/OIDC-Setup-With-Authentik.md

@@ -6,14 +6,6 @@
 
 Authentik is an open-source identity provider (IdP) designed to manage authentication, authorization, and user management across applications. It supports modern authentication protocols and provides tools to simplify integration, including single sign-on (SSO), multi-factor authentication (MFA), and auditing capabilities. Authentik can be deployed alongside your other services to centralize identity management.
 
-### What is OAuth2?
-
-OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user’s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
-
-### What is OpenID Connect (OIDC)?
-
-OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user’s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
-
 ## Setting up a Provider and Application in Authentik
 
 ### Step 1: Install and Configure Authentik
@@ -28,7 +20,7 @@ Before setting up a provider and app, ensure that Authentik is installed and run
 
 ### Step 2: Create a Property Mapping
 
-In version 2025.10 Authentik changed their default value for the `email_verified` field from true to false.  
+In version 2025.10 Authentik changed their default value for the `email_verified` field from true to false.
 Since RomM requires a verified email address, without this property, the authentication would fail.
 
 1. **Navigate to Property Mappings**
@@ -44,7 +36,7 @@ Since RomM requires a verified email address, without this property, the authent
         "email_verified": True,
     }
     ```
-    - It should look like this  
+    - It should look like this
       ![Propperty Mapping](../resources/authentik/propperty-mapping.png)
 3. **Click Create**.
 

docs/OIDC-Guides/OIDC-Setup-With-Keycloak.md

@@ -0,0 +1,67 @@
+# OIDC Setup With Keycloak
+
+## A quick rundown of the technologies
+
+### What is Keycloak?
+
+Keycloak is an open-source Identity and Access Management solution that provides single sign-on (SSO), OpenID Connect (OIDC), OAuth2, amongst other protocols.
+
+## Setting up a Provider and Application in Keycloak
+
+### Step 1: Install or access Keycloak
+
+Before setting up the OIDC client, ensure that Keycloak is installed and running by following the [setup guide](https://www.keycloak.org/getting-started).
+
+Log into the Admin Console and either create a new realm for RomM or reuse an existing one.
+
+### Step 2: Add a client
+
+1. In the Admin Console select your realm → **Clients** → **Create client**.
+2. Leave `Client type` as `OpenID Connect` and enter a `Client ID` (for example `romm`). Click **Next**.
+3. On the next page:
+   - Enable **Client authentication**.
+   - Leave only the **Standard flow** option enabled.
+   - Click **Next**.
+4. Set the following URLs:
+   - **Root URL**: `http://romm.host.local` (replace with your RomM URL)
+   - **Valid Redirect URIs**: `http://romm.host.local/api/oauth/openid` (replace with your RomM URL)
+   - **Web origins**: `http://romm.host.local` (replace with your RomM URL)
+5. Go to the **Credentials** tab and copy the **Client Secret** — you'll need this for the RomM configuration.
+
+### Step 3: Configure RomM Environment Variables
+
+To enable OIDC authentication in RomM, you need to set the following environment variables:
+
+- `OIDC_ENABLED`: Set to `true` to enable OIDC authentication.
+- `OIDC_PROVIDER`: The lowercase name of the provider (`keycloak`).
+- `OIDC_CLIENT_ID`: The client ID copied from the Keycloak application.
+- `OIDC_CLIENT_SECRET`: The generated output from `Random Password`.
+- `OIDC_REDIRECT_URI`: The redirect URI configured in the Keycloak provider, in the format `http://romm.host.local/api/oauth/openid`.
+- `OIDC_SERVER_APPLICATION_URL`: The base URL for you Keycloak instance including the realm name, e.g. `http://keycloak.host.local/realms/<realm-name>`.
+
+### Step 5: Set your Email in RomM
+
+In RomM, open your user profile and set your email address. This email **has to match** your user email in Keycloak.
+
+Open the Keycloak Admin Console → Users and mark each RomM user's email as verified. Users without verified emails will not be able to log in.
+
+### Step 6: Test the Integration
+
+After configuring the environment variables, restart (or stop and remove) your RomM instance and navigate to the login page. You should see the option "LOGIN WITH KEYCLOAK". Click on it and you'll be redirected to Keycloak for authentication. Once authenticated, you'll be redirected back to RomM.
+
+Note that if the user already exists in RomM, they will be logged in with their existing account and permissions. If it's a new user, an account will be created for them with viewer permissions by default. To change the permissions for new users, see Step 8 below.
+
+### Step 7: (Optional) Disable password logins
+
+If you want to enforce OIDC logins and disable password-based logins, set the environment variable `PASSWORD_AUTH_ENABLED` to `false`. This will hide the password login option on the login page, ensuring that all users must authenticate via Keycloak.
+
+### Step 8: (Optional) Configure permissions for new users
+
+By default, new users logging in via OIDC will be created with viewer permissions. If you want to change this default behavior, you can set the environment variables:
+
+- `OIDC_CLAIM_ROLES`: Set to the name of the claim that contains the user's role
+- `OIDC_ROLE_VIEWER`: The value of the role claim that maps to viewer permissions
+- `OIDC_ROLE_EDITOR`: The value of the role claim that maps to editor permissions
+- `OIDC_ROLE_ADMIN`: The value of the role claim that maps to admin permissions
+
+Configure Keycloak to include the appropriate role claim in the token

docs/OIDC-Guides/OIDC-Setup-With-PocketID.md

@@ -10,14 +10,6 @@ The goal of Pocket ID is to be a simple and easy-to-use. There are other self-ho
 
 Additionally, what makes Pocket ID special is that it only supports passkey authentication, which means you don’t need a password.
 
-### What is OAuth2?
-
-OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user’s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
-
-### What is OpenID Connect (OIDC)?
-
-OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user’s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
-
 ## Setting up a client in Pocket ID
 
 ### Step 1: Install and Configure Pocket ID

docs/OIDC-Guides/OIDC-Setup-With-Zitadel.md

@@ -6,14 +6,6 @@
 
 Zitadel is an enterprise-grade, open-source identity and access management (IAM) platform that supports OAuth2, OpenID Connect, SAML, and passwordless authentication. It's used to manage users, roles, and secure login for web and cloud applications.
 
-### What is OAuth2?
-
-OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user’s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
-
-### What is OpenID Connect (OIDC)?
-
-OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user’s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
-
 ## Setting up a client in Zitadel
 
 ### Step 1: Install and Configure Zitadel