docs: Update docs

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
 

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.
 

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:

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