Feature Request: Login Flow v2 Support for Automated App Password Generation

[cbcoutinho]

Summary

Add support for Nextcloud's Login Flow v2 to enable external applications to obtain app passwords through a user-friendly authorization flow, eliminating manual copy/paste of credentials.

Use Case

I'm developing a system with:

A Nextcloud app (frontend, OAuth confidential client)

A Python backend (non-ExApp, also OAuth confidential client)

The Python backend requires an app password for background sync operations (WebDAV, CalDAV, etc.). Currently, users must:

Navigate to Nextcloud → Settings → Security → Devices & Sessions

Manually generate an app password

Copy the password

Paste it into my app's settings page

Submit to the backend

This is error-prone and creates friction for end users.

Proposed Solution

Implement Login Flow v2 endpoints that allow MCP clients or external applications to:

Initiate a login flow - Backend calls POST /index.php/login/v2 and receives a poll endpoint + login URL

Redirect user to authorize - Frontend opens Nextcloud's authorization page

Poll for credentials - Backend polls until user completes authorization, receiving { server, loginName, appPassword }

API Flow

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ MCP Client / │ │ nextcloud-mcp │ │ Nextcloud │ │ External App │ │ -server │ │ Server │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ │ │ │ 1. Request auth URL │ │ │──────────────────────>│ │ │ │ 2. POST /login/v2 │ │ │──────────────────────>│ │ │<──────────────────────│ │ │ {poll, login URL} │ │<──────────────────────│ │ │ 3. Return login URL│ │ │ │ │ │ 4. User visits login URL ────────────────────>│ │ │ │ │ │ 5. Poll endpoint │ │ │──────────────────────>│ │ (User logs in and grants access) │ │ │<──────────────────────│ │ │ {appPassword, ...} │ │ │ │ │ 6. Auth complete │ │ │<──────────────────────│ │

Suggested Implementation

New MCP Tool: nc_auth_login_flow_initiate

@mcp.tool() async def nc_auth_login_flow_initiate( user_agent: str = "Nextcloud MCP Server" ) -> LoginFlowResponse: """ Initiate Nextcloud Login Flow v2 for obtaining an app password. Returns: - login_url: URL to open in browser for user authorization - poll_endpoint: Endpoint to poll for credentials - poll_token: Token for polling """ response = await httpx.post( f"{nextcloud_host}/index.php/login/v2", headers={"User-Agent": user_agent} ) data = response.json() return LoginFlowResponse( login_url=data["login"], poll_endpoint=data["poll"]["endpoint"], poll_token=data["poll"]["token"] )

New MCP Tool: nc_auth_login_flow_poll

@mcp.tool() async def nc_auth_login_flow_poll( poll_endpoint: str, poll_token: str ) -> LoginFlowCredentials | None: """ Poll for Login Flow v2 completion. Returns credentials if user has authorized, None if still pending. Raises error on timeout or rejection. """ response = await httpx.post( poll_endpoint, data={"token": poll_token} ) if response.status_code == 200: data = response.json() return LoginFlowCredentials( server=data["server"], login_name=data["loginName"], app_password=data["appPassword"] ) elif response.status_code == 404: return None # Still pending else: raise AuthorizationError("Login flow failed or was rejected")

Alternative: HTTP Endpoint (non-MCP)

For applications that need to integrate without MCP, expose REST endpoints:

POST /auth/login-flow/initiate → { "login_url": "...", "poll_endpoint": "...", "poll_token": "..." } POST /auth/login-flow/poll Body: { "poll_endpoint": "...", "poll_token": "..." } → { "server": "...", "login_name": "...", "app_password": "..." } | 202 Pending

Benefits

Better UX - One-click authorization instead of manual copy/paste

More secure - App password name is set via User-Agent, making it identifiable in Nextcloud's security settings

Standard approach - Uses Nextcloud's official client authentication mechanism

Complements OAuth - While OAuth is experimental and requires patches, Login Flow v2 works out-of-the-box with any Nextcloud instance

Relationship to Existing Auth

This would complement, not replace, the existing authentication modes:

ModeUse CaseStatusBasic AuthStatic credentials in env vars✅ Production-readyOAuth2/OIDCPer-user tokens, fine-grained scopes⚠️ Experimental (requires patches)Login Flow v2 (proposed)Automated app password generation📋 This proposal

References

Nextcloud Login Flow Documentation

Nextcloud OCS API - getapppassword

Related upstream issue: nextcloud/server#21178 - API Endpoint to set application specific password

Environment

nextcloud-mcp-server version: 0.48.6+

Nextcloud: Any version with Login Flow v2 support (NC 16+)

Willingness to Contribute

I'm happy to help implement this feature or provide additional context. Let me know if you'd like me to submit a PR.

[cbcoutinho]

@claude help me refine this issue, so that we can consolidate the various deployment modes into a single OAuth MCP mode that uses URL elicitation to initiate Nextcloud's login flow v2. This would simplify the MCP server into an OAuth client that authenticates MCP client requests, and exchanges valid tokens for a Nextcloud app password to both access nextcloud for tool usage as well as background sync tasks. The goal is to remove the anti-pattern of token passthrough currently done by the multi-user basic auth deployment mode, as well as deprecating the OAuth deployment modes that require upstream patches to nextcloud for enabling oauth bearer tokens for NC app APIs

