mcp-nextcloud/docs/login-flow-v2.md

Login Flow v2 (Multi-User Mode)

This is the recommended multi-user deployment mode for the Nextcloud MCP Server. It works with stock Nextcloud 16+ (no upstream patches) and is the mode used by hosted offerings like Astrolabe Cloud.

For the design rationale, see ADR-022. For other deployment modes, see Authentication.

How It Works

Two authentication legs, each with a different mechanism:

┌─────────────────┐    OAuth/OIDC    ┌──────────────────┐   App password    ┌─────────────────┐
│   MCP Client    │ ───────────────> │   MCP Server     │ ────────────────> │   Nextcloud     │
│ (Claude, etc.)  │   (mcp:* scopes) │  (OIDC RP of IdP,│   (Basic Auth)    │   (NC 16+)      │
│                 │                  │  OAuth facade,   │                   │                 │
│                 │                  │  app-pwd holder) │                   │                 │
└─────────────────┘                  └──────────────────┘                   └─────────────────┘
                                              ▲
                                              │ OIDC discovery + token validation
                                              ▼
                                     ┌─────────────────┐
                                     │ OIDC Provider   │
                                     │ (Nextcloud OIDC,│
                                     │  Keycloak,      │
                                     │  AWS Cognito,…) │
                                     └─────────────────┘

