ADR-004: Federated Authentication Architecture for Offline Access

Status: Draft Date: 2025-11-02 Supersedes: ADR-002

Context

ADR-002 attempted to solve the problem of background workers accessing user data by proposing token exchange patterns. However, it fundamentally misunderstood the MCP protocol's authentication architecture and OAuth delegation patterns.

The real challenge is that:

The MCP server needs to access Nextcloud APIs on behalf of users
Background workers need to operate when users are offline
We need proper OAuth compliance with user consent
Modern enterprise environments use federated identity providers

The solution is a Federated Authentication Architecture where both the MCP server and Nextcloud trust the same Identity Provider (IdP).

Problem Statement

We need a way for:

Users to authenticate once to a central identity provider
The MCP server to obtain delegated access to Nextcloud resources
Background workers to access user data using stored refresh tokens
Clean separation between identity management and resource access

The core issue: How can the MCP server obtain refresh tokens from a shared IdP to access Nextcloud on behalf of users?

Decision

We will implement a Federated Authentication Architecture using a Shared Identity Provider where:

Shared IdP: A central identity provider (e.g., Keycloak, Okta, Azure AD) manages user authentication
MCP Server as OAuth Client: The MCP server registers with the shared IdP to request tokens
Nextcloud as Resource Server: Nextcloud validates tokens issued by the shared IdP
On-Behalf-Of Flow: The MCP server requests tokens scoped for Nextcloud access

The MCP server will:

Act as an OAuth client to the shared IdP
Request tokens on behalf of users, scoped for Nextcloud API access
Store refresh tokens securely with rotation
Use stored tokens for both MCP sessions and background operations

Architecture

Progressive Consent Architecture with Dual OAuth Flows

The MCP server implements progressive consent - separate authorization flows for client authentication and resource access. This architecture uses two distinct, sequential OAuth flows:

The Core Principle

Three separate OAuth clients are registered at the Identity Provider (IdP):

MCP Client (e.g., client_id="claude-desktop") - The native application
MCP Server (e.g., client_id="mcp-server") - The intermediary server
Nextcloud (e.g., client_id="nextcloud") - The resource server

CRITICAL: Each flow uses a DIFFERENT client_id for proper OAuth delegation.

Flow 1: Client Authentication (Always Required)

The MCP client authenticates itself to the MCP server using its own OAuth credentials:

Initiator: MCP Client
Client ID: claude-desktop (the MCP client's own ID)
Scopes: openid profile mcp-server:api
Flow: Standard PKCE OAuth 2.0
User Consent: "Allow Claude Desktop to access MCP Server?"
Result: Access token with aud: "mcp-server"
Server State: STATELESS - server just validates tokens, has no Nextcloud access

At this point:

✅ MCP client can authenticate to MCP server
❌ MCP server CANNOT access Nextcloud APIs
❌ No refresh tokens stored anywhere

Flow 2: Resource Provisioning (Triggered Explicitly)

When the user attempts to use a Nextcloud tool, the server initiates a second OAuth flow to obtain delegated access:

Trigger: User calls a Nextcloud tool (e.g., list_notes) and server has no refresh token
Server Response: Error message directing user to call provision_nextcloud_access tool
Initiator: MCP Server (on user's explicit request)
Client ID: mcp-server (the SERVER's own ID)
Scopes: openid offline_access nextcloud:api nextcloud:notes:* nextcloud:calendar:*
Flow: Standard OAuth 2.0 authorization code flow
User Consent: "Allow MCP Server to access Nextcloud offline on your behalf?"
Result: Refresh token with aud: "nextcloud"
Server State: STATEFUL - server stores encrypted refresh token

After provisioning:

✅ MCP client still authenticates with aud: "mcp-server" tokens
✅ MCP server can now access Nextcloud APIs using stored refresh token
✅ Background workers can operate offline

Token Types and Lifecycles

MCP Access Tokens (audience: "mcp-server")
- Issued to MCP client in Flow 1
- Authenticates MCP client to MCP server
- Short-lived (1 hour)
- Cannot access Nextcloud directly
- MCP client sends with every request
Nextcloud Access Tokens (audience: "nextcloud")
- Obtained by MCP server using stored refresh token
- Used for Nextcloud API access
- Never exposed to MCP clients
- Short-lived (5-15 minutes), cached by server
Master Refresh Token (can mint audience: "nextcloud" tokens)
- Issued to MCP server in Flow 2
- Stored encrypted in server's database
- Enables offline access to Nextcloud
- Used by server to mint Nextcloud access tokens

┌──────────────┐                                  ┌──────────────┐
│  MCP Client  │──────Flow 1: Authenticate───────►│   Shared IdP │
│ (Native App) │  client_id="claude-desktop"      │  (Keycloak)  │
│              │  scope="mcp-server:api"          │              │
│              │◄─────────────────────────────────┤              │
│              │  access_token (aud: mcp-server)  │              │
└──────┬───────┘                                  └──────────────┘
       │
       │ Bearer token
       │ (aud: mcp-server)
       ▼
┌──────────────┐
│  MCP Server  │  1. Validate aud == "mcp-server" ✓
│  (Stateless) │  2. Check for Nextcloud refresh token ✗
│              │  3. Return: "Not provisioned - run provision_nextcloud_access"
└──────┬───────┘
       │
       │ User calls provision_nextcloud_access tool
       │
       ▼
┌──────────────┐                                  ┌──────────────┐
│  MCP Server  │──────Flow 2: Provision Access───►│   Shared IdP │
│              │  client_id="mcp-server"          │  (Keycloak)  │
│              │  scope="offline_access nextcloud:*" │           │
│              │◄─────────────────────────────────┤              │
│              │  refresh_token (aud: nextcloud)  │              │
└──────┬───────┘                                  └──────────────┘
       │
       │ Store encrypted refresh token
       ▼
┌──────────────┐
│  MCP Server  │  Now STATEFUL - can access Nextcloud
│ (Stateful)   │  ├─ Validate MCP tokens (aud: mcp-server)
│              │  ├─ Mint Nextcloud tokens (aud: nextcloud)
│              │  └─ Access Nextcloud APIs
└──────────────┘

Key Innovations:

Separate Client Identities: MCP client uses its own client_id, not the server's
Stateless by Default: Server starts with zero stored state
Explicit Provisioning: Resource access requested via separate tool call
Progressive Consent: Users understand what they're authorizing at each step
SSO Efficiency: If authenticated in Flow 1, Flow 2 only needs consent (no re-login)

MCP Client Registration

IMPORTANT: MCP SDK clients (like Claude Desktop) are proper OAuth clients registered at the IdP level, not with the MCP server itself.

Client Registration Options

Option 1: Dynamic Client Registration (DCR) - Recommended

# MCP client registers itself at IdP startup
import httpx

async def register_with_idp():
    response = await httpx.post(
        "https://idp.example.com/register",
        json={
            "client_name": "Claude Desktop",
            "redirect_uris": ["http://localhost:51234/callback"],
            "grant_types": ["authorization_code", "refresh_token"],
            "token_endpoint_auth_method": "none",  # Public client with PKCE
            "application_type": "native",
        }
    )
    client_id = response.json()["client_id"]
    # Store client_id for subsequent OAuth flows

Option 2: Pre-registered Client

# Admin pre-registers known MCP clients in Keycloak/Nextcloud
# Client IDs: "claude-desktop", "continue-dev", "zed-editor", etc.

Key Points:

MCP clients are registered at IdP level (Nextcloud OIDC, Keycloak, Auth0, etc.)
MCP server validates client_id against IdP registry during authorization
Public clients use PKCE (no client_secret) per RFC 8252
Each MCP client has its own identity and permissions

Authentication Flows

Flow 1: MCP Client Authentication (Always Required)

This is a standard OAuth 2.0 PKCE flow where the MCP client authenticates to the MCP server. The server has no involvement in this flow beyond returning the challenge endpoint.

sequenceDiagram
    participant User
    participant MCPClient as MCP Client<br/>(Claude Desktop)
    participant MCPServer as MCP Server<br/>(Stateless)
    participant IdP as Shared IdP<br/>(Keycloak)

    User->>MCPClient: Connect to MCP Server
    MCPClient->>MCPServer: Initial request
    MCPServer-->>MCPClient: 401 Unauthorized<br/>WWW-Authenticate: Bearer realm="Keycloak"<br/>auth_endpoint=https://keycloak/auth

    Note over MCPClient: Generate PKCE:<br/>verifier + challenge

    MCPClient->>MCPClient: Start local callback server<br/>http://localhost:51234/callback

    MCPClient->>IdP: GET /auth<br/>client_id="claude-desktop" ← Client's own ID!<br/>redirect_uri=http://localhost:51234/callback<br/>scope=openid profile mcp-server:api<br/>code_challenge + S256<br/>response_type=code

    Note over IdP: Standard OAuth flow<br/>MCP Server NOT involved!

    IdP->>User: Login page (if not authenticated)
    User->>IdP: Authenticate (username + password)

    IdP->>User: Consent: "Allow Claude Desktop<br/>to access MCP Server?"
    User->>IdP: Approve

    IdP->>MCPClient: 302 to http://localhost:51234/callback<br/>code={authorization_code}

    MCPClient->>IdP: POST /token<br/>code={authorization_code}<br/>client_id="claude-desktop"<br/>code_verifier={verifier}<br/>redirect_uri=http://localhost:51234/callback

    IdP->>MCPClient: Tokens:<br/>- access_token (aud: mcp-server)<br/>- id_token<br/>- token_type: Bearer<br/>- expires_in: 3600

    Note over MCPClient: Client has token with<br/>aud: "mcp-server"

    MCPClient->>MCPServer: MCP request<br/>Authorization: Bearer {token}

    MCPServer->>MCPServer: Validate:<br/>1. aud == "mcp-server" ✓<br/>2. Scopes include required scope ✓

    MCPServer-->>MCPClient: Success (or 403 if wrong audience)

Key Points:

No server interception: MCP server is NOT involved in the OAuth flow
Client's credentials: Flow uses client_id="claude-desktop", not the server's ID
Direct callback: IdP redirects directly to client's localhost callback
Stateless server: Server just validates the resulting token's audience

After Flow 1:

✅ MCP client authenticated with token (aud: "mcp-server")
❌ MCP server has NO Nextcloud access
❌ MCP server has NO stored tokens

Flow 2: Nextcloud Resource Provisioning (Triggered Explicitly)

This flow is initiated when the user calls a Nextcloud tool and the server discovers it has no refresh token. This is a completely separate OAuth flow using the server's credentials.

sequenceDiagram
    participant User
    participant MCPClient as MCP Client
    participant MCPServer as MCP Server
    participant TokenStore as Token Storage
    participant IdP as Shared IdP
    participant Nextcloud

    Note over User,MCPClient: User authenticated from Flow 1

    MCPClient->>MCPServer: list_notes()<br/>Authorization: Bearer {mcp_token}

    MCPServer->>MCPServer: Validate token:<br/>aud == "mcp-server" ✓

    MCPServer->>MCPServer: Extract user_id from token

    MCPServer->>TokenStore: Check: Has refresh token<br/>for user_id?
    TokenStore-->>MCPServer: NOT FOUND

    MCPServer-->>MCPClient: Error Response:<br/>"Not provisioned for Nextcloud access.<br/>Please call provision_nextcloud_access tool."

    Note over User,MCPClient: User explicitly calls provisioning

    MCPClient->>MCPServer: provision_nextcloud_access()<br/>Authorization: Bearer {mcp_token}

    MCPServer->>MCPServer: Validate token:<br/>aud == "mcp-server" ✓

    MCPServer->>MCPServer: Generate state linking to user_id

    MCPServer-->>MCPClient: Return OAuth URL:<br/>{<br/>  "auth_url": "https://keycloak/auth?...",<br/>  "message": "Open this URL to authorize"<br/>}

    Note over MCPClient,IdP: This is a SECOND, SEPARATE OAuth flow!<br/>Uses MCP server's client_id!

    User->>IdP: Navigate to auth_url:<br/>client_id="mcp-server" ← Server's ID!<br/>redirect_uri=https://mcp-server.com/callback-nextcloud<br/>scope=openid offline_access nextcloud:api<br/>state={user_id_link}

    Note over IdP: User may already be logged in (SSO)<br/>Just need consent, not re-authentication

    IdP->>User: Consent: "Allow MCP Server<br/>to access Nextcloud offline<br/>on your behalf?"
    User->>IdP: Approve offline_access

    IdP->>MCPServer: 302 to /callback-nextcloud<br/>code={authorization_code}<br/>state={user_id_link}

    MCPServer->>MCPServer: Validate state,<br/>extract user_id

    MCPServer->>IdP: POST /token<br/>code={authorization_code}<br/>client_id="mcp-server"<br/>client_secret={server_secret}<br/>redirect_uri=https://mcp-server.com/callback-nextcloud

    IdP->>MCPServer: Tokens:<br/>- access_token (aud: nextcloud)<br/>- refresh_token ← MASTER TOKEN!<br/>- id_token

    MCPServer->>TokenStore: Store refresh token<br/>(encrypted, linked to user_id)

    MCPServer-->>User: "Provisioning complete!<br/>You can now access Nextcloud."

    Note over MCPServer: Server is now STATEFUL<br/>Has refresh token for this user

Key Points:

Separate flow: This is Flow 2, completely independent from Flow 1
Server's credentials: Uses client_id="mcp-server", the SERVER's own ID
Server callback: IdP redirects to server's callback endpoint
User intent: User explicitly requested this provisioning
SSO benefit: If user authenticated in Flow 1, only consent needed here

After Flow 2:

✅ MCP client still uses same token (aud: "mcp-server")
✅ MCP server now has refresh token (can mint aud: "nextcloud" tokens)
✅ Background workers can operate offline

Subsequent Sessions (Using Provisioned Access)

Once provisioned, subsequent MCP sessions work seamlessly:

sequenceDiagram
    participant MCPClient as MCP Client
    participant MCPServer as MCP Server<br/>(Stateful)
    participant TokenStore as Token Storage
    participant IdP as Shared IdP
    participant Nextcloud

    Note over MCPClient: User reconnects (new MCP session)

    MCPClient->>MCPServer: list_notes()<br/>Authorization: Bearer {new_mcp_token}

    MCPServer->>MCPServer: Validate token:<br/>aud == "mcp-server" ✓

    MCPServer->>MCPServer: Extract user_id from token

    MCPServer->>TokenStore: Check: Has refresh token<br/>for user_id?
    TokenStore-->>MCPServer: FOUND ✓

    MCPServer->>MCPServer: Check cached Nextcloud token

    alt Nextcloud Token Expired or Missing
        MCPServer->>IdP: POST /token<br/>grant_type=refresh_token<br/>refresh_token={stored_token}<br/>audience=nextcloud

        IdP->>MCPServer: access_token (aud: nextcloud)

        MCPServer->>MCPServer: Cache token (5 min TTL)
    end

    MCPServer->>Nextcloud: GET /notes<br/>Authorization: Bearer {nextcloud_token}

    Nextcloud->>IdP: Validate token + audience
    IdP-->>Nextcloud: Valid, aud: nextcloud ✓

    Nextcloud-->>MCPServer: [list of notes]

    MCPServer-->>MCPClient: MCP response with notes

    Note over MCPClient: Client only sees MCP response,<br/>never sees Nextcloud token!

Key Points:

No re-provisioning: Refresh token persists across MCP sessions
Token caching: Nextcloud access tokens cached to reduce IdP calls
Audience isolation: MCP client never sees Nextcloud tokens

Background Operations

sequenceDiagram
    participant Worker as Background Worker
    participant TokenStore as Token Storage
    participant IdP as Shared IdP
    participant Nextcloud

    Worker->>TokenStore: Get user's master refresh token
    TokenStore-->>Worker: Encrypted master refresh token
    Worker->>Worker: Decrypt token

    Worker->>IdP: POST /token<br/>grant_type=refresh_token<br/>audience=nextcloud
    IdP->>Worker: New access token ONLY<br/>(aud: nextcloud)
    Note over IdP,Worker: Access token for Nextcloud<br/>Master refresh token unchanged

    Worker->>Nextcloud: API call with access token
    Nextcloud->>IdP: Validate token
    IdP-->>Nextcloud: Valid + scopes
    Nextcloud-->>Worker: API response

    Note over Worker: No MCP client involvement!<br/>No refresh token rotation!

Token Rotation Strategy:

Access Tokens: Refreshed frequently (every 5-60 minutes) as needed
Master Refresh Token: Only rotated periodically (e.g., daily/weekly) or when explicitly refreshing the MCP session
Separation: Getting Nextcloud access tokens does NOT rotate the master refresh token

Implementation

1. Token Broker Service

import jwt
from datetime import datetime, timedelta

class TokenBrokerService:
    """
    Token broker that exchanges master refresh tokens for audience-specific access tokens.
    Works alongside the required_scopes decorator which handles MCP token validation.
    """

    def __init__(self,
                 token_storage: RefreshTokenStorage,
                 idp_client: OAuthClient):
        self.storage = token_storage
        self.idp_client = idp_client
        self.nextcloud_token_cache = {}  # Short-lived cache

    async def get_nextcloud_token(self, user_id: str) -> str | None:
        """
        Get or refresh token with Nextcloud audience.
        Called AFTER the required_scopes decorator has validated the MCP token.
        """
        # Check cache first
        cached = self.nextcloud_token_cache.get(user_id)
        if cached and cached['exp'] > datetime.utcnow().timestamp():
            return cached['token']

        # Get master refresh token (stored during OAuth flow)
        refresh_token = await self.storage.get_refresh_token(user_id)
        if not refresh_token:
            logger.warning(f"No refresh token for user {user_id}")
            return None  # User needs to re-authenticate

        try:
            # Request new ACCESS token with Nextcloud audience
            # This does NOT rotate the master refresh token!
            response = await self.idp_client.refresh_token(
                refresh_token=refresh_token,
                audience='nextcloud'  # CRITICAL: Request Nextcloud audience
            )

            # Verify the new token has correct audience
            payload = jwt.decode(
                response.access_token,
                options={"verify_signature": False}
            )

            audiences = payload.get('aud', [])
            if isinstance(audiences, str):
                audiences = [audiences]

            if 'nextcloud' not in audiences:
                raise ValueError(f"IdP returned wrong audience: {audiences}")

            # Cache for short period (5 minutes)
            self.nextcloud_token_cache[user_id] = {
                'token': response.access_token,
                'exp': payload.get('exp', 0)
            }

            return response.access_token

        except Exception as e:
            logger.error(f"Failed to get Nextcloud token: {e}")
            return None

    async def refresh_master_token(self, user_id: str):
        """
        Refresh the master refresh token (with rotation).
        This should only be called periodically (e.g., weekly) or when
        explicitly refreshing the MCP session, NOT on every API call.
        """
        old_refresh = await self.storage.get_refresh_token(user_id)
        if not old_refresh:
            raise ValueError("No refresh token found")

        # Mark as used (rotation)
        await self.storage.mark_token_used(old_refresh.token_id)

        try:
            # Get new refresh token from IdP
            response = await self.idp_client.refresh_token(
                refresh_token=old_refresh.token,
                scope='openid profile offline_access nextcloud:*'
            )

            # Store new refresh token
            await self.storage.store_refresh_token(
                user_id=user_id,
                token_family_id=old_refresh.token_family_id,
                refresh_token=response.refresh_token,
                status='active'
            )

            return response.refresh_token

        except RefreshTokenReuseError:
            # Possible token theft - revoke entire family
            await self.storage.revoke_token_family(old_refresh.token_family_id)
            await self.alert_user_possible_breach(user_id)
            raise

# Integration with FastMCP framework
class MCPTokenVerifier(TokenVerifier):
    """
    Simple verifier that checks audience for MCP tokens.
    Used by FastMCP framework alongside required_scopes decorator.
    """

    async def verify_token(self, token: str) -> AccessToken | None:
        """Verify token has correct audience for MCP server."""
        try:
            payload = jwt.decode(
                token,
                options={"verify_signature": False}  # IdP handles signature
            )

            # CRITICAL: Verify audience is MCP server
            audiences = payload.get('aud', [])
            if isinstance(audiences, str):
                audiences = [audiences]

            if 'mcp-server' not in audiences:
                logger.warning(f"Token rejected: wrong audience {audiences}")
                return None

            # Check expiry
            if payload.get('exp', 0) < datetime.utcnow().timestamp():
                return None

            return AccessToken(
                token=token,  # Keep original MCP token
                scopes=payload.get('scope', '').split(),
                resource=json.dumps({
                    "user_id": payload['sub'],
                    "session_id": payload.get('jti')
                })
            )

        except jwt.InvalidTokenError:
            return None

2. MCP Tool for Resource Provisioning

CRITICAL: Flow 1 (client authentication) does NOT use MCP server endpoints. The MCP client authenticates directly with the IdP using its own client_id. The server only validates the resulting tokens.

For Flow 2 (Nextcloud provisioning), we provide an MCP tool that returns an OAuth URL:

from urllib.parse import urlencode
import secrets

@mcp.tool()
@required_scopes("mcp:provision")  # Or allow all authenticated users
async def provision_nextcloud_access(ctx: Context) -> dict:
    """
    Initiate OAuth flow to grant MCP server access to Nextcloud on your behalf.

    This starts Flow 2, where you authorize the MCP server to access Nextcloud
    resources offline (when you're not connected).

    Returns:
        dict: OAuth authorization URL to visit in your browser
    """
    # Get user_id from MCP token (already validated by required_scopes)
    token_payload = jwt.decode(
        ctx.authorization.token,
        options={"verify_signature": False}
    )
    user_id = token_payload['sub']

    # Check if already provisioned
    token_storage = get_token_storage(ctx)
    existing_token = await token_storage.get_refresh_token(user_id)
    if existing_token:
        return {
            "status": "already_provisioned",
            "message": "MCP server already has Nextcloud access for this user."
        }

    # Generate state to link callback to this user
    state = secrets.token_urlsafe(32)
    await store_provisioning_session(
        state=state,
        user_id=user_id,
        created_at=datetime.utcnow()
    )

    # Build OAuth URL for Flow 2
    # CRITICAL: This uses the MCP server's client_id, not the MCP client's!
    idp_params = {
        "client_id": MCP_SERVER_CLIENT_ID,  # Server's ID!
        "redirect_uri": f"{MCP_SERVER_URL}/oauth/callback-nextcloud",
        "response_type": "code",
        "scope": "openid offline_access "
                 "nextcloud:notes:read nextcloud:notes:write "
                 "nextcloud:calendar:read nextcloud:calendar:write",
        "state": state,
        "prompt": "consent"  # Ensure user sees consent screen
    }

    auth_url = f"{IDP_AUTHORIZATION_ENDPOINT}?{urlencode(idp_params)}"

    return {
        "status": "pending",
        "auth_url": auth_url,
        "message": "Please open the URL in your browser to authorize Nextcloud access.",
        "instructions": "After authorizing, the MCP server will be able to access Nextcloud on your behalf."
    }

3. OAuth Callback for Resource Provisioning (Flow 2)

@app.get("/oauth/callback-nextcloud")
async def oauth_callback_nextcloud(code: str, state: str):
    """
    Handle IdP callback for Flow 2 (Nextcloud resource provisioning).

    This endpoint receives the authorization code after the user consents to
    the MCP server accessing Nextcloud on their behalf.
    """
    # Retrieve provisioning session
    session = await get_provisioning_session(state)
    if not session:
        return HTMLResponse(
            "<html><body>"
            "<h1>Error</h1>"
            "<p>Invalid or expired authorization request.</p>"
            "</body></html>",
            status_code=400
        )

    user_id = session.user_id

    try:
        # Exchange authorization code for tokens
        # CRITICAL: This uses the MCP server's client credentials!
        tokens = await idp_client.exchange_code(
            code=code,
            redirect_uri=f"{MCP_SERVER_URL}/oauth/callback-nextcloud",
            client_id=MCP_SERVER_CLIENT_ID,
            client_secret=MCP_SERVER_CLIENT_SECRET
        )

        # Verify the refresh token has correct audience
        # NOTE: The access token will have aud: "nextcloud", and the
        # refresh token should be able to mint tokens with that audience
        payload = jwt.decode(
            tokens.access_token,
            options={"verify_signature": False}
        )

        audiences = payload.get('aud', [])
        if isinstance(audiences, str):
            audiences = [audiences]

        if 'nextcloud' not in audiences:
            raise ValueError(f"IdP returned token with wrong audience: {audiences}")

        # Generate new token family for rotation
        token_family_id = str(uuid4())

        # Store master refresh token (encrypted)
        # This token can mint tokens with aud: "nextcloud"
        token_storage = get_token_storage()
        await token_storage.store_tokens(
            user_id=user_id,
            token_family_id=token_family_id,
            access_token=tokens.access_token,  # Initial Nextcloud access token
            refresh_token=tokens.refresh_token,  # Master refresh token!
            status='active',
            scopes=tokens.scope,
            idp_subject=payload['sub']
        )

        # Delete provisioning session
        await delete_provisioning_session(state)

        # Return success page
        return HTMLResponse(
            "<html><body>"
            "<h1>Success!</h1>"
            "<p>MCP server has been granted access to Nextcloud on your behalf.</p>"
            "<p>You can close this window and return to your MCP client.</p>"
            "</body></html>"
        )

    except Exception as e:
        logger.error(f"Failed to exchange authorization code: {e}")
        return HTMLResponse(
            "<html><body>"
            "<h1>Error</h1>"
            "<p>Failed to complete authorization. Please try again.</p>"
            f"<p>Error: {str(e)}</p>"
            "</body></html>",
            status_code=500
        )

NOTE: The MCP server does NOT need to provide /oauth/authorize or /oauth/token endpoints for Flow 1. The MCP client authenticates directly with the IdP using its own client_id, and the IdP issues tokens directly to the client. The MCP server only validates these tokens.

4. MCP Tool Token Verification with Audience Check

from functools import wraps

def required_scopes(*scopes):
    """
    Decorator that verifies token audience and scopes.
    The existing required_scopes decorator needs to be updated
    to verify audience: "mcp-server" for all incoming tokens.
    """
    def decorator(func):
        @wraps(func)
        async def wrapper(ctx: Context, *args, **kwargs):
            # Get token from context (set by FastMCP framework)
            token = ctx.authorization.token if ctx.authorization else None

            if not token:
                raise Unauthorized("No token provided")

            # Decode and verify audience
            try:
                payload = jwt.decode(
                    token,
                    options={"verify_signature": False}  # IdP handles signature
                )

                # CRITICAL: Verify token is for MCP server
                audiences = payload.get('aud', [])
                if isinstance(audiences, str):
                    audiences = [audiences]

                if 'mcp-server' not in audiences:
                    raise Unauthorized(f"Invalid audience: {audiences}")

                # Verify required scopes
                token_scopes = set(payload.get('scope', '').split())
                required = set(scopes)

                if not required.issubset(token_scopes):
                    missing = required - token_scopes
                    raise Forbidden(f"Missing scopes: {missing}")

                # Token is valid for MCP server with required scopes
                return await func(ctx, *args, **kwargs)

            except jwt.InvalidTokenError as e:
                raise Unauthorized(f"Invalid token: {e}")

        return wrapper
    return decorator

# Example usage in MCP tools
@mcp.tool()
@required_scopes("notes:read")
async def list_notes(ctx: Context) -> dict:
    """List notes - token audience and scopes are automatically verified."""
    # Token already verified to have audience: "mcp-server"
    # Now get Nextcloud token for backend access

    token_broker = get_token_broker(ctx)
    nextcloud_token = await token_broker.get_nextcloud_token(ctx.user_id)

    # Use Nextcloud token for API access
    client = NextcloudClient.from_token(
        base_url=NEXTCLOUD_HOST,
        token=nextcloud_token  # Token with aud: "nextcloud"
    )

    notes = await client.notes.list_notes()
    return {"notes": notes}

4. Token Storage Schema

-- User accounts (created from IdP identity)
CREATE TABLE users (
    id TEXT PRIMARY KEY,
    idp_sub TEXT UNIQUE NOT NULL,      -- IdP subject identifier
    username TEXT NOT NULL,
    email TEXT,
    created_at INTEGER NOT NULL,
    last_login INTEGER NOT NULL
);

-- IdP tokens with rotation support
CREATE TABLE idp_tokens (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id TEXT NOT NULL REFERENCES users(id),
    token_family_id TEXT NOT NULL,    -- Groups all tokens in rotation chain
    encrypted_access_token BLOB NOT NULL,
    encrypted_refresh_token BLOB NOT NULL,
    access_expires_at INTEGER NOT NULL,
    status TEXT NOT NULL CHECK(status IN ('active', 'used', 'revoked')),
    scopes TEXT NOT NULL,              -- Includes Nextcloud scopes
    idp_subject TEXT NOT NULL,         -- IdP user identifier
    created_at INTEGER NOT NULL,
    used_at INTEGER,                   -- When token was exchanged

    -- Only one active token per family
    UNIQUE(token_family_id, status) WHERE status = 'active'
);

-- Index for quick lookups
CREATE INDEX idx_active_tokens ON idp_tokens(user_id, status)
    WHERE status = 'active';
CREATE INDEX idx_token_families ON idp_tokens(token_family_id);

-- MCP session tokens (separate from IdP tokens)
CREATE TABLE mcp_sessions (
    session_token TEXT PRIMARY KEY,
    user_id TEXT NOT NULL REFERENCES users(id),
    created_at INTEGER NOT NULL,
    expires_at INTEGER NOT NULL,
    last_used INTEGER
);

-- OAuth flow sessions with PKCE support (temporary during auth)
CREATE TABLE oauth_sessions (
    session_id TEXT PRIMARY KEY,
    client_id TEXT,
    client_redirect_uri TEXT NOT NULL,  -- Client's localhost redirect URI
    state TEXT,
    code_challenge TEXT,                -- PKCE code challenge from client
    code_challenge_method TEXT,         -- PKCE method (S256)
    mcp_authorization_code TEXT UNIQUE, -- MCP-generated code (e.g., mcp-code-xyz)
    idp_access_token TEXT,              -- Stored after IdP exchange in /oauth/callback
    user_id TEXT,                       -- Set after IdP authentication
    created_at INTEGER NOT NULL,
    expires_at INTEGER NOT NULL
);

-- Audit log for security
CREATE TABLE token_audit_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id TEXT NOT NULL,
    token_family_id TEXT,
    operation TEXT NOT NULL,  -- 'authorize', 'refresh', 'revoke', 'reuse_detected'
    timestamp INTEGER NOT NULL,
    ip_address TEXT,
    user_agent TEXT,
    details TEXT
);

5. Background Worker (Access Token Only)

class BackgroundSyncWorker:
    """Background workers use master refresh token to get Nextcloud access tokens."""

    def __init__(self, token_storage: RefreshTokenStorage):
        self.storage = token_storage
        self.idp_client = OAuthClient.from_discovery(IDP_DISCOVERY_URL)
        self.nextcloud_url = os.getenv("NEXTCLOUD_HOST")
        self.nextcloud_token_cache = {}  # Short-lived cache

    async def sync_user_data(self, user_id: str):
        """
        Sync data using master refresh token to get Nextcloud access tokens.

        Key Points:
        - Workers use the master refresh token stored during OAuth flow
        - Workers request access tokens with audience: "nextcloud"
        - NO refresh token rotation during normal operations
        - Master refresh token only rotated periodically (e.g., weekly)
        """
        # Get master refresh token (stored during initial OAuth)
        master_refresh_token = await self.storage.get_refresh_token(user_id)
        if not master_refresh_token:
            logger.warning(f"No master refresh token for user {user_id}")
            return

        try:
            # Check cache for valid Nextcloud access token
            cached = self.nextcloud_token_cache.get(user_id)
            if cached and cached['exp'] > datetime.utcnow().timestamp():
                nextcloud_token = cached['token']
            else:
                # Get new ACCESS token with Nextcloud audience
                # This does NOT rotate the refresh token!
                response = await self.idp_client.refresh_token(
                    refresh_token=master_refresh_token,
                    audience='nextcloud'  # Request Nextcloud audience
                )

                # Verify audience is for Nextcloud (security check)
                payload = jwt.decode(
                    response.access_token,
                    options={"verify_signature": False}
                )

                audiences = payload.get('aud', [])
                if isinstance(audiences, str):
                    audiences = [audiences]

                if 'nextcloud' not in audiences:
                    raise ValueError(f"IdP returned wrong audience: {audiences}")

                # Cache the access token for 5 minutes
                self.nextcloud_token_cache[user_id] = {
                    'token': response.access_token,
                    'exp': payload.get('exp', 0)
                }
                nextcloud_token = response.access_token

            # Create Nextcloud client with access token
            # Token has audience: "nextcloud" and proper scopes
            client = NextcloudClient.from_token(
                base_url=self.nextcloud_url,
                token=nextcloud_token,  # Access token with aud: nextcloud
                username=user_id
            )

            # Perform sync operations with Nextcloud
            await self.sync_notes(user_id, client)
            await self.sync_calendar(user_id, client)
            await self.sync_contacts(user_id, client)

            logger.info(f"Background sync completed for user {user_id}")

        except HTTPStatusError as e:
            if e.response.status_code == 401:
                # Access token rejected - try clearing cache
                self.nextcloud_token_cache.pop(user_id, None)
                # If persistent, may need to trigger re-authentication
                await self.log_security_event(
                    user_id,
                    "access_token_rejected",
                    f"Nextcloud rejected access token for user {user_id}"
                )
            raise
        except Exception as e:
            logger.error(f"Background sync failed for user {user_id}: {e}")
            raise

    async def log_security_event(self, user_id: str, event: str, details: str):
        """Log security events for audit."""
        await self.storage.log_audit(
            user_id=user_id,
            operation=event,
            details=details,
            timestamp=datetime.utcnow().isoformat()
        )

6. Configuration

# Environment variables for federated setup
IDP_DISCOVERY_URL = os.getenv("IDP_DISCOVERY_URL")  # e.g., https://keycloak.example.com/realms/master/.well-known/openid-configuration
MCP_SERVER_CLIENT_ID = os.getenv("MCP_SERVER_CLIENT_ID")  # MCP server's client ID in IdP
MCP_SERVER_CLIENT_SECRET = os.getenv("MCP_SERVER_CLIENT_SECRET")  # Client secret
MCP_SERVER_URL = os.getenv("MCP_SERVER_URL", "http://localhost:8000")

# Nextcloud configuration
NEXTCLOUD_HOST = os.getenv("NEXTCLOUD_HOST")  # Nextcloud instance URL

# Parse IdP discovery document
async def setup_idp_client():
    """Initialize OAuth client from IdP discovery."""
    async with httpx.AsyncClient() as client:
        discovery = await client.get(IDP_DISCOVERY_URL)
        discovery_doc = discovery.json()

    return OAuthClient(
        authorization_endpoint=discovery_doc["authorization_endpoint"],
        token_endpoint=discovery_doc["token_endpoint"],
        introspection_endpoint=discovery_doc.get("introspection_endpoint"),
        userinfo_endpoint=discovery_doc["userinfo_endpoint"],
        client_id=MCP_SERVER_CLIENT_ID,
        client_secret=MCP_SERVER_CLIENT_SECRET
    )

Advantages

Single Sign-On: Users authenticate once to the shared IdP
Federated Identity: Enterprise-ready with support for SAML, LDAP backends
True Offline Access: Background workers operate with stored IdP refresh tokens
OAuth Compliant: Proper delegation with on-behalf-of pattern
Security Isolation: MCP clients never see IdP or Nextcloud credentials
Flexible Backend: Can swap Nextcloud for other resources without changing auth
Standard Pattern: Industry-standard federated OAuth architecture

Disadvantages

IdP Dependency: Requires a shared identity provider infrastructure
Complex Token Lifecycle: Managing tokens from IdP for Nextcloud access
Token Validation Overhead: Nextcloud must validate tokens with IdP
Migration Complexity: Existing deployments need IdP setup

Security Considerations

Progressive Consent Security Model

The dual OAuth flow architecture provides enhanced security through:

Separate Client Identities:
- MCP client authenticates with its own client_id (e.g., "claude-desktop")
- MCP server has its own client_id (e.g., "mcp-server")
- Each entity's permissions are independently managed at IdP level
- Compromised client credentials don't grant server-level access
Explicit User Consent:
- Flow 1: User consents to "Claude Desktop accessing MCP Server"
- Flow 2: User consents to "MCP Server accessing Nextcloud offline"
- Two separate, understandable authorization decisions
- Users understand the security model
Stateless by Default:
- Server starts with zero stored credentials
- No automatic provisioning of resource access
- User must explicitly authorize offline access via provision_nextcloud_access tool
- Reduces attack surface for initial deployment
Least Privilege:
- Flow 1 only grants MCP server authentication, no resource access
- Flow 2 only requested when user actually needs Nextcloud functionality
- Unused features don't get provisioned
Defense in Depth:
- Even if MCP client is compromised, attacker only gets aud:"mcp-server" tokens
- Cannot directly access Nextcloud without server's stored refresh token
- Server-side refresh token is encrypted at rest
- Multiple layers of protection

Audience Isolation Architecture

Core Security Principle: Token Audience Separation

The architecture enforces strict audience isolation to prevent token misuse:

Tokens with audience: "mcp-server" can ONLY authenticate to MCP server
Tokens with audience: "nextcloud" can ONLY access Nextcloud APIs
No token has multiple audiences - this would be a security boundary violation
Compromised MCP tokens cannot access Nextcloud directly

Token Broker Security Model

The MCP server acts as a secure token broker:

Validates incoming tokens have audience: "mcp-server"
Uses stored refresh tokens to obtain audience: "nextcloud" tokens
Never exposes Nextcloud tokens to MCP clients
Maintains separate token lifecycles for each audience

Audience Validation Examples

# MCP Access Token (from IdP)
{
  "aud": "mcp-server",      # Single audience ONLY
  "sub": "user-123",
  "scope": "mcp:full",
  "exp": 1234567890
}

# Nextcloud Access Token (obtained via refresh)
{
  "aud": "nextcloud",        # Different audience
  "sub": "user-123",
  "scope": "notes:read calendar:write",
  "exp": 1234567890
}

# Master Refresh Token Claims (stored by server)
{
  "sub": "user-123",
  "scope": "openid offline_access nextcloud:notes:read nextcloud:calendar:write",
  # Can mint tokens with aud: "nextcloud" via refresh grant
}

PKCE Protection (Flow 1)

Mandatory for native clients (RFC 7636)
Applied in Flow 1 (MCP client → IdP authentication)
Code verifier: 43-128 character random string
Code challenge: SHA256(code_verifier)
Prevents authorization code interception
Validated by IdP before token issuance
Note: Flow 2 uses confidential client pattern (server has client_secret)

Native Client Security

Localhost redirect only (RFC 8252)
- Restrict to http://localhost:* or http://127.0.0.1:*
- Dynamic port allocation per session
- No custom URL schemes allowed
System browser required - no embedded browsers
302 redirect flow - direct redirect, no HTML page

Token Storage Security

Master refresh tokens: Encrypted at rest (Fernet/AES-256)
Audience-specific caching: Short-lived cache for Nextcloud tokens
Database isolation: Refresh tokens never exposed to application layer
Key rotation: Support for encryption key rotation
Hardware security: Consider HSM for production

Token Rotation with Audience Preservation

Rotation maintains audience: New tokens keep same audience
Reuse detection: Previous use revokes entire token family
Atomic operations: Database transactions prevent races
Audit trail: All exchanges logged with audience info

Trust Boundaries

┌──────────────┐     aud:"mcp-server"     ┌──────────────┐
│  MCP Client  │──────────────────────────►│  MCP Server  │
└──────────────┘                           └───────┬──────┘
                                                   │
                                          Refresh for different
                                               audience
                                                   │
┌──────────────┐     aud:"nextcloud"      ┌───────▼──────┐
│  Nextcloud   │◄──────────────────────────│     IdP      │
└──────────────┘                           └──────────────┘

MCP Client → MCP Server: Only aud:"mcp-server" tokens
MCP Server → IdP: Refresh with audience parameter
MCP Server → Nextcloud: Only aud:"nextcloud" tokens
No direct path: Client cannot use MCP tokens for Nextcloud

Revocation and Breach Response

Audience-specific revocation: Can revoke MCP without affecting Nextcloud
Token family tracking: All tokens from same refresh chain
Immediate propagation: Revocation flows through trust chain
Breach isolation: Compromised MCP tokens don't grant Nextcloud access

Migration Strategy

Phase 1: IdP Setup

Deploy shared IdP (Keycloak recommended)
Register MCP server as OAuth client
Configure Nextcloud to accept IdP tokens
Test token validation flow

Phase 2: Parallel Operation

Keep existing pass-through authentication
Add federated auth as optional feature flag
Test with subset of users
Monitor token lifecycle and refresh patterns

Phase 3: Migration

Migrate existing users to IdP accounts
Map existing permissions to IdP scopes
Update clients to use new OAuth flow
Maintain backward compatibility period

Phase 4: Deprecation

Announce end-of-life for pass-through mode
Complete user migration
Remove legacy authentication code
Document new auth flow

Alternatives Considered

1. Pass-Through Only (Current)

Pros: Simple, stateless
Cons: No offline access possible
Rejected: Doesn't meet requirements

2. Service Accounts (ADR-002 Tier 1)

Pros: Simple to implement
Cons: Violates OAuth principles, creates audit issues
Rejected: Security and compliance concerns

3. Token Exchange (ADR-002 Tier 2)

Pros: Standards-based (RFC 8693)
Cons: Circular dependency, doesn't solve bootstrap problem
Rejected: Doesn't enable true offline access

4. Sign-in with Nextcloud (Previous ADR-004)

Pros: Direct Nextcloud integration
Cons: Tight coupling, no enterprise IdP support
Rejected: Not suitable for federated environments

5. Double OAuth (Manual)

Pros: Clear separation of concerns
Cons: Poor UX with two login prompts
Rejected: Users shouldn't authenticate twice

Token Exchange Pattern Implementation

How Audience-Specific Token Exchange Works

The key to this architecture is the IdP's ability to issue tokens with different audiences from a single refresh token. This is achieved through:

1. Keycloak Configuration

// Keycloak Client Configuration for MCP Server
{
  "clientId": "mcp-server",
  "standardFlowEnabled": true,
  "serviceAccountsEnabled": false,
  "publicClient": false,
  "attributes": {
    // Allow refresh tokens to request different audiences
    "oauth2.device.authorization.grant.enabled": "false",
    "oidc.ciba.grant.enabled": "false",
    "oauth2.token.exchange.grant.enabled": "true"  // Enable token exchange
  }
}

// Audience Mapper Configuration
{
  "name": "dynamic-audience-mapper",
  "protocol": "openid-connect",
  "protocolMapper": "oidc-audience-mapper",
  "config": {
    "included.client.audience": "mcp-server",  // Default audience
    "access.token.claim": "true",
    "id.token.claim": "false"
  }
}

// Scope-to-Audience Mapping
{
  "mcp:*": "mcp-server",        // MCP scopes → mcp-server audience
  "nextcloud:*": "nextcloud"     // Nextcloud scopes → nextcloud audience
}

2. Refresh Token with Audience Parameter

When the MCP server needs a token for a specific audience:

POST /realms/nextcloud-mcp/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=eyJhbGc...
&client_id=mcp-server
&client_secret=secret
&audience=nextcloud  # Request specific audience

Response:

{
  "access_token": "eyJhbGc...",  // Token with aud: "nextcloud"
  "expires_in": 300,
  "refresh_token": "eyJhbGc...",  // Same or rotated refresh token
  "token_type": "Bearer"
}

3. Alternative: Token Exchange (RFC 8693)

For IdPs that support token exchange:

POST /realms/nextcloud-mcp/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=eyJhbGc...  # Token with aud: "mcp-server"
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&requested_token_type=urn:ietf:params:oauth:token-type:access_token
&audience=nextcloud  # Request different audience

Why This Pattern Is Secure

Audience Validation at Every Layer:
- MCP server validates aud: "mcp-server" for incoming requests
- Nextcloud validates aud: "nextcloud" for API calls
- Tokens with wrong audience are rejected
Unidirectional Token Flow:
- Client → MCP: Only aud: "mcp-server"
- MCP → Nextcloud: Only aud: "nextcloud"
- No reverse flow possible
Breach Containment:
- Stolen MCP token: Cannot access Nextcloud
- Stolen Nextcloud token: Cannot authenticate to MCP
- Stolen refresh token: Requires client credentials to use

Configuration for Popular IdPs

Keycloak

Enable Token Exchange in realm settings
Configure audience mappers per client
Use protocol mappers for dynamic audiences

Auth0

Use custom rules for audience selection
Configure API identifiers as audiences
Enable refresh token rotation

Azure AD

Configure app registrations for each audience
Use scope-to-resource mapping
Enable conditional access policies

Okta

Define custom authorization servers
Configure audience claim per API
Use inline hooks for dynamic audiences

Token Acquisition Patterns for MCP Tool Calls

Progressive Consent vs Token Exchange

IMPORTANT: Progressive Consent and Token Exchange are complementary patterns that serve different purposes:

Progressive Consent = Authorization architecture (when and why users grant access)
- Flow 1: MCP client authenticates to MCP server
- Flow 2: MCP server provisions Nextcloud access
- Results in stored refresh tokens for background jobs
Token Exchange = Token acquisition pattern (how tokens are obtained during tool execution)
- Pass-through mode: Verify and pass Flow 1 token to Nextcloud
- Token exchange mode: Exchange Flow 1 token for ephemeral Nextcloud token
- Results in short-lived, operation-specific tokens

Key Principle: Refresh tokens from Progressive Consent (Flow 2) should NEVER be used for MCP tool calls - they are exclusively for background jobs. This maintains clear separation between user-initiated operations and offline background work.

Two Token Acquisition Modes

The MCP server supports two modes for obtaining Nextcloud tokens during tool execution:

Mode 1: Pass-Through (Default - ENABLE_TOKEN_EXCHANGE=false)

How it works:

MCP client sends Flow 1 token (aud: "mcp-server") with tool call
MCP server validates token audience and scopes
MCP server passes the same token to Nextcloud
Nextcloud validates token with IdP

Characteristics:

Simple, stateless operation
Single token flows through the system
Lower latency (no token exchange round-trip)
Token lifetime determined by IdP's Flow 1 token settings

Use case: Simple deployments where Flow 1 tokens are trusted to access Nextcloud directly.

Mode 2: Token Exchange (Opt-In - ENABLE_TOKEN_EXCHANGE=true)

How it works:

MCP client sends Flow 1 token (aud: "mcp-server") with tool call
MCP server validates token audience and scopes
MCP server exchanges Flow 1 token for ephemeral Nextcloud token via RFC 8693
MCP server uses ephemeral token for Nextcloud API call
Ephemeral token is discarded (not cached)

Characteristics:

Enhanced security through token delegation
Ephemeral tokens with minimal lifetime (5 minutes default)
Token exchange provides audit trail
Fallback to refresh grant if RFC 8693 not supported
Tokens never cached or stored

Use case: High-security environments requiring token delegation, audit trails, and minimal token lifetimes.

Implementation in get_client()

The token acquisition mode is handled transparently by get_client():

async def get_client(ctx: Context) -> NextcloudClient:
    """
    Get the appropriate Nextcloud client based on authentication mode.

    This function handles three modes:
    1. BasicAuth mode: Returns shared client from lifespan context
    2. OAuth pass-through mode (ENABLE_TOKEN_EXCHANGE=false, default):
       Verifies Flow 1 token and passes it to Nextcloud
    3. OAuth token exchange mode (ENABLE_TOKEN_EXCHANGE=true):
       Exchanges Flow 1 token for ephemeral Nextcloud token via RFC 8693
    """
    settings = get_settings()
    lifespan_ctx = ctx.request_context.lifespan_context

    # BasicAuth mode
    if hasattr(lifespan_ctx, "client"):
        return lifespan_ctx.client

    # OAuth mode
    if hasattr(lifespan_ctx, "nextcloud_host"):
        if settings.enable_token_exchange:
            # Token exchange mode
            return await get_session_client_from_context(ctx, lifespan_ctx.nextcloud_host)
        else:
            # Pass-through mode (default)
            return get_client_from_context(ctx, lifespan_ctx.nextcloud_host)

Nextcloud Scope Limitation

CRITICAL: Nextcloud does not support OAuth scopes natively. The scopes used in this architecture (e.g., "notes:read", "calendar:write") are soft-scopes enforced by the MCP server via the @require_scopes decorator, not by the IdP or Nextcloud.

Implications:

Token exchange requests don't pass scopes to the IdP (Nextcloud doesn't validate them)
The MCP server's @require_scopes decorator handles authorization checks
All Nextcloud tokens have equivalent permissions at the Nextcloud level
Fine-grained access control is enforced by the MCP server, not Nextcloud

Why this matters:

You cannot request a "notes-only" token from the IdP
Token exchange provides audit and delegation benefits, not scope restriction
Scopes are a convenience for MCP server authorization logic, not a security boundary

Background Job Pattern

Background jobs use a completely different token acquisition pattern:

class BackgroundSyncWorker:
    async def sync_user_data(self, user_id: str):
        """Background workers use refresh tokens from Flow 2, never from tool calls."""

        # Get refresh token stored during Flow 2 (Progressive Consent)
        refresh_token = await self.storage.get_refresh_token(user_id)

        # Use refresh token to get Nextcloud access token
        response = await self.idp_client.refresh_token(
            refresh_token=refresh_token,
            audience='nextcloud'
        )

        # Use access token for background operations
        client = NextcloudClient.from_token(
            base_url=self.nextcloud_url,
            token=response.access_token,
            username=user_id
        )

        await self.sync_notes(user_id, client)

Key differences:

Uses refresh tokens from Flow 2 (Progressive Consent provisioning)
Tokens can be cached for efficiency (longer-lived operations)
No user interaction possible (offline)
Different scopes than tool calls (e.g., "notes:sync" vs "notes:read")

When to Enable Token Exchange

Enable token exchange when:

You need audit trails showing token delegation
You want minimal token lifetimes for security
Your IdP supports RFC 8693
You operate in a high-security environment

Use pass-through mode when:

Simplicity is more important than token delegation
Your IdP doesn't support RFC 8693
You trust Flow 1 tokens to access Nextcloud directly
Lower latency is a priority

Both modes maintain the same security boundary: Refresh tokens from Flow 2 are never used for tool calls, only for background jobs.

Decision Outcome

The Progressive Consent Architecture with Dual OAuth Flows provides a secure, enterprise-ready solution for offline access while maintaining strict security boundaries and user transparency. By using separate OAuth flows for client authentication and resource provisioning, we achieve:

Security through separation: Two distinct OAuth flows with different client identities
Explicit user consent: Users understand exactly what they're authorizing
Offline capabilities: Master refresh tokens enable background operations
Enterprise compliance: Follows OAuth best practices and security standards
Stateless by default: Server only stores credentials when explicitly provisioned

Key Implementation: Two Completely Separate OAuth Flows

The Progressive Consent architecture solves the critical challenges of token brokering while maintaining standards compliance:

Flow 1: MCP Client Authentication (Always Required)

Purpose: Authenticate MCP client to MCP server
Participants: MCP Client (e.g., Claude Desktop) ↔ IdP
Client ID: MCP client's own ID (e.g., "claude-desktop")
Scopes: openid profile mcp-server:api
User Consent: "Allow Claude Desktop to access MCP Server?"
Result: Access token with aud: "mcp-server"
Server State: STATELESS - server just validates tokens
Key Point: MCP server is NOT involved in this flow - client authenticates directly with IdP

Flow 2: Resource Provisioning (Explicit, On-Demand)

Purpose: Grant MCP server offline access to Nextcloud
Trigger: User calls provision_nextcloud_access tool
Participants: User → MCP Server ↔ IdP
Client ID: MCP server's own ID (e.g., "mcp-server")
Scopes: openid offline_access nextcloud:*
User Consent: "Allow MCP Server to access Nextcloud offline?"
Result: Refresh token with aud: "nextcloud"
Server State: STATEFUL - server stores encrypted refresh token
Key Point: This is a separate, independent OAuth flow initiated by server

Benefits:

Standards-compliant: Two proper OAuth 2.0 flows, no server interception
Secure: Separate client identities, no credential sharing
Transparent: Users explicitly understand each authorization
Efficient: Nextcloud consent only needed once per user
SSO-friendly: If authenticated in Flow 1, Flow 2 only requires consent (no re-login)
Least privilege: Flow 2 only triggered when user needs Nextcloud functionality

Token Lifecycle Clarification

Access Token Refresh: Happens frequently (every 5-60 minutes) without rotating the master refresh token
Master Refresh Token: Only rotated periodically (e.g., weekly) or during explicit session refresh
Audience Separation: Each token request specifies the target audience (mcp-server or nextcloud)

This architecture follows industry best practices for federated systems and positions the MCP server as a secure token broker in an enterprise identity ecosystem.

Implementation Status

Current Status: Partially Implemented (Refactoring Required)

The current implementation (nextcloud_mcp_server/auth/oauth_routes.py) implements a simplified hybrid flow but needs refactoring to match the progressive consent architecture documented above:

What's Currently Implemented ✅

Basic OAuth endpoints: /oauth/authorize, /oauth/callback, /oauth/token
PKCE validation: Code challenge/verifier flow works
Session storage: OAuth sessions stored in SQLite
Token storage: Master refresh tokens stored encrypted
Integration tests: Playwright-based tests pass (3/3)

What Needs Refactoring 🔄

Client Validation:
- Current: client_id is ignored
- Needed: Validate client_id exists at IdP registry
Dual OAuth Flow:
- Current: Single OAuth using MCP server's client_id
- Needed: Phase 1 (MCP client auth) + Phase 2 (conditional Nextcloud consent)
Consent Separation:
- Current: Monolithic consent screen
- Needed: Separate consents for client authentication vs resource access
Intermediate Session State:
- Current: Simple session with MCP code generated upfront
- Needed: Store state between OAuth phases, support consent_stage field
New Callback Endpoint:
- Current: Single /oauth/callback
- Needed: Add /oauth/callback_nextcloud for Phase 2

Migration Plan

The refactoring will be tracked in a separate issue. The current implementation serves as a proof-of-concept for the hybrid flow pattern and demonstrates:

MCP server can intercept OAuth callbacks
Refresh tokens can be securely stored
MCP clients can connect using PKCE
End-to-end tool execution works

The progressive consent architecture documented here represents the target state for production deployments.

Testing

The ADR-004 Hybrid Flow is currently tested via automated integration tests (using the simplified implementation):

Integration Tests

# Run all ADR-004 tests
uv run pytest tests/server/oauth/test_adr004_hybrid_flow.py --browser firefox -v

# Run specific test
uv run pytest tests/server/oauth/test_adr004_hybrid_flow.py::test_adr004_hybrid_flow_tool_execution --browser firefox -v

Test Coverage:

test_adr004_hybrid_flow_connection: Verifies MCP session establishment with hybrid flow token
test_adr004_hybrid_flow_tool_execution: Tests complete flow including tool execution
test_adr004_hybrid_flow_multiple_operations: Validates persistent access without re-authentication

What the tests verify:

✅ PKCE code challenge/verifier flow
✅ MCP server intercepts OAuth callback and stores master refresh token
✅ Client receives MCP access token (not master token)
✅ MCP session establishment with hybrid flow token
✅ Tool execution using stored refresh tokens (on-behalf-of pattern)
✅ Multiple operations without re-authentication

Test Implementation

The tests use Playwright automation to complete the OAuth flow:

Generate PKCE challenge/verifier
Navigate to MCP server /oauth/authorize endpoint
MCP server redirects to IdP
Playwright fills login form and consents
IdP redirects to MCP server /oauth/callback
MCP server stores master refresh token
MCP server redirects client with MCP authorization code
Client exchanges MCP code for access token using PKCE verifier
Create MCP session and execute tools

See tests/server/oauth/test_adr004_hybrid_flow.py for complete implementation.

FilesExpand file tree

ADR-004-mcp-application-oauth.md

Latest commit

History

ADR-004-mcp-application-oauth.md

File metadata and controls

ADR-004: Federated Authentication Architecture for Offline Access

Context

Problem Statement

Decision

Architecture

Progressive Consent Architecture with Dual OAuth Flows

The Core Principle

Flow 1: Client Authentication (Always Required)

Flow 2: Resource Provisioning (Triggered Explicitly)

Token Types and Lifecycles

MCP Client Registration

Client Registration Options

Authentication Flows

Flow 1: MCP Client Authentication (Always Required)

Flow 2: Nextcloud Resource Provisioning (Triggered Explicitly)

Subsequent Sessions (Using Provisioned Access)

Background Operations

Implementation

1. Token Broker Service

2. MCP Tool for Resource Provisioning

3. OAuth Callback for Resource Provisioning (Flow 2)

4. MCP Tool Token Verification with Audience Check

4. Token Storage Schema

5. Background Worker (Access Token Only)

6. Configuration

Advantages

Disadvantages

Security Considerations

Progressive Consent Security Model

Audience Isolation Architecture

Core Security Principle: Token Audience Separation

Token Broker Security Model

Audience Validation Examples

PKCE Protection (Flow 1)

Native Client Security

Token Storage Security

Token Rotation with Audience Preservation

Trust Boundaries

Revocation and Breach Response

Migration Strategy

Phase 1: IdP Setup

Phase 2: Parallel Operation

Phase 3: Migration

Phase 4: Deprecation

Alternatives Considered

1. Pass-Through Only (Current)

2. Service Accounts (ADR-002 Tier 1)

3. Token Exchange (ADR-002 Tier 2)

4. Sign-in with Nextcloud (Previous ADR-004)

5. Double OAuth (Manual)

Token Exchange Pattern Implementation

How Audience-Specific Token Exchange Works

1. Keycloak Configuration

2. Refresh Token with Audience Parameter

3. Alternative: Token Exchange (RFC 8693)

Why This Pattern Is Secure

Configuration for Popular IdPs

Keycloak

Auth0

Azure AD

Okta

Token Acquisition Patterns for MCP Tool Calls

Progressive Consent vs Token Exchange

Two Token Acquisition Modes

Mode 1: Pass-Through (Default - ENABLE_TOKEN_EXCHANGE=false)

Mode 2: Token Exchange (Opt-In - ENABLE_TOKEN_EXCHANGE=true)

Implementation in get_client()

Nextcloud Scope Limitation

Background Job Pattern

When to Enable Token Exchange

Decision Outcome

Key Implementation: Two Completely Separate OAuth Flows

Flow 1: MCP Client Authentication (Always Required)

Flow 2: Resource Provisioning (Explicit, On-Demand)