[claude]

Claude finished @cbcoutinho's task in 2m 0s —— View job

---

Refining Issue #521: Consolidating Auth Modes with Login Flow v2

I've analyzed the current authentication architecture and drafted a refined issue description below. This consolidates the deployment modes around a single OAuth architecture using Login Flow v2 to eliminate the anti-patterns of token passthrough and upstream patches.

---

Refined Issue Description

Summary

Consolidate all deployment modes into a single OAuth MCP architecture that uses Nextcloud's Login Flow v2 to exchange OAuth tokens for app passwords. This eliminates the need for:

• ❌ Multi-user BasicAuth token passthrough (anti-pattern)
• ❌ Upstream patches to Nextcloud for Bearer token support on app APIs
• ❌ Complex deployment mode selection with 5+ different configurations

Problem Statement

The current architecture has several anti-patterns and limitations:

Current State (5 Deployment Modes):

1. Single-User BasicAuth - Credentials in env vars
2. Multi-User BasicAuth - Token passthrough anti-pattern (client credentials sent through server)
3. OAuth Single-Audience - Requires upstream patches for Bearer tokens on Notes/Calendar APIs
4. OAuth Token Exchange - Complex RFC 8693 setup, limited IdP support
5. Smithery - Platform-specific stateless variant

Problems:

• Token Passthrough (Multi-User BasicAuth): MCP server receives client's username/password in every request and passes them to Nextcloud. This creates:
  • Security risk (server sees plaintext credentials)
  • Audit trail issues (all actions appear from MCP server)
  • Violates OAuth delegation principles
• Upstream Dependencies (OAuth modes): Require patched user_oidc app for Bearer token validation on non-OCS endpoints
  • Blocks adoption on unpatched Nextcloud instances
  • Maintenance burden tracking upstream PRs
• Configuration Complexity: ~500+ possible combinations across modes, making setup difficult

Proposed Solution

Replace all deployment modes with a unified OAuth architecture where:

1. MCP Client authenticates with OAuth (standard PKCE flow)

   • Receives token with aud: "mcp-server"
   • Used for MCP tool authentication only

2. MCP Server exchanges token for app password via Login Flow v2

   • URL elicitation triggers Nextcloud's Login Flow v2
   • User authorizes in browser (same UX as desktop/mobile apps)
   • Server receives app password (not refresh token)
   • App password used for Nextcloud API access (WebDAV, CalDAV, Notes, etc.)

3. Background sync uses stored app passwords

   • App passwords encrypted and stored in MCP server database
   • Background workers use app passwords (not refresh tokens)
   • User can revoke app password from Nextcloud settings

Architecture Diagram

┌─────────────────┐                  ┌──────────────────┐                  ┌─────────────────┐
│   MCP Client    │                  │   MCP Server     │                  │   Nextcloud     │
│   (Claude)      │                  │                  │                  │                 │
└────────┬────────┘                  └────────┬─────────┘                  └────────┬────────┘
         │                                    │                                     │
         │ 1. OAuth PKCE Flow                 │                                     │
         ├───────────────────────────────────>│                                     │
         │ (auth to IdP, get token)           │                                     │
         │                                    │                                     │
         │ 2. MCP Request                     │                                     │
         ├───────────────────────────────────>│                                     │
         │ Authorization: Bearer <mcp-token>  │                                     │
         │                                    │                                     │
         │                                    │ 3. Check for app password           │
         │                                    │    (none found)                     │
         │                                    │                                     │
         │ 4. Return URL elicitation          │                                     │
         │<───────────────────────────────────┤                                     │
         │ "Visit: <login-flow-url>"          │                                     │
         │                                    │                                     │
         │ 5. User opens URL in browser       │                                     │
         ├────────────────────────────────────┼────────────────────────────────────>│
         │                                    │                                     │
         │ 6. User authenticates & grants     │                                     │
         │<───────────────────────────────────┼─────────────────────────────────────┤
         │                                    │                                     │
         │                                    │ 7. Server polls endpoint            │
         │                                    ├────────────────────────────────────>│
         │                                    │ POST /login/v2/poll                 │
         │                                    │                                     │
         │                                    │ 8. Receive app password             │
         │                                    │<────────────────────────────────────┤
         │                                    │ {server, loginName, appPassword}    │
         │                                    │                                     │
         │                                    │ 9. Store app password (encrypted)   │
         │                                    │                                     │
         │ 10. Retry MCP request              │                                     │
         ├───────────────────────────────────>│                                     │
         │ Authorization: Bearer <mcp-token>  │                                     │
         │                                    │                                     │
         │                                    │ 11. Use app password                │
         │                                    ├────────────────────────────────────>│
         │                                    │ Authorization: Basic <app-password> │
         │                                    │                                     │
         │                                    │ 12. API Response                    │
         │                                    │<────────────────────────────────────┤
         │                                    │                                     │
         │ 13. Return result                  │                                     │
         │<───────────────────────────────────┤                                     │

