From 4b19964817dfdafcd84d6b811a9c9da96c60625c Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Mon, 13 Oct 2025 18:08:04 +0200 Subject: [PATCH] docs: Update docs --- docs/authentication.md | 43 +++++++++++++++++++++++++++++++++++++---- docs/configuration.md | 12 +++++++++--- docs/oauth-setup.md | 36 +++++++++++++++++++++++++++++++--- docs/troubleshooting.md | 23 +++++++++++++++------- 4 files changed, 97 insertions(+), 17 deletions(-) diff --git a/docs/authentication.md b/docs/authentication.md index aabf0fd..9db7785 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -13,6 +13,34 @@ The Nextcloud MCP server supports two authentication modes for connecting to you OAuth2/OIDC authentication provides secure, token-based authentication following modern security standards. +### Required Nextcloud Apps + +OAuth authentication requires **two Nextcloud apps** to work together: + +#### 1. `oidc` - OIDC Identity Provider +**Purpose:** Makes Nextcloud an OAuth2/OIDC authorization server + +**Provides:** +- OAuth2 authorization endpoint (`/apps/oidc/authorize`) +- Token endpoint (`/apps/oidc/token`) +- User info endpoint (`/apps/oidc/userinfo`) +- JWKS endpoint for token validation (`/apps/oidc/jwks`) +- Dynamic client registration endpoint (`/apps/oidc/register`) + +**Installation:** Available in Nextcloud App Store under "Security" + +#### 2. `user_oidc` - OpenID Connect User Backend +**Purpose:** Authenticates users and validates Bearer tokens + +**Provides:** +- Bearer token validation against the OIDC provider +- User authentication via OIDC +- Session management for authenticated users + +**Installation:** Available in Nextcloud App Store under "Security" + +**Important:** The `user_oidc` app requires a patch for Bearer token support on non-OCS endpoints (like Notes API). See [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md) for details. + ### Benefits - **Zero-config deployment** via dynamic client registration - **No credential storage** in environment variables @@ -23,10 +51,17 @@ OAuth2/OIDC authentication provides secure, token-based authentication following ### Current Implementation Limitations > [!IMPORTANT] -> - Only tested with Nextcloud `user_oidc` and `oidc` apps (Nextcloud as identity provider) -> - Requires a patch for Bearer token support on non-OCS endpoints (see [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md)) -> - External identity providers (Azure AD, Keycloak, etc.) have not been tested -> - Dynamic client registration credentials expire (default: 1 hour) - use pre-configured clients for production +> **Tested Configuration:** +> - ✅ Nextcloud `oidc` app (OIDC Identity Provider) + `user_oidc` app (OIDC User Backend) +> - ✅ Nextcloud acting as its own identity provider (self-hosted OIDC) +> +> **Not Tested:** +> - ❌ External identity providers (Azure AD, Keycloak, Okta, etc.) +> - ❌ Using `user_oidc` with external OIDC providers +> +> **Known Requirements:** +> - 🔧 The `user_oidc` app requires a patch for Bearer token support on non-OCS endpoints (see [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md)) +> - ⏱️ Dynamic client registration credentials expire (default: 1 hour) - use pre-configured clients for production ### How OAuth Works diff --git a/docs/configuration.md b/docs/configuration.md index f1e881a..3742b1f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -70,9 +70,15 @@ NEXTCLOUD_PASSWORD= Before using OAuth configuration: -1. **Install Nextcloud OIDC app** - Navigate to Apps → Security in your Nextcloud instance -2. **Enable dynamic client registration** (if using auto-registration) - Settings → OIDC -3. **Apply Bearer token patch** (if using non-OCS endpoints) - See [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md) +1. **Install required Nextcloud apps** (both are required): + - **`oidc`** - OIDC Identity Provider (Apps → Security) + - **`user_oidc`** - OpenID Connect user backend (Apps → Security) + +2. **Configure the apps**: + - Enable dynamic client registration (if using auto-registration) - Settings → OIDC + - Enable Bearer token validation: `php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean` + +3. **Apply Bearer token patch** - The `user_oidc` app requires a patch for non-OCS endpoints - See [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md) See the [OAuth Setup Guide](oauth-setup.md) for detailed instructions. diff --git a/docs/oauth-setup.md b/docs/oauth-setup.md index 29343b1..aa7c692 100644 --- a/docs/oauth-setup.md +++ b/docs/oauth-setup.md @@ -8,14 +8,33 @@ This guide walks you through setting up OAuth2/OIDC authentication for the Nextc - Python 3.11+ installed - Nextcloud MCP server installed (see [Installation Guide](installation.md)) -## Step 1: Install Nextcloud OIDC App +## Step 1: Install Required Nextcloud Apps + +OAuth authentication requires **two apps** to work together: + +### Install the OIDC Identity Provider App 1. Open your Nextcloud instance as an administrator 2. Navigate to **Apps** → **Security** -3. Find and install the **OpenID Connect user backend** app +3. Find and install the **OIDC** app (full name: "OIDC Identity Provider") 4. Enable the app -## Step 2: Enable Dynamic Client Registration +This app makes Nextcloud an OAuth2/OIDC authorization server. + +### Install the OpenID Connect User Backend App + +1. In **Apps** → **Security** +2. Find and install the **OpenID Connect user backend** app (app ID: `user_oidc`) +3. Enable the app + +This app handles Bearer token validation and user authentication. + +> [!IMPORTANT] +> **Required Patch:** The `user_oidc` app needs a patch for Bearer token authentication to work with non-OCS endpoints (like Notes API). See [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md) for the patch and installation instructions. + +## Step 2: Configure OIDC Apps + +### Enable Dynamic Client Registration (for `oidc` app) 1. Navigate to **Settings** → **OIDC** (in Administration settings) 2. Find the **Dynamic Client Registration** section @@ -26,6 +45,17 @@ This guide walks you through setting up OAuth2/OIDC authentication for the Nextc php occ config:app:set oidc expire_time --value "86400" # 24 hours ``` +### Enable Bearer Token Validation (for `user_oidc` app) + +Configure the `user_oidc` app to validate bearer tokens from the `oidc` Identity Provider: + +```bash +# Via Nextcloud CLI (occ) - required for Bearer token authentication +php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean +``` + +This tells the `user_oidc` app to validate Bearer tokens against Nextcloud's own OIDC Identity Provider. + ## Step 3: Choose Your Setup Approach You have two options for configuring OAuth clients: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 31ffb96..d75a5a8 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -25,23 +25,30 @@ echo $NEXTCLOUD_HOST ### Issue: "OAuth mode requires either client credentials OR dynamic client registration" -**Cause:** The Nextcloud OIDC app either: -1. Is not installed -2. Doesn't have dynamic client registration enabled -3. Isn't providing a registration endpoint +**Cause:** The required Nextcloud OIDC apps are either: +1. Not installed (both `oidc` and `user_oidc` apps are required) +2. Don't have dynamic client registration enabled +3. Aren't providing a registration endpoint **Solution:** **Option 1: Enable dynamic client registration** -1. Verify OIDC app is installed: +1. Verify **both** OIDC apps are installed: - Navigate to Nextcloud **Apps** → **Security** - - Install "OpenID Connect user backend" if not present + - Install **"OIDC"** (OIDC Identity Provider app) if not present + - Install **"OpenID Connect user backend"** (user_oidc app) if not present 2. Enable dynamic client registration: - Go to **Settings** → **OIDC** (Administration) - Enable "Allow dynamic client registration" +3. Configure Bearer token validation: + ```bash + # Required for user_oidc app to validate tokens + php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean + ``` + 3. Verify the registration endpoint exists: ```bash curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.registration_endpoint' @@ -172,7 +179,9 @@ mkdir -p $(dirname .nextcloud_oauth_client.json) ping your.nextcloud.instance.com ``` -4. Verify OIDC app is installed and enabled in Nextcloud +4. Verify **both** OIDC apps are installed and enabled in Nextcloud: + - `oidc` - OIDC Identity Provider + - `user_oidc` - OpenID Connect user backend 5. Check firewall rules if using Docker