From 5804a59be93bcaf8e969a01bf2acf89e56b24cfc Mon Sep 17 00:00:00 2001 From: aaldebs99 Date: Sat, 11 Oct 2025 04:51:22 +0000 Subject: [PATCH] fix(docs): OIDC callback URL, and add new options --- docs/integrations.md | 12 +- docs/oidc-setup.md | 261 ++++++++++++++++++++++++++++++++++++++--- docs/security-guide.md | 2 +- 3 files changed, 249 insertions(+), 26 deletions(-) diff --git a/docs/integrations.md b/docs/integrations.md index 6694cbf..dbc7e78 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -214,7 +214,7 @@ OIDC_ENABLED: true OIDC_ISSUER_URL: https://keycloak.example.com/auth/realms/readur OIDC_CLIENT_ID: readur-client OIDC_CLIENT_SECRET: your-client-secret -OIDC_REDIRECT_URI: https://readur.example.com/auth/oidc/callback +OIDC_REDIRECT_URI: https://readur.example.com/api/auth/oidc/callback OIDC_SCOPES: openid profile email ``` @@ -230,7 +230,7 @@ Keycloak client configuration: "frontchannelLogout": true, "protocol": "openid-connect", "redirectUris": [ - "https://readur.example.com/auth/oidc/callback" + "https://readur.example.com/api/auth/oidc/callback" ], "webOrigins": [ "https://readur.example.com" @@ -246,7 +246,7 @@ OIDC_ENABLED: true OIDC_ISSUER_URL: https://your-tenant.auth0.com/ OIDC_CLIENT_ID: your-client-id OIDC_CLIENT_SECRET: your-client-secret -OIDC_REDIRECT_URI: https://readur.example.com/auth/oidc/callback +OIDC_REDIRECT_URI: https://readur.example.com/api/auth/oidc/callback OIDC_SCOPES: openid profile email ``` @@ -258,7 +258,7 @@ OIDC_ENABLED: true OIDC_ISSUER_URL: https://your-org.okta.com/oauth2/default OIDC_CLIENT_ID: your-client-id OIDC_CLIENT_SECRET: your-client-secret -OIDC_REDIRECT_URI: https://readur.example.com/auth/oidc/callback +OIDC_REDIRECT_URI: https://readur.example.com/api/auth/oidc/callback ``` #### Azure AD @@ -269,7 +269,7 @@ OIDC_ENABLED: true OIDC_ISSUER_URL: https://login.microsoftonline.com/{tenant-id}/v2.0 OIDC_CLIENT_ID: your-application-id OIDC_CLIENT_SECRET: your-client-secret -OIDC_REDIRECT_URI: https://readur.example.com/auth/oidc/callback +OIDC_REDIRECT_URI: https://readur.example.com/api/auth/oidc/callback OIDC_SCOPES: openid profile email User.Read ``` @@ -281,7 +281,7 @@ OIDC_ENABLED: true OIDC_ISSUER_URL: https://accounts.google.com OIDC_CLIENT_ID: your-client-id.apps.googleusercontent.com OIDC_CLIENT_SECRET: your-client-secret -OIDC_REDIRECT_URI: https://readur.example.com/auth/oidc/callback +OIDC_REDIRECT_URI: https://readur.example.com/api/auth/oidc/callback OIDC_SCOPES: openid profile email ``` diff --git a/docs/oidc-setup.md b/docs/oidc-setup.md index c5a5da4..12e862b 100644 --- a/docs/oidc-setup.md +++ b/docs/oidc-setup.md @@ -14,6 +14,7 @@ This guide explains how to configure OpenID Connect (OIDC) authentication for Re - [Microsoft Azure AD](#microsoft-azure-ad) - [Keycloak](#keycloak) - [Auth0](#auth0) + - [Authentik](#authentik) - [Generic OIDC Provider](#generic-oidc-provider) - [Testing the Setup](#testing-the-setup) - [User Experience](#user-experience) @@ -25,6 +26,8 @@ This guide explains how to configure OpenID Connect (OIDC) authentication for Re OIDC authentication in Readur provides: - **Single Sign-On (SSO)**: Users can sign in with existing corporate accounts +- **Email-Based User Syncing**: Automatically link existing local users to OIDC by email +- **Flexible Auto-Registration**: Control whether new users can self-register via OIDC - **Centralized User Management**: User provisioning handled by your identity provider - **Enhanced Security**: No need to manage passwords in Readur - **Seamless Integration**: Works alongside existing local authentication @@ -52,7 +55,9 @@ Configure OIDC by setting these environment variables: | `OIDC_CLIENT_ID` | ✅ | OAuth2 client ID from your provider | `readur-app-client-id` | | `OIDC_CLIENT_SECRET` | ✅ | OAuth2 client secret from your provider | `very-secret-key` | | `OIDC_ISSUER_URL` | ✅ | OIDC provider's issuer URL | `https://accounts.google.com` | -| `OIDC_REDIRECT_URI` | ✅ | Callback URL for your Readur instance | `https://readur.company.com/auth/oidc/callback` | +| `OIDC_REDIRECT_URI` | ✅ | Callback URL for your Readur instance | `https://readur.company.com/api/auth/oidc/callback` | +| `OIDC_AUTO_REGISTER` | ❌ | Allow new users to self-register (default: `true`) | `true` or `false` | +| `ALLOW_LOCAL_AUTH` | ❌ | Allow username/password authentication (default: `true`) | `true` or `false` | ### Example Configurations @@ -66,7 +71,9 @@ OIDC_ENABLED=true OIDC_CLIENT_ID=123456789-abcdefgh.apps.googleusercontent.com OIDC_CLIENT_SECRET=GOCSPX-your-secret-key OIDC_ISSUER_URL=https://accounts.google.com -OIDC_REDIRECT_URI=https://readur.company.com/auth/oidc/callback +OIDC_REDIRECT_URI=https://readur.company.com/api/auth/oidc/callback +OIDC_AUTO_REGISTER=true # Allow new users to register via OIDC +ALLOW_LOCAL_AUTH=true # Set to false to disable username/password login ``` #### Development Setup @@ -79,7 +86,9 @@ OIDC_ENABLED=true OIDC_CLIENT_ID=dev-client-id OIDC_CLIENT_SECRET=dev-client-secret OIDC_ISSUER_URL=https://your-keycloak.company.com/auth/realms/readur -OIDC_REDIRECT_URI=http://localhost:8000/auth/oidc/callback +OIDC_REDIRECT_URI=http://localhost:8000/api/auth/oidc/callback +OIDC_AUTO_REGISTER=false # Only allow existing users to login +ALLOW_LOCAL_AUTH=true # Keep local auth for development ``` #### Docker Compose Setup @@ -98,7 +107,8 @@ services: OIDC_CLIENT_ID: "${OIDC_CLIENT_ID}" OIDC_CLIENT_SECRET: "${OIDC_CLIENT_SECRET}" OIDC_ISSUER_URL: "${OIDC_ISSUER_URL}" - OIDC_REDIRECT_URI: "https://readur.company.com/auth/oidc/callback" + OIDC_REDIRECT_URI: "https://readur.company.com/api/auth/oidc/callback" + OIDC_AUTO_REGISTER: "true" ports: - "8000:8000" ``` @@ -122,8 +132,8 @@ services: 4. **Configure Redirect URIs**: ``` Authorized redirect URIs: - https://your-readur-domain.com/auth/oidc/callback - http://localhost:8000/auth/oidc/callback (for development) + https://your-readur-domain.com/api/auth/oidc/callback + http://localhost:8000/api/auth/oidc/callback (for development) ``` 5. **Environment Variables**: @@ -132,7 +142,8 @@ services: OIDC_CLIENT_ID=123456789-abcdefgh.apps.googleusercontent.com OIDC_CLIENT_SECRET=GOCSPX-your-secret-key OIDC_ISSUER_URL=https://accounts.google.com - OIDC_REDIRECT_URI=https://your-readur-domain.com/auth/oidc/callback + OIDC_REDIRECT_URI=https://your-readur-domain.com/api/auth/oidc/callback + OIDC_AUTO_REGISTER=true ``` ### Microsoft Azure AD @@ -142,7 +153,7 @@ services: - Click "New registration" - Name: "Readur Document Management" - Supported account types: Choose based on your needs - - Redirect URI: `https://your-readur-domain.com/auth/oidc/callback` + - Redirect URI: `https://your-readur-domain.com/api/auth/oidc/callback` 2. **Configure Authentication**: - In your app registration, go to "Authentication" @@ -166,7 +177,8 @@ services: OIDC_CLIENT_ID=12345678-1234-1234-1234-123456789012 OIDC_CLIENT_SECRET=your-client-secret OIDC_ISSUER_URL=https://login.microsoftonline.com/your-tenant-id/v2.0 - OIDC_REDIRECT_URI=https://your-readur-domain.com/auth/oidc/callback + OIDC_REDIRECT_URI=https://your-readur-domain.com/api/auth/oidc/callback + OIDC_AUTO_REGISTER=true ``` ### Keycloak @@ -184,7 +196,7 @@ services: 3. **Configure Client Settings**: - Access Type: `confidential` - Standard Flow Enabled: `ON` - - Valid Redirect URIs: `https://your-readur-domain.com/auth/oidc/callback*` + - Valid Redirect URIs: `https://your-readur-domain.com/api/auth/oidc/callback*` - Web Origins: `https://your-readur-domain.com` 4. **Get Client Secret**: @@ -197,7 +209,8 @@ services: OIDC_CLIENT_ID=readur OIDC_CLIENT_SECRET=your-keycloak-client-secret OIDC_ISSUER_URL=https://keycloak.company.com/auth/realms/your-realm - OIDC_REDIRECT_URI=https://your-readur-domain.com/auth/oidc/callback + OIDC_REDIRECT_URI=https://your-readur-domain.com/api/auth/oidc/callback + OIDC_AUTO_REGISTER=true ``` ### Auth0 @@ -208,7 +221,7 @@ services: - Application Type: "Regular Web Applications" 2. **Configure Settings**: - - Allowed Callback URLs: `https://your-readur-domain.com/auth/oidc/callback` + - Allowed Callback URLs: `https://your-readur-domain.com/api/auth/oidc/callback` - Allowed Web Origins: `https://your-readur-domain.com` - Allowed Logout URLs: `https://your-readur-domain.com/login` @@ -222,15 +235,154 @@ services: OIDC_CLIENT_ID=your-auth0-client-id OIDC_CLIENT_SECRET=your-auth0-client-secret OIDC_ISSUER_URL=https://your-app.auth0.com - OIDC_REDIRECT_URI=https://your-readur-domain.com/auth/oidc/callback + OIDC_REDIRECT_URI=https://your-readur-domain.com/api/auth/oidc/callback + OIDC_AUTO_REGISTER=true ``` +### Authentik + +[Authentik](https://goauthentik.io/) is a self-hosted, open-source identity provider that's perfect for organizations wanting full control over their authentication. + +1. **Create an Application** in Authentik Admin Interface: + - Navigate to "Applications" → "Applications" + - Click "Create" and choose "Create with Wizard" + - Name: "Readur Document Management" + - Slug: `readur` (or your preferred slug) + +2. **Configure Provider**: + - Provider type: Choose "OAuth2/OpenID Provider" + - Authorization flow: "default-provider-authorization-implicit-consent" + - Client type: "Confidential" + - Redirect URIs: Add `https://your-readur-domain.com/api/auth/oidc/callback` + - Scopes: Ensure `openid`, `email`, and `profile` are included + +3. **Get Application Credentials**: + - After creation, go to your application's "Provider" settings + - Copy the Client ID (shown in the overview) + - Copy the Client Secret (click "Copy" button) + +4. **Configure Scopes and Claims** (Optional but recommended): + - Go to "Customization" → "Property Mappings" + - Ensure the following scope mappings exist and are enabled: + - `openid` → `sub` claim + - `email` → `email` claim + - `profile` → `preferred_username` and `name` claims + +5. **Get Issuer URL**: + - The issuer URL format is: `https://your-authentik-domain.com/application/o/readur/` + - Replace `readur` with your application's slug + - Alternatively, use: `https://your-authentik-domain.com/application/o//` + +6. **Environment Variables**: + ```env + OIDC_ENABLED=true + OIDC_CLIENT_ID= + OIDC_CLIENT_SECRET= + OIDC_ISSUER_URL=https://your-authentik-domain.com/application/o/readur/ + OIDC_REDIRECT_URI=https://your-readur-domain.com/api/auth/oidc/callback + OIDC_AUTO_REGISTER=true + ``` + +7. **Testing Authentik Integration**: + - Navigate to your Readur instance + - Click "Sign in with OIDC" + - You should be redirected to Authentik's login page + - After authentication, you'll be redirected back to Readur + +**Authentik-Specific Tips**: + +- **User Attributes**: Authentik automatically provides `email`, `preferred_username`, and `name` in the OIDC claims +- **Group Mapping**: You can map Authentik groups to user attributes (future Readur feature will support role mapping) +- **Self-Service Portal**: Users can manage their Authentik profile at `https://your-authentik-domain.com/if/user/` +- **Email Verification**: If email verification is required in Authentik, ensure users verify their email before using Readur +- **Custom Branding**: Authentik allows you to customize the login page to match your organization's branding + +**Docker Compose Example with Authentik**: + +If you're running both Readur and Authentik with Docker Compose: + +```yaml +version: '3.8' + +services: + authentik-server: + image: ghcr.io/goauthentik/server:latest + restart: unless-stopped + command: server + environment: + AUTHENTIK_SECRET_KEY: your-secret-key-here + AUTHENTIK_POSTGRESQL__HOST: postgresql + AUTHENTIK_POSTGRESQL__NAME: authentik + AUTHENTIK_POSTGRESQL__USER: authentik + AUTHENTIK_POSTGRESQL__PASSWORD: authentik + volumes: + - ./media:/media + - ./custom-templates:/templates + ports: + - "9000:9000" + - "9443:9443" + depends_on: + - postgresql + - redis + + readur: + image: readur:latest + environment: + DATABASE_URL: postgresql://readur:readur@postgres:5432/readur + + # Authentik OIDC Configuration + OIDC_ENABLED: "true" + OIDC_CLIENT_ID: "" + OIDC_CLIENT_SECRET: "" + OIDC_ISSUER_URL: "https://authentik.company.com/application/o/readur/" + OIDC_REDIRECT_URI: "https://readur.company.com/api/auth/oidc/callback" + OIDC_AUTO_REGISTER: "true" + ports: + - "8000:8000" + depends_on: + - postgres + + postgresql: + image: postgres:17-alpine + restart: unless-stopped + environment: + POSTGRES_PASSWORD: postgres + POSTGRES_USER: postgres + volumes: + - database:/var/lib/postgresql/data + # Create both databases + command: > + bash -c " + docker-entrypoint.sh postgres & + sleep 5 + psql -U postgres -c 'CREATE DATABASE authentik;' + psql -U postgres -c 'CREATE DATABASE readur;' + wait + " + + redis: + image: redis:alpine + restart: unless-stopped + +volumes: + database: + media: +``` + +**Troubleshooting Authentik**: + +- **"Discovery failed"**: Verify the issuer URL includes the full path with application slug +- **"Invalid client"**: Double-check the Client ID matches exactly (no extra spaces) +- **"Redirect URI mismatch"**: Ensure the redirect URI in Authentik matches `OIDC_REDIRECT_URI` exactly +- **Email not syncing**: Check that the `email` scope is enabled in your Authentik application +- **Users not linking**: Verify emails match exactly between local users and Authentik user emails + ### Generic OIDC Provider For any OIDC-compliant provider: 1. **Register Your Application** with the provider -2. **Configure Redirect URI**: `https://your-readur-domain.com/auth/oidc/callback` +2. **Configure Redirect URI**: `https://your-readur-domain.com/api/auth/oidc/callback` 3. **Get Credentials**: Client ID, Client Secret, and Issuer URL 4. **Set Environment Variables**: ```env @@ -238,7 +390,8 @@ For any OIDC-compliant provider: OIDC_CLIENT_ID=your-client-id OIDC_CLIENT_SECRET=your-client-secret OIDC_ISSUER_URL=https://your-provider.com - OIDC_REDIRECT_URI=https://your-readur-domain.com/auth/oidc/callback + OIDC_REDIRECT_URI=https://your-readur-domain.com/api/auth/oidc/callback + OIDC_AUTO_REGISTER=true ``` ## Testing the Setup @@ -252,7 +405,7 @@ When starting Readur, check the logs for OIDC configuration: ✅ OIDC_CLIENT_ID: your-client-id (loaded from env) ✅ OIDC_CLIENT_SECRET: ***hidden*** (loaded from env, 32 chars) ✅ OIDC_ISSUER_URL: https://accounts.google.com (loaded from env) -✅ OIDC_REDIRECT_URI: https://your-domain.com/auth/oidc/callback (loaded from env) +✅ OIDC_REDIRECT_URI: https://your-domain.com/api/auth/oidc/callback (loaded from env) ``` ### 2. Test Discovery Endpoint @@ -306,12 +459,82 @@ For returning users: 2. Readur matches the user by `oidc_subject` and `oidc_issuer` 3. User is automatically signed in without creating a duplicate account +### Email-Based User Syncing + +Readur intelligently handles existing local users when they first log in via OIDC: + +**Existing Local User with Matching Email**: +- When an OIDC user logs in with an email that matches an existing local user +- The OIDC identity is automatically linked to that existing account +- User retains all their documents, settings, and permissions +- The `auth_provider` field is updated to `oidc` +- Future logins can use OIDC (password still works if set) + +**Example**: If you have a local user `john.doe@company.com`, and they log in via OIDC with the same email, their account is seamlessly upgraded to support OIDC authentication without creating a duplicate account. + +### Auto-Registration Control + +The `OIDC_AUTO_REGISTER` setting controls whether new users can self-register: + +**When `OIDC_AUTO_REGISTER=true` (default)**: +- New OIDC users are automatically created when they first log in +- Perfect for open environments where any company employee should get access +- Username is derived from OIDC claims (preferred_username or email) +- Users get the default "user" role + +**When `OIDC_AUTO_REGISTER=false`**: +- Only existing users (pre-created by admin or linked by email) can log in +- OIDC login attempts by unregistered users are rejected with HTTP 403 +- Ideal for production environments requiring controlled access +- Admin must pre-create users before they can use OIDC + +**Migration Strategy**: Set to `false` initially, have existing users log in to link accounts, then enable for new users. + +### Disabling Local Authentication + +For OIDC-only deployments, you can disable local username/password authentication: + +**When `ALLOW_LOCAL_AUTH=false`**: +- Local registration endpoint returns HTTP 403 Forbidden +- Local login endpoint returns HTTP 403 Forbidden +- Only OIDC authentication is available +- Perfect for enforcing SSO-only access +- Existing local users can still be linked via email when they use OIDC + +**Security Benefits**: +- Single authentication method reduces attack surface +- Centralized password management through identity provider +- No need to manage password resets or policies in Readur +- Corporate password policies automatically apply + +**Important Notes**: +- Ensure OIDC is working before disabling local auth +- At least one admin should test OIDC login first +- Cannot disable both OIDC and local auth (server will refuse to start) +- Recommended configuration for production SSO environments + +**Example OIDC-Only Configuration**: +```env +# Enable OIDC +OIDC_ENABLED=true +OIDC_CLIENT_ID=your-client-id +OIDC_CLIENT_SECRET=your-client-secret +OIDC_ISSUER_URL=https://your-provider.com +OIDC_REDIRECT_URI=https://readur.company.com/api/auth/oidc/callback +OIDC_AUTO_REGISTER=true + +# Disable local authentication +ALLOW_LOCAL_AUTH=false +``` + ### Mixed Authentication +When both authentication methods are enabled (`ALLOW_LOCAL_AUTH=true`): - Local users can continue using username/password -- OIDC users are created as separate accounts +- OIDC users can have both OIDC and password authentication - Administrators can manage both types of users -- No automatic account linking between local and OIDC accounts +- Email-based automatic account linking prevents duplicate accounts +- Users can choose their preferred login method ## Troubleshooting @@ -398,7 +621,7 @@ curl -X GET "https://your-readur-domain.com/api/auth/oidc/callback?code=AUTH_COD 1. **Use HTTPS**: Always use HTTPS in production ```env - OIDC_REDIRECT_URI=https://readur.company.com/auth/oidc/callback + OIDC_REDIRECT_URI=https://readur.company.com/api/auth/oidc/callback ``` 2. **Secure Client Secret**: Store client secrets securely diff --git a/docs/security-guide.md b/docs/security-guide.md index 6c537f7..c60f7b8 100644 --- a/docs/security-guide.md +++ b/docs/security-guide.md @@ -34,7 +34,7 @@ OIDC_ENABLED: "true" OIDC_CLIENT_ID: "readur-client" OIDC_CLIENT_SECRET: "your-client-secret" OIDC_ISSUER_URL: "https://auth.example.com/realms/readur" -OIDC_REDIRECT_URI: "https://readur.example.com/auth/oidc/callback" +OIDC_REDIRECT_URI: "https://readur.example.com/api/auth/oidc/callback" OIDC_SCOPES: "openid profile email" ```