From 7d3490a079dfd70565fa17d07cb2f21c2fb90a8e Mon Sep 17 00:00:00 2001 From: ShaddyDC Date: Mon, 6 Jan 2025 10:30:42 +0100 Subject: [PATCH] doc(openid-connect): Add initial setup instructions (#7174) * doc(openid-connect): Add initial setup instructions See discussion for reference: https://github.com/FreshRSS/FreshRSS/discussions/5684#discussioncomment-11707635 * style(openid-connect): Change lists to dash style * Minimize changes * Typography --------- Co-authored-by: Alexandre Alapetite --- docs/en/admins/16_OpenID-Connect.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/en/admins/16_OpenID-Connect.md b/docs/en/admins/16_OpenID-Connect.md index 283b2ffdb..0c77f955e 100644 --- a/docs/en/admins/16_OpenID-Connect.md +++ b/docs/en/admins/16_OpenID-Connect.md @@ -10,13 +10,30 @@ Additional documentation can be found in that project. The callback URL is `https:///i/oidc/`. +## Initial Setup Process + +When setting up a new FreshRSS instance with OIDC, follow these steps carefully to ensure proper administrator access: + +1. Configure your OIDC environment variables (see configuration section below) +2. Start your FreshRSS instance +3. Access the Web interface – it will immediately attempt to authenticate you via your OIDC provider +4. After successful authentication, you’ll be directed to the setup wizard +5. In the authentication setup step (currently *step 4*): + * Enter the exact username that matches your OIDC identity (e.g., `admin@idm.example.com`) as the default user + * The password field can contain any random value as it won’t be used with OIDC + * Select *HTTP Authentication Method* as the authentication method + * If configured correctly, you should see your current username displayed as: `HTTP (for advanced users with HTTPS) (REMOTE_USER='admin@idm.example.com')`. If it doesn’t, recheck your OIDC setup and the variables to avoid locking yourself out from administrator access. +6. Complete the remaining setup steps + +> ⚠️ Important: Using a random username instead of your actual OIDC identity as the default user may result in no administrator access to your instance. + ## Using Docker OIDC support in Docker is activated by the presence of a non-empty non-zero `OIDC_ENABLED` environment variable. > ℹ️ Only available in our default Debian image (not Alpine) for `x86_64` ([help welcome](https://github.com/FreshRSS/FreshRSS/issues/5722)). -## The config is done with these environment variables +## Configuration Environment Variables * `OIDC_ENABLED`: Activates OIDC support. * `OIDC_PROVIDER_METADATA_URL`: The config URL. Usually looks like: `/.well-known/openid-configuration` @@ -36,14 +53,6 @@ You may add additional custom configuration in a new `./FreshRSS/p/i/.htaccess` See our reference [Apache configuration](https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/FreshRSS.Apache.conf) for more information. -## Setup - -After being properly configured, OIDC support can be activated in FreshRSS. - -During a new FreshRSS install, the **HTTP Authentication Method** must be picked. - -After install, the method can be changed in *Administration > Authentication*. Note that this option will be greyed out if Apache is unable to read the `REMOTE_USER` variable. - ## Identity Provider See specific instructions for: