admin/mcp-nextcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
df4994e8605feca0116c54ca9709c0a8b51cd27f
mcp-nextcloud/docs/auth-flows.md
T
Chris CoutinhoandClaude Opus 4.7 df4994e860 refactor(config)!: derive enable_login_flow from mode, remove ENABLE_LOGIN_FLOW env var 
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>
2026-05-12 19:45:50 +02:00

13 KiB
Raw Blame History

Authentication Flows by Deployment Mode

This document provides a unified reference for the auth flows in each supported deployment mode. For configuration details, see Authentication. For Login Flow v2 architecture and setup, see Login Flow v2.

Quick Reference Matrix

Mode Client → MCP → NC Background Sync Astrolabe (hosted UI) → MCP
Single-User BasicAuth Embedded credentials Same credentials N/A
Multi-User BasicAuth Header pass-through Stored app password (optional) OAuth Bearer token
Login Flow v2 OAuth → MCP, app pwd → NC Stored app password OAuth Bearer token

Communication Patterns

This document covers three distinct communication patterns:

  1. MCP Client → MCP Server → Nextcloud: Interactive tool calls initiated by users through MCP clients (Claude Desktop, claude.ai, custom clients).
  2. MCP Server → Nextcloud: Background operations like vector sync that run without user interaction.
  3. Astrolabe → MCP Server: Astrolabe app backend communication for settings UI and unified search.

Deployment Modes

1. Single-User BasicAuth

Use Case: Personal Nextcloud instance, local development, single-user deployments.

MCP Client → MCP Server → Nextcloud

MCP Client                    MCP Server                   Nextcloud
    │                             │                            │
    │── MCP Request ─────────────▶│                            │
    │   (no auth required)        │                            │
    │                             │── HTTP + BasicAuth ───────▶│
    │                             │   Authorization: Basic     │
    │                             │   (embedded credentials)   │
    │                             │◀── API Response ───────────│
    │◀── Tool Result ─────────────│                            │

Key characteristics:

  • Credentials embedded in server configuration (NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD)
  • Single shared NextcloudClient created at startup
  • No MCP-level authentication required (server trusts local clients)
  • All requests use the same Nextcloud user

Implementation: context.py — returns the shared client from lifespan context

Background Sync

Uses the same embedded credentials as interactive requests. The background job accesses Nextcloud with the configured username/password.

Astrolabe Integration

Not applicable — Astrolabe is only used in multi-user deployments where users need personal settings and per-user state.

2. Multi-User BasicAuth

Use Case: Internal deployment where users provide their own Nextcloud credentials via HTTP headers.

MCP Client → MCP Server → Nextcloud

MCP Client                    MCP Server                   Nextcloud
    │                             │                            │
    │── MCP Request ─────────────▶│                            │
    │   Authorization: Basic      │                            │
    │   (user credentials)        │                            │
    │                             │── BasicAuthMiddleware ────▶│
    │                             │   Extracts credentials     │
    │                             │                            │
    │                             │── HTTP + BasicAuth ───────▶│
    │                             │   (pass-through)           │
    │                             │◀── API Response ───────────│
    │◀── Tool Result ─────────────│                            │

Key characteristics:

  • BasicAuthMiddleware extracts credentials from the Authorization: Basic header
  • Credentials passed through to Nextcloud (not stored)
  • Client created per-request from extracted credentials
  • Stateless — no credential storage between requests

Background Sync (Optional)

If users provision an app password (via Astrolabe or nc_auth_provision_access), the server can run background jobs on their behalf:

Astrolabe                     MCP Server                   Nextcloud
    │                             │                            │
    │── Store app password ──────▶│                            │
    │   (via management API)      │                            │
    │                             │ [Encrypt + persist locally]│
    │                             │  (SQLite, Fernet)          │
    │◀── Confirmation ────────────│                            │
    │                             │                            │
    │         [Background job]    │                            │
    │                             │── Retrieve app password ──▶│
    │                             │── HTTP + BasicAuth ───────▶│
    │                             │◀── API Response ───────────│

Requirements: TOKEN_ENCRYPTION_KEY, TOKEN_STORAGE_DB.

Astrolabe → MCP Server

Astrolabe                     MCP Server                   OIDC Provider
    │                             │                            │
    │── OAuth Flow ──────────────▶│◀── Token from IdP ────────▶│
    │   (user initiates)          │                            │
    │                             │                            │
    │── Bearer Token ────────────▶│                            │
    │   (management API calls)    │                            │
    │                             │── Validate via JWKS ──────▶│
    │                             │   (or introspection)       │
    │◀── API Response ────────────│                            │

Key characteristics:

  • Astrolabe has its own OAuth client registered with the IdP (Nextcloud OIDC by default; Keycloak / Cognito / etc. when configured via OIDC_DISCOVERY_URL)
  • Tokens are validated by the MCP server using the IdP's JWKS (Nextcloud OIDC's JWKS by default; whichever IdP is configured otherwise)
  • Authorization check: token.sub == requested_resource_owner
  • The same JWKS-based validation path applies under Login Flow v2 — the MCP server is an OIDC relying party of the configured IdP in both modes; Login Flow v2 only changes the MCP→Nextcloud credential leg (per-user app passwords).

