Add OIDC authentication configuration documentation (#46)

* Add OIDC authentication configuration documentation

Documents OIDC setup including custom providers, built-in providers (Google, Microsoft, GitHub), and configuration examples with comprehensive setting descriptions.

* Document missing OIDC configuration variables and role mapping

- Add OIDC_USERNAME_CLAIM and OIDC_OPENID_CONFIG_URL to base config table
- Add complete OIDC Role Mapping section documenting:
  - OIDC_ROLE_CLAIM for customizing the claim name
  - OIDC_GROUP_* variables for mapping provider groups to Gramps roles
- Add role mapping example to OIDC configuration example
- Include notes on role mapping behavior and case sensitivity

* Add OIDC logout and backchannel logout documentation

- Document OIDC Single Sign-Out (SSO logout) functionality
- Add comprehensive backchannel logout setup instructions
- Include provider-specific configuration for Keycloak and Authentik
- Explain token expiration limitations and security considerations
- Add step-by-step guide for registering backchannel logout endpoint

* add redirect URI instructions

* Reorganize OIDC documentation into dedicated page

Create separate OIDC authentication page with setup instructions and examples, while keeping settings reference in configuration page.

* Convert OIDC variable lists to table format for consistency

Updates oidc.md to use table format for Custom OIDC Providers and Role Mapping configuration variables, matching the style used in configuration.md. Also improves variable descriptions for clarity and adds spacing for proper list rendering.

* fix info and warn boxes

Author: AlexBocken

docs/install_setup/configuration.md

@@ -27,7 +27,7 @@ The following configuration options exist.
 
 ### Required settings
 
-Key | Description 
+Key | Description
 ----|-------------
 `TREE` | The name of the family tree database to use. Show available trees with `gramps -l`. If a tree with this name does not exist, a new empty one will be created.
 `SECRET_KEY` | The secret key for flask. The secret must not be shared publicly. Changing it will invalidate all access tokens.
@@ -42,7 +42,7 @@ Key | Description
 
 ### Optional settings
 
-Key | Description 
+Key | Description
 ----|-------------
 `MEDIA_BASE_DIR` | Path to use as base directory for media files, overriding the media base directory set in Gramps. When using [S3](s3.md), must have the form `s3://<bucket_name>`
 `SEARCH_INDEX_DB_URI` | Database URL for the search index. Only `sqlite` or `postgresql` are allowed as backends. Defaults to `sqlite:///indexdir/search_index.db`, creating an SQLite file in the folder `indexdir` relative to the path where the script is run
@@ -73,7 +73,7 @@ Key | Description
 
 This is required if you've configured your Gramps database to work with the [PostgreSQL addon](https://gramps-project.org/wiki/index.php/Addon:PostgreSQL).
 
-Key | Description 
+Key | Description
 ----|-------------
 `POSTGRES_USER` | The user name for the database connection
 `POSTGRES_PASSWORD` | The password for the database user
@@ -84,19 +84,63 @@ Key | Description
 The following settings are relevant when [hosting multiple trees](multi-tree.md).
 
 
-Key | Description 
+Key | Description
 ----|-------------
 `MEDIA_PREFIX_TREE` | Boolean, whether or not to use a separate subfolder for the media files of each tree. Defaults to `False`, but strongly recommend to use `True` in a multi-tree setup
 `NEW_DB_BACKEND` | The database backend to use for newly created family trees. Must be one of `sqlite`, `postgresql`, or `sharedpostgresql`. Defaults to `sqlite`.
 `POSTGRES_HOST` | The host name of the PostgreSQL server used for creating new trees when using a multi-tree setup with the SharedPostgreSQL backend
 `POSTGRES_PORT` | The port of the PostgreSQL server used for creating new trees when using a multi-tree setup with the SharedPostgreSQL backend
 
- 
+
+### Settings for OIDC authentication
+
+These settings are needed if you want to use OpenID Connect (OIDC) authentication with external providers. For detailed setup instructions and examples, see [OIDC Authentication](oidc.md).
+
+Key | Description
+----|-------------
+`OIDC_ENABLED` | Boolean, whether to enable OIDC authentication. Defaults to `False`.
+`OIDC_ISSUER` | OIDC provider issuer URL (for custom OIDC providers)
+`OIDC_CLIENT_ID` | OAuth client ID (for custom OIDC providers)
+`OIDC_CLIENT_SECRET` | OAuth client secret (for custom OIDC providers)
+`OIDC_NAME` | Custom display name for the provider. Defaults to "OIDC"
+`OIDC_SCOPES` | OAuth scopes. Defaults to "openid email profile"
+`OIDC_USERNAME_CLAIM` | The claim to use for the username. Defaults to "preferred_username"
+`OIDC_OPENID_CONFIG_URL` | Optional: URL to the OpenID Connect configuration endpoint (if not using standard `/.well-known/openid-configuration`)
+`OIDC_DISABLE_LOCAL_AUTH` | Boolean, whether to disable local username/password authentication. Defaults to `False`
+`OIDC_AUTO_REDIRECT` | Boolean, whether to automatically redirect to OIDC when only one provider is configured. Defaults to `False`
+
+#### Built-in OIDC providers
+
+For built-in providers (Google, Microsoft, GitHub), use these settings:
+
+Key | Description
+----|-------------
+`OIDC_GOOGLE_CLIENT_ID` | Client ID for Google OAuth
+`OIDC_GOOGLE_CLIENT_SECRET` | Client secret for Google OAuth
+`OIDC_MICROSOFT_CLIENT_ID` | Client ID for Microsoft OAuth
+`OIDC_MICROSOFT_CLIENT_SECRET` | Client secret for Microsoft OAuth
+`OIDC_GITHUB_CLIENT_ID` | Client ID for GitHub OAuth
+`OIDC_GITHUB_CLIENT_SECRET` | Client secret for GitHub OAuth
+
+#### OIDC Role Mapping
+
+These settings allow you to map OIDC groups/roles from your identity provider to Gramps Web user roles:
+
+Key | Description
+----|-------------
+`OIDC_ROLE_CLAIM` | The claim name in the OIDC token that contains the user's groups/roles. Defaults to "groups"
+`OIDC_GROUP_ADMIN` | The group/role name from your OIDC provider that maps to the Gramps "Admin" role
+`OIDC_GROUP_OWNER` | The group/role name from your OIDC provider that maps to the Gramps "Owner" role
+`OIDC_GROUP_EDITOR` | The group/role name from your OIDC provider that maps to the Gramps "Editor" role
+`OIDC_GROUP_CONTRIBUTOR` | The group/role name from your OIDC provider that maps to the Gramps "Contributor" role
+`OIDC_GROUP_MEMBER` | The group/role name from your OIDC provider that maps to the Gramps "Member" role
+`OIDC_GROUP_GUEST` | The group/role name from your OIDC provider that maps to the Gramps "Guest" role
+
 ### Settings only for AI features
 
 These settings are needed if you want to use AI-powered features like chat or semantic search.
 
-Key | Description 
+Key | Description
 ----|-------------
 `LLM_BASE_URL` | Base URL for the OpenAI-compatible chat API. Defaults to `None`, which uses the OpenAI API.
 `LLM_MODEL` | The model to use for the OpenAI-compatible chat API. If unset (the default), chat is disabled.

docs/install_setup/oidc.md

@@ -0,0 +1,198 @@
+# OIDC Authentication
+
+Gramps Web supports OpenID Connect (OIDC) authentication, allowing users to log in using external identity providers. This includes both popular providers like Google, Microsoft, and GitHub, as well as custom OIDC providers like Keycloak, Authentik, and others.
+
+## Overview
+
+OIDC authentication allows you to:
+
+- Use external identity providers for user authentication
+- Support multiple authentication providers simultaneously
+- Map OIDC groups/roles to Gramps Web user roles
+- Implement Single Sign-On (SSO) and Single Sign-Out
+- Optionally disable local username/password authentication
+
+## Configuration
+
+To enable OIDC authentication, you need to configure the appropriate settings in your Gramps Web configuration file or environment variables. See the [Server Configuration](configuration.md#settings-for-oidc-authentication) page for a complete list of available OIDC settings.
+
+!!! info
+    When using environment variables, remember to prefix each setting name with `GRAMPSWEB_` (e.g., `GRAMPSWEB_OIDC_ENABLED`). See [Configuration file vs. environment variables](configuration.md#configuration-file-vs-environment-variables) for details.
+
+### Built-in Providers
+
+Gramps Web has built-in support for popular identity providers. To use them, you only need to provide the client ID and client secret:
+
+- **Google**: `OIDC_GOOGLE_CLIENT_ID` and `OIDC_GOOGLE_CLIENT_SECRET`
+- **Microsoft**: `OIDC_MICROSOFT_CLIENT_ID` and `OIDC_MICROSOFT_CLIENT_SECRET`
+- **GitHub**: `OIDC_GITHUB_CLIENT_ID` and `OIDC_GITHUB_CLIENT_SECRET`
+
+You can configure multiple providers simultaneously. The system will automatically detect which providers are available based on the configuration values.
+
+### Custom OIDC Providers
+
+For custom OIDC providers (like Keycloak, Authentik, or any standard OIDC-compliant provider), use these settings:
+
+Key | Description
+----|-------------
+`OIDC_ENABLED` | Boolean, whether to enable OIDC authentication. Set to `True`.
+`OIDC_ISSUER` | Your provider's issuer URL
+`OIDC_CLIENT_ID` | Client ID for your OIDC provider
+`OIDC_CLIENT_SECRET` | Client secret for your OIDC provider
+`OIDC_NAME` | Custom display name (optional, defaults to "OIDC")
+`OIDC_SCOPES` | OAuth scopes (optional, defaults to "openid email profile")
+
+## Required Redirect URIs
+
+When configuring your OIDC provider, you must register the following redirect URI:
+
+**For web application access:**
+
+- `https://your-gramps-backend.com/api/oidc/callback/*`
+
+Where `*` is a regex wildcard. Depending on your provider's regex interpreter this could also be a `.*` or similar.
+Ensure that regex is enabled if your provider requires it (e.g., Authentik).
+
+
+## Role Mapping
+
+Gramps Web can automatically map OIDC groups or roles from your identity provider to Gramps Web user roles. This allows you to manage user permissions centrally in your identity provider.
+
+### Configuration
+
+Use these settings to configure role mapping:
+
+Key | Description
+----|-------------
+`OIDC_ROLE_CLAIM` | The claim name in the OIDC token that contains the user's groups/roles. Defaults to "groups"
+`OIDC_GROUP_ADMIN` | The group/role name from your OIDC provider that maps to the Gramps "Admin" role
+`OIDC_GROUP_OWNER` | The group/role name from your OIDC provider that maps to the Gramps "Owner" role
+`OIDC_GROUP_EDITOR` | The group/role name from your OIDC provider that maps to the Gramps "Editor" role
+`OIDC_GROUP_CONTRIBUTOR` | The group/role name from your OIDC provider that maps to the Gramps "Contributor" role
+`OIDC_GROUP_MEMBER` | The group/role name from your OIDC provider that maps to the Gramps "Member" role
+`OIDC_GROUP_GUEST` | The group/role name from your OIDC provider that maps to the Gramps "Guest" role
+
+### Role Mapping Behavior
+
+- If no role mapping is configured (no `OIDC_GROUP_*` variables set), existing user roles are preserved
+- Users are assigned the highest role they are entitled to based on their group membership
+- Role mapping is case-sensitive by default (depends on your OIDC provider)
+
+## OIDC Logout
+
+Gramps Web supports Single Sign-Out (SSO logout) for OIDC providers. When a user logs out from Gramps Web after authenticating via OIDC, they will be automatically redirected to the identity provider's logout page if the provider supports the `end_session_endpoint`.
+
+### Backchannel Logout
+
+Gramps Web implements the OpenID Connect Back-Channel Logout specification. This allows identity providers to notify Gramps Web when a user logs out from another application or the identity provider itself.
+
+#### Configuration
+
+To configure backchannel logout with your identity provider:
+
+1. **Register the backchannel logout endpoint** in your identity provider's client configuration:
+   ```
+   https://your-gramps-backend.com/api/oidc/backchannel-logout/
+   ```
+
+2. **Configure your provider** to send logout notifications. The exact steps depend on your provider:
+
+   **Keycloak:**
+
+   - In your client configuration, navigate to "Settings"
+   - Set "Backchannel Logout URL" to `https://your-gramps-backend.com/api/oidc/backchannel-logout/`
+   - Enable "Backchannel Logout Session Required" if you want session-based logout
+
+   **Authentik:**
+
+   - In your provider configuration, add the backchannel logout URL
+   - Ensure the provider is configured to send logout tokens
+
+!!! warning "Token Expiration"
+    Due to the stateless nature of JWT tokens, backchannel logout currently logs the logout event but cannot immediately revoke already-issued JWT tokens. Tokens will remain valid until they expire (default: 15 minutes for access tokens).
+
+    For enhanced security, consider:
+
+    - Reducing JWT token expiration time (`JWT_ACCESS_TOKEN_EXPIRES`)
+    - Educating users to manually log out from Gramps Web when logging out from your identity provider
+
+!!! tip "How It Works"
+    When a user logs out from your identity provider or another application:
+
+    1. The provider sends a `logout_token` JWT to Gramps Web's backchannel logout endpoint
+    2. Gramps Web validates the token and logs the logout event
+    3. The logout token's JTI is added to a blocklist to prevent replay attacks
+    4. Any new API requests with the user's JWT will be denied once tokens expire
+
+## Example Configurations
+
+### Custom OIDC Provider (Keycloak)
+
+```python
+TREE="My Family Tree"
+BASE_URL="https://mytree.example.com"
+SECRET_KEY="..."  # your secret key
+USER_DB_URI="sqlite:////path/to/users.sqlite"
+
+# Custom OIDC Configuration
+OIDC_ENABLED=True
+OIDC_ISSUER="https://auth.example.com/realms/myrealm"
+OIDC_CLIENT_ID="gramps-web"
+OIDC_CLIENT_SECRET="your-client-secret"
+OIDC_NAME="Family SSO"
+OIDC_SCOPES="openid email profile"
+OIDC_AUTO_REDIRECT=True  # Optional: automatically redirect to SSO login
+OIDC_DISABLE_LOCAL_AUTH=True  # Optional: disable username/password login
+
+# Optional: Role mapping from OIDC groups to Gramps roles
+OIDC_ROLE_CLAIM="groups"  # or "roles" depending on your provider
+OIDC_GROUP_ADMIN="gramps-admins"
+OIDC_GROUP_EDITOR="gramps-editors"
+OIDC_GROUP_MEMBER="gramps-members"
+
+EMAIL_HOST="mail.example.com"
+EMAIL_PORT=465
+EMAIL_USE_TLS=True
+EMAIL_HOST_USER="[email protected]"
+EMAIL_HOST_PASSWORD="..." # your SMTP password
+DEFAULT_FROM_EMAIL="[email protected]"
+```
+
+### Built-in Provider (Google)
+
+```python
+TREE="My Family Tree"
+BASE_URL="https://mytree.example.com"
+SECRET_KEY="..."  # your secret key
+USER_DB_URI="sqlite:////path/to/users.sqlite"
+
+# Google OAuth
+OIDC_GOOGLE_CLIENT_ID="your-google-client-id"
+OIDC_GOOGLE_CLIENT_SECRET="your-google-client-secret"
+```
+
+### Multiple Providers
+
+You can enable multiple OIDC providers simultaneously:
+
+```python
+TREE="My Family Tree"
+BASE_URL="https://mytree.example.com"
+SECRET_KEY="..."  # your secret key
+USER_DB_URI="sqlite:////path/to/users.sqlite"
+
+# Custom provider
+OIDC_ENABLED=True
+OIDC_ISSUER="https://auth.example.com/realms/myrealm"
+OIDC_CLIENT_ID="gramps-web"
+OIDC_CLIENT_SECRET="your-client-secret"
+OIDC_NAME="Company SSO"
+
+# Google OAuth
+OIDC_GOOGLE_CLIENT_ID="your-google-client-id"
+OIDC_GOOGLE_CLIENT_SECRET="your-google-client-secret"
+
+# GitHub OAuth
+OIDC_GITHUB_CLIENT_ID="your-github-client-id"
+OIDC_GITHUB_CLIENT_SECRET="your-github-client-secret"
+```

mkdocs.yml

@@ -12,6 +12,7 @@ nav:
       - Server Administration:
           - User system:  install_setup/users.md
           - Server configuration:  install_setup/configuration.md
+          - OIDC authentication:  install_setup/oidc.md
           - Setting up AI chat: install_setup/chat.md
           - Multi-tree setup:  install_setup/multi-tree.md
           - Frontend customization:  install_setup/frontend-config.md