fix(docs): OIDC callback URL, and add new options

2026-01-06 06:20:17 -06:00 · 2025-10-11 04:51:22 +00:00
parent 10d461aeac
commit 5804a59be9
3 changed files with 249 additions and 26 deletions
--- 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
 ```

--- 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/<application-slug>/`
+
+6. **Environment Variables**:
+   ```env
+   OIDC_ENABLED=true
+   OIDC_CLIENT_ID=<your-authentik-client-id>
+   OIDC_CLIENT_SECRET=<your-authentik-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: "<from-authentik-application>"
+      OIDC_CLIENT_SECRET: "<from-authentik-application>"
+      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
--- 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"
 ```