• MCP client → MCP server: OAuth 2.1 with PKCE. The MCP server is not a standalone OAuth issuer — it acts as an OIDC relying party of a configurable identity provider and exposes an OAuth facade in front of it. The IdP is selected by OIDC_DISCOVERY_URL (defaults to Nextcloud's built-in OIDC); Keycloak, AWS Cognito, and other OIDC-compliant IdPs are also supported. Tokens are signed by that IdP, validated by the MCP server against the IdP's JWKS, and carry mcp:* scopes that gate which tools the user can call.
• MCP server → IdP (auth leg): The MCP server registers itself with the IdP via static NEXTCLOUD_OIDC_CLIENT_ID/SECRET (preferred — these are generic OIDC client credentials despite the Nextcloud-flavored naming, and work with any OIDC provider) or RFC 7591 DCR (fallback). This relationship is used for OIDC discovery, JWKS retrieval, and token validation.
• MCP server → Nextcloud (data leg): Per-user app password obtained via Nextcloud's native Login Flow v2. Sent as HTTP Basic Auth. Login Flow v2 is always Nextcloud's protocol regardless of which IdP authenticated the MCP client.

App passwords appear in Settings → Security → Devices & Sessions in Nextcloud and can be revoked by the user at any time.

Why not forward OAuth bearer tokens to Nextcloud?

Earlier deployment modes forwarded the client's OAuth bearer token directly to Nextcloud APIs. That required upstream patches to user_oidc (Bearer-token validation on non-OCS endpoints) which were never merged. Nextcloud also doesn't enforce OAuth scopes on its app APIs even when Bearer tokens are accepted, so the security guarantees were weaker than they appeared. App passwords are the simplest mechanism that works on every supported Nextcloud version and surfaces user-revocable credentials in the standard UI.

Scope enforcement happens at the MCP server layer (defense-in-depth). See Scope Enforcement below.

Setup

Required Environment Variables

# Nextcloud connection (data leg — always Nextcloud, regardless of which IdP authenticates clients)
NEXTCLOUD_HOST=https://your.nextcloud.example.com

# IdP selection (auth leg). Defaults to NEXTCLOUD_HOST/.well-known/openid-configuration
# (i.e. Nextcloud's built-in OIDC). Override to point at Keycloak, AWS Cognito, etc.
# OIDC_DISCOVERY_URL=https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration

# OIDC client credentials for the MCP server's relying-party relationship with the IdP.
# These are generic OIDC client credentials — they work with any OIDC provider, despite
# the Nextcloud-flavored env-var names. Preferred path: register a client in your IdP
# (Nextcloud admin → OIDC, Keycloak realm → Clients, etc.) and set these. If both are
# unset and the IdP advertises a `registration_endpoint`, the server falls back to RFC 7591 DCR.
NEXTCLOUD_OIDC_CLIENT_ID=<your-client-id>
NEXTCLOUD_OIDC_CLIENT_SECRET=<your-client-secret>

# Enable Login Flow v2 (per-user Nextcloud app-password provisioning for the data leg)
ENABLE_LOGIN_FLOW=true

# App-password storage (required for persistence across restarts)
TOKEN_STORAGE_DB=/app/data/tokens.db
TOKEN_ENCRYPTION_KEY=<fernet-key>          # see "Generating an encryption key" below

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

When using an external IdP (Keycloak, Cognito, etc.), see Keycloak Multi-Client Token Validation for how Nextcloud's user_oidc app handles realm-level token validation if you also federate Nextcloud's own login through the same IdP.

Generating an Encryption Key

App passwords are stored encrypted with Fernet. Generate a key once and reuse it:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Lose the key and stored app passwords become unrecoverable — users will need to re-provision.

Docker Compose

The repo ships with a working reference under the login-flow profile:

docker compose --profile login-flow up -d
# Server listens on http://localhost:8004

Excerpt from docker-compose.yml:

mcp-login-flow:
  build: .
  command: ["--transport", "streamable-http", "--oauth", "--port", "8004"]
  ports:
    - 127.0.0.1:8004:8004
  environment:
    - NEXTCLOUD_HOST=http://app:80
    - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8004
    - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
    - ENABLE_LOGIN_FLOW=true
    - TOKEN_ENCRYPTION_KEY=<your-fernet-key>
    - TOKEN_STORAGE_DB=/app/data/tokens.db
  volumes:
    - login-flow-data:/app/data
    - login-flow-oauth-storage:/app/.oauth

The --oauth flag enables the OAuth/OIDC identity layer that Login Flow v2 builds on (user identity via OAuth session, Nextcloud access via app passwords).

Per-User Provisioning Flow

Each user goes through provisioning once, the first time they connect. Subsequent requests reuse the stored app password.

┌─────────────┐                  ┌──────────────────┐                  ┌─────────────────┐
│ MCP Client  │                  │   MCP Server     │                  │    Nextcloud    │
└──────┬──────┘                  └────────┬─────────┘                  └────────┬────────┘
       │  1. OAuth PKCE                   │                                     │
       ├─────────────────────────────────>│                                     │
       │  ← access token (mcp:* scopes)   │                                     │
       │                                  │                                     │
       │  2. MCP request                  │                                     │
       ├─────────────────────────────────>│                                     │
       │                                  │                                     │
       │  3. No stored app password →     │                                     │
       │     elicit URL or 401            │                                     │
       │<─────────────────────────────────┤                                     │
       │  "Visit <login-url> to grant     │                                     │
       │   access"                        │                                     │
       │                                  │  4. POST /index.php/login/v2        │
       │                                  ├────────────────────────────────────>│
       │                                  │  ← {login_url, poll_endpoint, token}│
       │                                  │                                     │
       │  5. User opens login_url in browser, authenticates, clicks "Grant"     │
       │  ────────────────────────────────────────────────────────────────────> │
       │                                  │                                     │
       │                                  │  6. Poll endpoint (background)      │
       │                                  ├────────────────────────────────────>│
       │                                  │  ← {loginName, appPassword}         │
       │                                  │                                     │
       │                                  │  7. Encrypt + store in SQLite       │
       │                                  │                                     │
       │  8. Retry MCP request            │                                     │
       ├─────────────────────────────────>│                                     │
       │                                  │  9. GET /apps/notes/...             │
       │                                  ├────────────────────────────────────>│
       │                                  │  Authorization: Basic <app-pwd>     │
       │                                  │  ← response                         │
       │  10. ← result                    │                                     │

Provisioning Endpoints

The server exposes browser endpoints for management UIs (Astrolabe, custom dashboards):

Endpoint	Purpose
GET /app/provision?redirect_uri=…	Start Login Flow v2 and redirect to Nextcloud's grant page
GET /app/provision/status?id=…	Check whether the background poll has completed

Both require a valid OAuth bearer token in the Authorization header (the user's identity is taken from the token, not from a query parameter).

Implementation: nextcloud_mcp_server/auth/provision_routes.py.

Provisioning via MCP Tools (Elicitation)

For MCP clients, the same flow is exposed as tools (nc_auth_provision_access, nc_auth_check_status). Clients that support URL elicitation (MCP spec 2025-11-25) get a clickable link automatically; clients without that capability fall back to a copy-paste URL in an error message. See ADR-022 §"MCP Elicitation for Login Flow v2" for the full capability matrix.

Scope Enforcement

Nextcloud's app passwords have no native scope support — they grant the user's full API access. The MCP server enforces scopes at the application layer.

Scope Reference

Scope	Operations	Tool count
mcp:notes.read	Read access (get, list, search) across all Nextcloud apps	~36 tools
mcp:notes.write	Write access (create, update, delete) across all Nextcloud apps	~54 tools

The historical notes.read / notes.write naming covers all Nextcloud apps, not just the Notes app — it's a project-wide read/write distinction.

Standard OIDC scopes (openid, profile, email) are also supported and have no effect on tool access.

How Scopes Are Enforced

Each MCP tool is decorated with @require_scopes(...):

@mcp.tool()
@require_scopes("mcp:notes.read")
async def nc_notes_get_note(note_id: int, ctx: Context):
    ...

When a client calls list_tools, the server returns only tools the user has granted scopes for (dynamic tool filtering). When a client calls a tool whose scope is missing, the server returns:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                  scope="mcp:notes.write",
                  resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"

Clients can use this header to trigger step-up authorization — re-running the OAuth flow with additional scopes.

Implementation: nextcloud_mcp_server/auth/scope_authorization.py.

OAuth Endpoints

When --oauth is enabled, the MCP server exposes OAuth 2.1 endpoints. These endpoints front the configured IdP — discovery metadata, token issuance, and JWKS still come from whichever provider is selected via OIDC_DISCOVERY_URL (Nextcloud OIDC by default, or Keycloak / Cognito / etc.); the MCP server is not a standalone OAuth issuer.

Endpoint	RFC	Purpose
GET /.well-known/oauth-authorization-server	RFC 8414	Server metadata (advertises the configured IdP as the upstream issuer)
GET /.well-known/oauth-protected-resource/mcp	RFC 9728	PRM — advertises supported scopes (dynamically discovered from @require_scopes)
POST /register	RFC 7591	Dynamic Client Registration (for MCP clients; see also NEXTCLOUD_OIDC_CLIENT_ID/SECRET for the MCP server's own RP credentials with the IdP)
PUT/DELETE /register/{client_id}	RFC 7592	Client management with registration token
GET /authorize	RFC 6749	Authorization endpoint (PKCE required, S256)
POST /token	RFC 6749	Token endpoint

Implementation: nextcloud_mcp_server/auth/oauth_routes.py, nextcloud_mcp_server/auth/client_registration.py.

PKCE with S256 is mandatory — required by the MCP specification and enforced at the authorization endpoint.

Token Format

The MCP server can issue or accept either JWT or opaque access tokens depending on configuration.

	JWT (recommended)	Opaque
Validation	Signature check via JWKS (local, fast)	Introspection HTTP call
Scope claim	Embedded in scope claim	Returned by introspection endpoint
Size	~800-1200 chars	~72 chars
Standard	RFC 9068	RFC 7662

JWTs are preferred for production because validation is local and stateless. Opaque tokens are useful when you need server-side revocation without JWT blocklist infrastructure.

Troubleshooting

"Provisioning loop" — user keeps being asked to authorize

Check that TOKEN_STORAGE_DB is on a persistent volume. The default (/tmp or per-process tempfile) is wiped on container restart, so each restart loses every stored app password.

"Failed to start login flow" / 502 from /app/provision

The MCP server cannot reach Nextcloud at NEXTCLOUD_HOST. Verify network connectivity and that NEXTCLOUD_HOST uses an address reachable from the server (not the user's browser). For Docker Compose deployments, this is typically the internal service hostname (e.g. http://app:80).

"Login URL points to localhost in browser"

NEXTCLOUD_PUBLIC_ISSUER_URL is missing or wrong. Set it to the public URL of Nextcloud as the user's browser sees it. The server rewrites the login URL's origin from the internal NEXTCLOUD_HOST to NEXTCLOUD_PUBLIC_ISSUER_URL before redirecting the browser.

Stored app password rejected by Nextcloud (401)

The user revoked it from Settings → Security → Devices & Sessions. Delete the row from the storage DB (or call nc_auth_provision_access again) to trigger a fresh Login Flow.

cryptography.fernet.InvalidToken on startup

TOKEN_ENCRYPTION_KEY changed since the DB was created — stored app passwords cannot be decrypted with a different key. Either restore the original key or wipe the DB and have users re-provision.

Multiple worker processes

The provisioning session store is in-memory; ENABLE_LOGIN_FLOW=true assumes a single worker. Running with uvicorn --workers N will cause provisioning sessions to randomly fail. For higher concurrency, scale horizontally (multiple containers behind a sticky-session load balancer) rather than within a single process.

Sticky-session keying: route on the user's OAuth bearer token (or a session cookie tied to the user) — not on source IP. MCP clients may not maintain stable IPs between the request that initiates provisioning and the polling request that completes it, so IP-based affinity will silently break the flow. A stable per-user identifier from the Authorization header is the right key.

See Also

• ADR-022: Deployment Mode Consolidation — design rationale
• Authentication — overview of all deployment modes
• Authentication Flows — sequence diagrams per mode
• Configuration — full environment variable reference
• Nextcloud Login Flow v2 spec