3. Login Flow v2

Use Case: Hosted multi-user deployments, OAuth-based MCP clients (claude.ai, Astrolabe Cloud), production. Recommended for any setup where MCP clients shouldn't handle Nextcloud credentials directly.

This mode replaces the previously-supported "OAuth Single-Audience" and "OAuth Token Exchange" modes, both of which required upstream Nextcloud patches that were never merged. See ADR-022 for the rationale.

MCP Client → MCP Server → Nextcloud (steady state)

MCP Client                    MCP Server                   Nextcloud
    │                             │                            │
    │── Bearer Token ────────────▶│                            │
    │   (issued by configured IdP,│                            │
    │    per-app scopes)          │                            │
    │                             │── Validate scopes ─────────│
    │                             │   (@require_scopes)        │
    │                             │                            │
    │                             │── Lookup user's            │
    │                             │   stored app password      │
    │                             │                            │
    │                             │── HTTP + BasicAuth ───────▶│
    │                             │   Authorization: Basic     │
    │                             │   (per-user app password)  │
    │                             │◀── API Response ───────────│
    │◀── Tool Result ─────────────│                            │

Key characteristics:

  • MCP client authenticates to MCP server via OAuth 2.1 + PKCE
  • MCP server is an OIDC relying party of a configurable IdP (Nextcloud OIDC by default; Keycloak, AWS Cognito, etc. via OIDC_DISCOVERY_URL) + an OAuth facade for MCP clients. RFC 7591 DCR is used to register the MCP-client side; the server's own RP credentials come from NEXTCLOUD_OIDC_CLIENT_ID/SECRET (generic OIDC creds), with DCR fallback. Tokens are signed by the chosen IdP and validated against that IdP's JWKS.
  • Per-app scopes (e.g. notes.read, talk.read, files.write) gate tool access — see Login Flow v2 → Scope Reference for the full list
  • Per-user app password obtained via Login Flow v2 (Nextcloud-specific protocol, used regardless of which IdP authenticated the client) and stored encrypted in SQLite
  • App passwords appear in Nextcloud's Settings → Security → Devices & Sessions and are user-revocable

First-Use Provisioning (one-time per user)

MCP Client                    MCP Server                   Nextcloud
    │                             │                            │
    │── Bearer Token + request ──▶│                            │
    │                             │   No stored app password   │
    │                             │                            │
    │◀── Elicit URL or 401 ───────│                            │
    │   "Visit <login-url>"       │                            │
    │                             │── POST /index.php/login/v2▶│
    │                             │◀── login_url, poll_token ──│
    │                             │                            │
    │   User opens login_url in browser, authenticates, "Grant"│
    │   ──────────────────────────────────────────────────────▶│
    │                             │                            │
    │                             │── Poll endpoint (bg) ─────▶│
    │                             │◀── loginName, appPassword ─│
    │                             │                            │
    │                             │── Encrypt + store          │
    │                             │   in tokens.db             │
    │                             │                            │
    │── Retry request ───────────▶│── Basic Auth as above ────▶│

Background Sync

Uses the same per-user app password retrieved from encrypted storage. No token refresh needed — Nextcloud app passwords don't expire (until the user revokes them).

                              MCP Server                   Nextcloud
                                  │                            │
    [Background job starts]       │                            │
                                  │── Retrieve app password ──▶│
                                  │   (per user, from SQLite)  │
                                  │                            │
                                  │── HTTP + BasicAuth ───────▶│
                                  │◀── API Response ───────────│

Astrolabe → MCP Server

Same as Multi-User BasicAuth — see Astrolabe → MCP Server above.

Configuration Quick Reference

Single-User BasicAuth

NEXTCLOUD_HOST=https://nextcloud.example.com
NEXTCLOUD_USERNAME=admin
NEXTCLOUD_PASSWORD=<app-password>

Multi-User BasicAuth

NEXTCLOUD_HOST=https://nextcloud.example.com
ENABLE_MULTI_USER_BASIC_AUTH=true

# Optional: app-password storage for background sync
TOKEN_ENCRYPTION_KEY=<fernet-key>
TOKEN_STORAGE_DB=/app/data/tokens.db

Login Flow v2

NEXTCLOUD_HOST=https://nextcloud.example.com
MCP_DEPLOYMENT_MODE=login_flow

# Required for app-password storage
TOKEN_ENCRYPTION_KEY=<fernet-key>
TOKEN_STORAGE_DB=/app/data/tokens.db

# Public URLs (for browser redirects)
NEXTCLOUD_MCP_SERVER_URL=https://mcp.example.com
NEXTCLOUD_PUBLIC_ISSUER_URL=https://nextcloud.example.com

See Login Flow v2 for full setup, scope reference, and troubleshooting.

Related Documentation

Reference in New Issue View Git Blame Copy Permalink