Implementation

New MCP Tools (URL Elicitation Pattern):

@mcp.tool(
    annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True)
)
async def nc_auth_provision_access(ctx: Context) -> ProvisionAccessResponse:
    """
    Provision Nextcloud access for the authenticated user.
    
    Uses Login Flow v2 to obtain an app password. The user will be
    directed to authorize access in their browser.
    
    Returns:
        URL to visit for authorization and polling status
    """
    user_id = extract_user_from_token(ctx)
    
    # Check if already provisioned
    if await has_app_password(user_id):
        return ProvisionAccessResponse(
            status="already_provisioned",
            message="Access already provisioned"
        )
    
    # Initiate Login Flow v2
    response = await httpx.post(
        f"{nextcloud_host}/index.php/login/v2",
        json={"user_agent": "Nextcloud MCP Server"}
    )
    data = response.json()
    
    # Store poll token for this user
    await store_poll_token(user_id, data["poll"]["token"], data["poll"]["endpoint"])
    
    return ProvisionAccessResponse(
        status="authorization_required",
        authorization_url=data["login"],
        message="Please visit the URL to authorize access",
        poll_endpoint=data["poll"]["endpoint"]
    )

@mcp.tool(
    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True)
)
async def nc_auth_check_status(ctx: Context) -> ProvisionStatusResponse:
    """
    Check the status of Nextcloud access provisioning.
    
    Polls the Login Flow v2 endpoint to see if the user has completed
    authorization.
    """
    user_id = extract_user_from_token(ctx)
    poll_data = await get_poll_token(user_id)
    
    if not poll_data:
        return ProvisionStatusResponse(
            status="not_initiated",
            message="No provisioning in progress"
        )
    
    # Poll the endpoint
    response = await httpx.post(
        poll_data["endpoint"],
        data={"token": poll_data["token"]}
    )
    
    if response.status_code == 404:
        return ProvisionStatusResponse(
            status="pending",
            message="Waiting for user authorization"
        )
    elif response.status_code == 200:
        data = response.json()
        
        # Store encrypted app password
        await store_app_password(
            user_id=user_id,
            username=data["loginName"],
            app_password=data["appPassword"]
        )
        
        # Clean up poll token
        await delete_poll_token(user_id)
        
        return ProvisionStatusResponse(
            status="provisioned",
            message="Access successfully provisioned"
        )
    else:
        return ProvisionStatusResponse(
            status="error",
            message="Authorization failed or was rejected"
        )

Auto-Provisioning Flow:

When a user calls any Nextcloud tool (e.g., nc_notes_list):

1. Server validates MCP OAuth token
2. Server checks if app password exists for user
3. If not:
   • Return error with URL elicitation
   • Include link to nc_auth_provision_access tool
4. If yes:
   • Use stored app password for Nextcloud API call

Migration Path:

• Single-User BasicAuth → Becomes OAuth with single user provisioning
• Multi-User BasicAuth → Becomes OAuth with per-user app passwords (no more passthrough)
• OAuth Single-Audience → Becomes OAuth + Login Flow v2 (no more upstream patches needed)
• OAuth Token Exchange → Becomes OAuth + Login Flow v2 (simpler, broader compatibility)
• Smithery → Special case (stateless, may need different approach)

Benefits

✅ No Upstream Dependencies: Login Flow v2 works on all Nextcloud instances (NC 16+), no patches needed
✅ No Token Passthrough: Server never sees user's password, only app passwords
✅ Standard OAuth: MCP client uses standard PKCE flow
✅ User Control: Users see app password in Nextcloud settings, can revoke anytime
✅ Audit Trail: All actions attributed to correct user via app password
✅ Background Sync: App passwords enable offline access
✅ Simpler Configuration: One deployment mode instead of 5

Open Questions

1. Smithery Compatibility: Stateless mode may need special handling (ephemeral app passwords?)
2. App Password Lifecycle: How long to store? Refresh strategy?
3. Revocation Detection: How to handle when user revokes app password in Nextcloud?
4. Migration Strategy: Phased rollout or big-bang replacement?

Willingness to Contribute

I'm happy to help implement this consolidation. This would be a significant architectural change, so I'd appreciate feedback on the approach before starting implementation.

---

Tasks

• Read current authentication architecture documentation
• Analyze current deployment modes and pain points
• Draft refined issue description focusing on consolidation
• Present refined issue for review

Summary: I've drafted a refined issue description above that proposes consolidating all deployment modes into a single OAuth architecture using Login Flow v2. The key insight is using Login Flow v2 to exchange OAuth tokens for app passwords, which:

• Eliminates token passthrough (BasicAuth anti-pattern)
• Removes dependency on upstream Nextcloud patches
• Simplifies configuration from 5 modes to 1
• Provides standard OAuth UX with URL elicitation

Let me know if this aligns with your vision or if you'd like me to refine it further.

---