From 395e71164f5c71c211f45bfed3a5960f5d6c04e4 Mon Sep 17 00:00:00 2001 From: Arunavo Ray Date: Sun, 26 Oct 2025 19:52:44 +0530 Subject: [PATCH] Added basic docs on SSO/OIDC --- README.md | 2 ++ docs/SSO-OIDC-SETUP.md | 23 ++++++++++++++++++++++- scripts/setup-authentik-test.sh | 12 ++++++++---- 3 files changed, 32 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b280d9f..b4c970b 100644 --- a/README.md +++ b/README.md @@ -326,6 +326,8 @@ Enable users to sign in with external identity providers like Google, Azure AD, https://your-domain.com/api/auth/sso/callback/{provider-id} ``` +Need help? The [SSO & OIDC guide](docs/SSO-OIDC-SETUP.md) now includes a working Authentik walkthrough plus troubleshooting tips. If you upgraded from a version earlier than v3.8.10 and see `TypeError … url.startsWith` after the callback, delete the old provider and add it again using the Discover button (see [#73](https://github.com/RayLabsHQ/gitea-mirror/issues/73) and [#122](https://github.com/RayLabsHQ/gitea-mirror/issues/122)). + ### 3. Header Authentication (Reverse Proxy) Perfect for automatic authentication when using reverse proxies like Authentik, Authelia, or Traefik Forward Auth. diff --git a/docs/SSO-OIDC-SETUP.md b/docs/SSO-OIDC-SETUP.md index e1626fa..3d33662 100644 --- a/docs/SSO-OIDC-SETUP.md +++ b/docs/SSO-OIDC-SETUP.md @@ -81,6 +81,26 @@ Replace `{provider-id}` with your chosen Provider ID. - Client Secret: [Your Okta Client Secret] - Click "Discover" to auto-fill endpoints +### Example: Authentik SSO Setup + +Working Authentik deployments (see [#134](https://github.com/RayLabsHQ/gitea-mirror/issues/134)) follow these steps: + +1. In Authentik, create a new **Application** and OIDC **Provider** (implicit flow works well for testing). +2. Start creating an SSO provider inside Gitea Mirror so you can copy the redirect URL shown (`https://your-domain.com/api/auth/sso/callback/authentik` if you pick `authentik` as your Provider ID). +3. Paste that redirect URL into the Authentik Provider configuration and finish creating the provider. +4. Copy the Authentik issuer URL, client ID, and client secret. +5. Back in Gitea Mirror: + - Issuer URL: the exact value from Authentik (keep any trailing slash Authentik shows). + - Provider ID: match the one you used in step 2. + - Click **Discover** so Gitea Mirror stores the authorization, token, and JWKS endpoints (Authentik publishes them via discovery). + - Domain: enter the email domain you expect to match (e.g. `example.com`). +6. Save the provider and test the login flow. + +Notes: +- Make sure `BETTER_AUTH_URL` and (if you serve the UI from multiple origins) `BETTER_AUTH_TRUSTED_ORIGINS` point at the public URL users reach. A mismatch can surface as 500 errors after redirect. +- Authentik must report the user’s email as verified (default behavior) so Gitea Mirror can auto-link accounts. +- If you created an Authentik provider before v3.8.10 you should delete it and re-add it after upgrading; older versions saved incomplete endpoint data which leads to the `url.startsWith` error explained in the Troubleshooting section. + ## Setting up OIDC Provider The OIDC Provider feature allows other applications to use Gitea Mirror as their authentication provider. @@ -165,6 +185,7 @@ When an application requests authentication: 1. **"Invalid origin" error**: Check that your Gitea Mirror URL matches the configured redirect URI 2. **"Provider not found" error**: Ensure the provider is properly configured and enabled 3. **Redirect loop**: Verify the redirect URI in both Gitea Mirror and the SSO provider match exactly +4. **`TypeError: undefined is not an object (evaluating 'url.startsWith')`**: This indicates the stored provider configuration is missing OIDC endpoints. Delete the provider from Gitea Mirror and re-register it using the **Discover** button so authorization/token URLs are saved (see [#73](https://github.com/RayLabsHQ/gitea-mirror/issues/73) and [#122](https://github.com/RayLabsHQ/gitea-mirror/issues/122) for examples). ### OIDC Provider Issues @@ -202,4 +223,4 @@ This immediately prevents the application from authenticating new users. If migrating from the previous JWT-based authentication: - Existing users remain unaffected - Users can continue using email/password authentication -- SSO can be added as an additional authentication method \ No newline at end of file +- SSO can be added as an additional authentication method diff --git a/scripts/setup-authentik-test.sh b/scripts/setup-authentik-test.sh index 170b0d9..0aec993 100755 --- a/scripts/setup-authentik-test.sh +++ b/scripts/setup-authentik-test.sh @@ -114,10 +114,10 @@ EOF echo "======================================" echo "1. Access Authentik at http://localhost:9000" echo "2. Login with akadmin / admin-password" - echo "3. Create OAuth2 Provider for Gitea Mirror:" + echo "3. Create an Authentik OIDC Provider for Gitea Mirror:" echo " - Name: gitea-mirror" - echo " - Redirect URIs:" - echo " http://localhost:4321/api/auth/callback/sso-provider" + echo " - Redirect URI:" + echo " http://localhost:4321/api/auth/sso/callback/authentik" echo " - Scopes: openid, profile, email" echo "" echo "4. Create Application:" @@ -131,10 +131,14 @@ EOF echo "6. Configure SSO in Gitea Mirror:" echo " - Go to Settings → Authentication & SSO" echo " - Add provider with:" + echo " - Provider ID: authentik" echo " - Issuer URL: http://localhost:9000/application/o/gitea-mirror/" + echo " - Click Discover to pull Authentik endpoints" echo " - Client ID: (from Authentik provider)" echo " - Client Secret: (from Authentik provider)" echo "" + echo "If you previously registered this provider on a version earlier than v3.8.10, delete it and re-add it after upgrading to avoid missing endpoint data." + echo "" ;; stop) @@ -177,4 +181,4 @@ EOF echo " status - Show service status" exit 1 ;; -esac \ No newline at end of file +esac