Chris CoutinhoandClaude Opus 4.7
df4994e860
Once OAUTH_SINGLE_AUDIENCE was renamed to LOGIN_FLOW and the validation
gate ensured the only meaningful configuration was
`MCP_DEPLOYMENT_MODE=login_flow + ENABLE_LOGIN_FLOW=true`, the two
controls became redundant. Setting the mode is sufficient; the
ENABLE_LOGIN_FLOW env var doesn't add information.
This commit makes the deployment mode the single source of truth for
the Login Flow v2 toggle:
- `nextcloud_mcp_server/config.py`: drop the `ENABLE_LOGIN_FLOW`
dynaconf env-var alias. The `enable_login_flow` field stays as an
internal attribute so the 6 runtime call sites (app.py x4,
context.py, auth/scope_authorization.py) keep working unchanged.
Updated field docstring to flag it as derived.
- `nextcloud_mcp_server/config_validators.py`:
- Drop `enable_login_flow` from `MODE_REQUIREMENTS[LOGIN_FLOW].required`.
- Drop the validation gate that required ENABLE_LOGIN_FLOW=true for
LOGIN_FLOW mode (no longer possible to misconfigure — the flag is
derived, not user input).
- Add `_sync_derived_flags()` helper called at every return path of
`detect_auth_mode` to set `settings.enable_login_flow` from the
resolved mode.
- `tests/unit/test_config_validators.py`: drop `enable_login_flow=True`
from happy-path fixtures (no longer needed — detection sets it).
Repurpose `test_login_flow_requires_enable_login_flow_flag` into
`test_login_flow_mode_auto_derives_enable_login_flow_flag` which
asserts the new auto-derivation behaviour for both LOGIN_FLOW and a
non-LOGIN_FLOW mode.
- `docker-compose.yml`: remove `ENABLE_LOGIN_FLOW=true` from the
`mcp-login-flow` and `mcp-keycloak` profiles.
- `env.sample`: remove the ENABLE_LOGIN_FLOW reference; the comment
on `MCP_DEPLOYMENT_MODE` now notes the derived flag.
- `docs/configuration.md`, `docs/authentication.md`,
`docs/login-flow-v2.md`, `docs/auth-flows.md`,
`docs/troubleshooting.md`, `docs/ADR-025-*.md`: replace
ENABLE_LOGIN_FLOW=true examples and references with
MCP_DEPLOYMENT_MODE=login_flow.
BREAKING CHANGE: `ENABLE_LOGIN_FLOW` is no longer read from the
environment. Anyone who relied on `ENABLE_LOGIN_FLOW=true` to activate
Login Flow v2 should set `MCP_DEPLOYMENT_MODE=login_flow` instead (or
rely on it being the default when no other auth env vars are set).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
98 lines
4.5 KiB
Markdown
98 lines
4.5 KiB
Markdown
# Authentication
|
|
|
|
The Nextcloud MCP server authenticates to Nextcloud using **app-specific passwords** (HTTP Basic Auth). It supports three deployment modes that differ in how those credentials are sourced.
|
|
|
|
## Mode Comparison
|
|
|
|
| Mode | How credentials are obtained | Best for |
|
|
|------|------------------------------|----------|
|
|
| **Single-User (BasicAuth)** | App password in environment variables | Personal use, development, single-tenant deployments |
|
|
| **Multi-User (BasicAuth pass-through)** | MCP client sends credentials in HTTP `Authorization` header | Internal multi-user setups where users manage their own Nextcloud credentials |
|
|
| **Multi-User (Login Flow v2)** | Per-user app password obtained via Nextcloud's [Login Flow v2](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/LoginFlow/index.html#login-flow-v2), stored encrypted | Hosted deployments, OAuth-based MCP clients (claude.ai, Astrolabe Cloud), production multi-user |
|
|
|
|
> **OAuth-direct-to-Nextcloud is no longer supported.** It required upstream patches to `user_oidc` that were never merged. Login Flow v2 replaces it for multi-user deployments and works with stock Nextcloud 16+. See [ADR-022](ADR-022-deployment-mode-consolidation.md) for the rationale.
|
|
|
|
## Single-User (BasicAuth)
|
|
|
|
One set of credentials is configured in the environment and shared by all MCP clients. All Nextcloud requests are made as the same user.
|
|
|
|
### Configuration
|
|
|
|
```bash
|
|
NEXTCLOUD_HOST=https://your.nextcloud.example.com
|
|
NEXTCLOUD_USERNAME=your_username
|
|
NEXTCLOUD_PASSWORD=your_app_password
|
|
```
|
|
|
|
Generate the app password in Nextcloud under **Settings → Security → Devices & sessions**. Don't use your login password.
|
|
|
|
### Trade-offs
|
|
|
|
- ✅ Simplest setup; no persistent state
|
|
- ✅ All MCP tools available (no scope enforcement — trusted environment)
|
|
- ❌ No per-user identity; all actions appear from the same account in Nextcloud
|
|
- ❌ Not suitable for shared deployments
|
|
|
|
See [Configuration](configuration.md) for the full environment variable reference.
|
|
|
|
## Multi-User (BasicAuth Pass-Through)
|
|
|
|
Each MCP client sends its own credentials in an HTTP `Authorization: Basic` header. The server creates a per-request Nextcloud client from those credentials and never persists them.
|
|
|
|
### Configuration
|
|
|
|
```bash
|
|
NEXTCLOUD_HOST=https://your.nextcloud.example.com
|
|
ENABLE_MULTI_USER_BASIC_AUTH=true
|
|
```
|
|
|
|
`NEXTCLOUD_USERNAME` and `NEXTCLOUD_PASSWORD` must NOT be set in this mode.
|
|
|
|
### Trade-offs
|
|
|
|
- ✅ Stateless — no token storage required
|
|
- ✅ Each user's actions are properly attributed in Nextcloud audit logs
|
|
- ❌ Clients must handle Nextcloud credentials directly (credential exposure risk)
|
|
- ❌ Not compatible with OAuth-based MCP clients (claude.ai, Astrolabe Cloud) without a credential bridge
|
|
|
|
## Multi-User (Login Flow v2)
|
|
|
|
The recommended mode for hosted and OAuth-based deployments. MCP clients authenticate to the MCP server via OAuth; the MCP server obtains a per-user app password from Nextcloud (via Login Flow v2) and uses HTTP Basic Auth to talk to Nextcloud APIs.
|
|
|
|
```
|
|
MCP Client ──(OAuth, per-app scopes)──> MCP Server ──(Basic Auth, app password)──> Nextcloud
|
|
```
|
|
|
|
The MCP server enforces per-app scopes (`notes.read`, `talk.write`, `files.read`, etc. — see [Login Flow v2 → Scope Reference](login-flow-v2.md#scope-reference)) at the application layer (defense-in-depth, since Nextcloud app passwords have no native scope support).
|
|
|
|
**See [Login Flow v2](login-flow-v2.md) for full setup, architecture, scope reference, and troubleshooting.**
|
|
|
|
## Mode Detection
|
|
|
|
The server detects the active mode from environment variables at startup:
|
|
|
|
| Env vars present | Detected mode |
|
|
|------------------|---------------|
|
|
| `NEXTCLOUD_USERNAME` + `NEXTCLOUD_PASSWORD` | Single-User (BasicAuth) |
|
|
| `ENABLE_MULTI_USER_BASIC_AUTH=true` (no creds) | Multi-User (BasicAuth pass-through) |
|
|
| `MCP_DEPLOYMENT_MODE=login_flow` or no auth env vars set | Multi-User (Login Flow v2) |
|
|
|
|
You can also force a mode via CLI flag:
|
|
|
|
```bash
|
|
# Force Login Flow v2 / OAuth identity layer
|
|
uv run nextcloud-mcp-server --oauth
|
|
|
|
# Force BasicAuth
|
|
uv run nextcloud-mcp-server --no-oauth
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [Login Flow v2](login-flow-v2.md) — multi-user setup details
|
|
- [Configuration](configuration.md) — environment variable reference
|
|
- [Authentication Flows](auth-flows.md) — sequence diagrams per mode
|
|
- [Running the Server](running.md) — start, manage, troubleshoot
|
|
- [Troubleshooting](troubleshooting.md) — common issues
|
|
- [ADR-022](ADR-022-deployment-mode-consolidation.md) — design rationale for mode consolidation
|