Chris Coutinho
164 lines
4.1 KiB
Markdown
164 lines
4.1 KiB
Markdown
# OAuth Quick Start Guide
|
|
|
|
Get up and running with OAuth authentication in 5 minutes.
|
|
|
|
## Prerequisites Checklist
|
|
|
|
Before you begin, ensure you have:
|
|
|
|
- [ ] Nextcloud instance with **administrator access**
|
|
- [ ] Nextcloud version 28 or later
|
|
- [ ] Python 3.11+ installed
|
|
- [ ] `uv` package manager installed ([installation instructions](https://docs.astral.sh/uv/getting-started/installation/))
|
|
|
|
## Step 1: Install Nextcloud Apps
|
|
|
|
Install **both** required apps in your Nextcloud instance:
|
|
|
|
1. Open Nextcloud as administrator
|
|
2. Navigate to **Apps** → **Security**
|
|
3. Install:
|
|
- **OIDC** (OIDC Identity Provider app)
|
|
- **OpenID Connect user backend** (user_oidc app)
|
|
4. Enable both apps
|
|
|
|
> [!IMPORTANT]
|
|
> The `user_oidc` app requires an upstream patch for Bearer token support. See [Upstream Status](oauth-upstream-status.md) for details. The functionality works, but the PR is pending.
|
|
|
|
## Step 2: Configure Nextcloud OIDC
|
|
|
|
Enable dynamic client registration and Bearer token validation:
|
|
|
|
### Via Web UI
|
|
|
|
1. Go to **Settings** → **OIDC** (Administration settings)
|
|
2. Enable **"Allow dynamic client registration"**
|
|
|
|
### Via CLI (Required)
|
|
|
|
SSH into your Nextcloud server and run:
|
|
|
|
```bash
|
|
# Enable Bearer token validation
|
|
php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
|
|
```
|
|
|
|
## Step 3: Install MCP Server
|
|
|
|
Clone and install the MCP server:
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
|
|
cd nextcloud-mcp-server
|
|
|
|
# Install dependencies
|
|
uv sync
|
|
```
|
|
|
|
## Step 4: Configure Environment
|
|
|
|
Create a `.env` file with minimal configuration:
|
|
|
|
```bash
|
|
# Copy sample
|
|
cp env.sample .env
|
|
|
|
# Edit .env and set:
|
|
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
|
|
|
|
# IMPORTANT: Leave these EMPTY for OAuth mode
|
|
NEXTCLOUD_USERNAME=
|
|
NEXTCLOUD_PASSWORD=
|
|
```
|
|
|
|
## Step 5: Start the Server
|
|
|
|
Load environment variables and start the server:
|
|
|
|
```bash
|
|
# Load environment
|
|
export $(grep -v '^#' .env | xargs)
|
|
|
|
# Start server with OAuth
|
|
uv run nextcloud-mcp-server --oauth
|
|
```
|
|
|
|
Look for this success message:
|
|
|
|
```
|
|
✓ PKCE support validated: ['S256']
|
|
INFO OAuth initialization complete
|
|
INFO MCP server ready at http://127.0.0.1:8000
|
|
```
|
|
|
|
## Step 6: Test with MCP Inspector
|
|
|
|
Open a new terminal and test the connection:
|
|
|
|
```bash
|
|
# Start MCP Inspector
|
|
uv run mcp dev
|
|
```
|
|
|
|
This opens your browser. In the MCP Inspector UI:
|
|
|
|
1. Enter server URL: `http://127.0.0.1:8000/mcp`
|
|
2. Click **Connect**
|
|
3. Complete the OAuth flow in the browser popup
|
|
4. After authorization, you'll see available tools and resources
|
|
|
|
Test a tool by trying:
|
|
- **Tool**: `nc_notes_create_note`
|
|
- **Title**: "Test Note"
|
|
- **Content**: "Hello from MCP!"
|
|
- **Category**: "Notes"
|
|
|
|
## Troubleshooting Quick Fixes
|
|
|
|
### PKCE Error
|
|
|
|
If you see:
|
|
```
|
|
ERROR: OIDC CONFIGURATION ERROR - Missing PKCE Support Advertisement
|
|
```
|
|
|
|
**Fix**: The Nextcloud OIDC app needs to be updated to advertise PKCE support. See [Upstream Status](oauth-upstream-status.md) for the required PR.
|
|
|
|
### 401 Unauthorized for Notes API
|
|
|
|
If OAuth works but Notes API returns 401:
|
|
|
|
**Fix**: The `user_oidc` app needs the Bearer token patch. See [Upstream Status](oauth-upstream-status.md) for details.
|
|
|
|
### Can't Reach OIDC Discovery Endpoint
|
|
|
|
**Fix**: Verify your Nextcloud URL is correct and accessible:
|
|
|
|
```bash
|
|
curl https://your.nextcloud.instance.com/.well-known/openid-configuration
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- [OAuth Setup Guide](oauth-setup.md) - Detailed configuration options
|
|
- [OAuth Architecture](oauth-architecture.md) - How it works under the hood
|
|
- [OAuth Troubleshooting](oauth-troubleshooting.md) - Common issues and solutions
|
|
- [Configuration](configuration.md) - All environment variables
|
|
|
|
## Development vs Production
|
|
|
|
This quick start uses **automatic client registration** which is perfect for:
|
|
- Development
|
|
- Testing
|
|
- Quick deployments
|
|
|
|
For **production deployments**, consider:
|
|
1. Pre-registering OAuth client manually
|
|
2. Using dedicated client credentials that don't expire
|
|
3. See [OAuth Setup Guide](oauth-setup.md) for production configuration
|
|
|
|
---
|
|
|
|
**Need help?** Check [OAuth Troubleshooting](oauth-troubleshooting.md) or [open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues).
|