docs: Update README and docs
This commit is contained in:
Chris Coutinho
@@ -0,0 +1,225 @@
|
||||
# OAuth Setup Guide
|
||||
|
||||
This guide walks you through setting up OAuth2/OIDC authentication for the Nextcloud MCP server.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Nextcloud instance with administrator access
|
||||
- Python 3.11+ installed
|
||||
- Nextcloud MCP server installed (see [Installation Guide](installation.md))
|
||||
|
||||
## Step 1: Install Nextcloud OIDC App
|
||||
|
||||
1. Open your Nextcloud instance as an administrator
|
||||
2. Navigate to **Apps** → **Security**
|
||||
3. Find and install the **OpenID Connect user backend** app
|
||||
4. Enable the app
|
||||
|
||||
## Step 2: Enable Dynamic Client Registration
|
||||
|
||||
1. Navigate to **Settings** → **OIDC** (in Administration settings)
|
||||
2. Find the **Dynamic Client Registration** section
|
||||
3. Enable **"Allow dynamic client registration"**
|
||||
4. (Optional) Configure client expiration time:
|
||||
```bash
|
||||
# Via Nextcloud CLI (occ) - optional, default is 3600 seconds (1 hour)
|
||||
php occ config:app:set oidc expire_time --value "86400" # 24 hours
|
||||
```
|
||||
|
||||
## Step 3: Choose Your Setup Approach
|
||||
|
||||
You have two options for configuring OAuth clients:
|
||||
|
||||
### Approach A: Automatic Registration (Zero-config)
|
||||
|
||||
**Best for:** Development, testing, short-lived deployments
|
||||
|
||||
**How it works:** The MCP server automatically registers a new OAuth client with Nextcloud at startup using dynamic client registration.
|
||||
|
||||
**Pros:**
|
||||
- Zero configuration required
|
||||
- Quick to set up
|
||||
- No manual client management
|
||||
|
||||
**Cons:**
|
||||
- Clients expire (default: 1 hour)
|
||||
- Server must re-register on restart if expired
|
||||
- Not recommended for long-running production deployments
|
||||
|
||||
[Jump to Approach A setup →](#approach-a-automatic-registration)
|
||||
|
||||
### Approach B: Pre-configured Client (Production)
|
||||
|
||||
**Best for:** Production, long-running deployments
|
||||
|
||||
**How it works:** You manually create an OAuth client via Nextcloud CLI and provide credentials to the MCP server.
|
||||
|
||||
**Pros:**
|
||||
- Credentials don't expire
|
||||
- Stable for production use
|
||||
- More control over client configuration
|
||||
|
||||
**Cons:**
|
||||
- Requires manual setup
|
||||
- Needs access to Nextcloud server CLI
|
||||
|
||||
[Jump to Approach B setup →](#approach-b-pre-configured-client)
|
||||
|
||||
---
|
||||
|
||||
## Approach A: Automatic Registration
|
||||
|
||||
### 1. Configure Environment
|
||||
|
||||
Create your `.env` file with only the Nextcloud host:
|
||||
|
||||
```dotenv
|
||||
# .env file
|
||||
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
|
||||
|
||||
# Leave these EMPTY for OAuth mode
|
||||
NEXTCLOUD_USERNAME=
|
||||
NEXTCLOUD_PASSWORD=
|
||||
```
|
||||
|
||||
### 2. Start the MCP Server
|
||||
|
||||
```bash
|
||||
# Load environment variables
|
||||
export $(grep -v '^#' .env | xargs)
|
||||
|
||||
# Start server with OAuth enabled
|
||||
uv run nextcloud-mcp-server --oauth
|
||||
```
|
||||
|
||||
### 3. Verify Registration
|
||||
|
||||
The server will automatically register a new OAuth client. Look for these log messages:
|
||||
|
||||
```
|
||||
INFO OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
|
||||
INFO Configuring MCP server for OAuth mode
|
||||
INFO Performing OIDC discovery: https://your.nextcloud.instance.com/.well-known/openid-configuration
|
||||
INFO OIDC discovery successful
|
||||
INFO Attempting dynamic client registration...
|
||||
INFO Dynamic client registration successful
|
||||
INFO OAuth client ready: <client-id>...
|
||||
INFO Saved OAuth client credentials to .nextcloud_oauth_client.json
|
||||
INFO OAuth initialization complete
|
||||
```
|
||||
|
||||
### 4. Client Credential Storage
|
||||
|
||||
Registered client credentials are saved to `.nextcloud_oauth_client.json` by default. The server will:
|
||||
- Load existing credentials on startup
|
||||
- Check if they've expired
|
||||
- Re-register automatically if expired or missing
|
||||
|
||||
**Note:** Since dynamically registered clients expire (default: 1 hour), the server checks credentials at startup. For long-running deployments, consider using Approach B (pre-configured clients) instead.
|
||||
|
||||
---
|
||||
|
||||
## Approach B: Pre-configured Client
|
||||
|
||||
### 1. Register Client via Nextcloud CLI
|
||||
|
||||
SSH into your Nextcloud server and run:
|
||||
|
||||
```bash
|
||||
# Create OAuth client
|
||||
php occ oidc:create \
|
||||
--name="Nextcloud MCP Server" \
|
||||
--type=confidential \
|
||||
--redirect-uri="http://localhost:8000/oauth/callback"
|
||||
|
||||
# Example output:
|
||||
# Client ID: abc123xyz
|
||||
# Client Secret: secret456def
|
||||
```
|
||||
|
||||
**Note:** Adjust the `--redirect-uri` to match your MCP server URL if different from `http://localhost:8000`.
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
Add the client credentials to your `.env` file:
|
||||
|
||||
```dotenv
|
||||
# .env file
|
||||
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
|
||||
|
||||
# OAuth Client Credentials
|
||||
NEXTCLOUD_OIDC_CLIENT_ID=abc123xyz
|
||||
NEXTCLOUD_OIDC_CLIENT_SECRET=secret456def
|
||||
|
||||
# Optional: Custom OAuth configuration
|
||||
NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
|
||||
NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
|
||||
|
||||
# Leave these EMPTY for OAuth mode
|
||||
NEXTCLOUD_USERNAME=
|
||||
NEXTCLOUD_PASSWORD=
|
||||
```
|
||||
|
||||
See [Configuration Guide](configuration.md#oauth2oidc-configuration) for all available options.
|
||||
|
||||
### 3. Start the MCP Server
|
||||
|
||||
```bash
|
||||
# Load environment variables
|
||||
export $(grep -v '^#' .env | xargs)
|
||||
|
||||
# Start server - it will use pre-configured credentials
|
||||
uv run nextcloud-mcp-server --oauth
|
||||
```
|
||||
|
||||
### 4. Verify Configuration
|
||||
|
||||
Look for these log messages:
|
||||
|
||||
```
|
||||
INFO OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
|
||||
INFO Configuring MCP server for OAuth mode
|
||||
INFO Performing OIDC discovery: https://your.nextcloud.instance.com/.well-known/openid-configuration
|
||||
INFO OIDC discovery successful
|
||||
INFO Using pre-configured OAuth client: abc123xyz
|
||||
INFO OAuth initialization complete
|
||||
```
|
||||
|
||||
**Benefits:** Pre-configured clients don't expire automatically and are more stable for production use.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Test Authentication
|
||||
|
||||
The MCP server is now configured for OAuth. When clients connect:
|
||||
|
||||
1. Client connects to MCP server
|
||||
2. Server provides OAuth authorization URL
|
||||
3. User opens URL in browser and authenticates to Nextcloud
|
||||
4. Nextcloud redirects back with authorization code
|
||||
5. Client exchanges code for access token
|
||||
6. Client uses Bearer token to access MCP server
|
||||
7. All Nextcloud API requests use the user's OAuth token
|
||||
|
||||
### Test with MCP Inspector
|
||||
|
||||
```bash
|
||||
# Start MCP Inspector
|
||||
uv run mcp dev
|
||||
|
||||
# In the browser UI:
|
||||
# 1. Enter your MCP server URL (e.g., http://localhost:8000)
|
||||
# 2. Complete OAuth flow in browser
|
||||
# 3. Test tools and resources
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Running the Server](running.md) - Additional server options
|
||||
- [Configuration](configuration.md) - All environment variables
|
||||
- [Troubleshooting](troubleshooting.md) - Common OAuth issues
|
||||
|
||||
## See Also
|
||||
|
||||
- [Authentication Overview](authentication.md) - OAuth vs BasicAuth comparison
|
||||
- [OAuth Bearer Token Issue](oauth2-bearer-token-session-issue.md) - Required patch for non-OCS endpoints
|
||||
Reference in New Issue
Block a user