feat(helm): add login-flow auth mode to Helm chart (ADR-022)
Add Login Flow v2 as a fourth auth mode alongside basic, multi-user-basic, and oauth. This enables multi-user deployments using Nextcloud's native Login Flow v2 without requiring OAuth patches to user_oidc. - Add loginFlow section to values.yaml with token encryption config - Add login-flow env vars, args, volume mounts to deployment.yaml - Add login-flow secret and oauth-storage PVC templates - Add loginFlowSecretName helper, update dataStorageEnabled - Add multi-user-basic and login-flow sections to NOTES.txt - Add version footer and ArtifactHub changelog annotations - Update README with 4 auth modes and docker-compose profiles Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
@@ -55,6 +55,15 @@ http://127.0.0.1:8000/sse
|
||||
http://127.0.0.1:8000/mcp
|
||||
```
|
||||
|
||||
**Docker Compose Profiles** (for development/testing):
|
||||
|
||||
```bash
|
||||
docker compose --profile single-user up -d # Port 8000
|
||||
docker compose --profile multi-user-basic up -d # Port 8003
|
||||
docker compose --profile oauth up -d # Port 8001
|
||||
docker compose --profile login-flow up -d # Port 8004
|
||||
```
|
||||
|
||||
**Next Steps:**
|
||||
- Connect your MCP client (Claude Desktop, IDEs, `mcp dev`, etc.)
|
||||
- See [docs/installation.md](docs/installation.md) for other deployment options (local, Kubernetes)
|
||||
@@ -99,25 +108,33 @@ Want to see another Nextcloud app supported? [Open an issue](https://github.com/
|
||||
|
||||
### Authentication Modes
|
||||
|
||||
The server supports three authentication modes:
|
||||
The server supports four authentication modes:
|
||||
|
||||
**Single-User Mode (BasicAuth):**
|
||||
**Single-User (BasicAuth):**
|
||||
- One set of credentials shared by all MCP clients
|
||||
- Simple setup: username + app password in environment variables
|
||||
- All clients access Nextcloud as the same user
|
||||
- Best for: Personal use, development, single-user deployments
|
||||
|
||||
**Multi-User Mode (OAuth):**
|
||||
**Multi-User (BasicAuth Pass-Through):**
|
||||
- MCP clients send credentials via Authorization header
|
||||
- Server passes through to Nextcloud (stateless by default)
|
||||
- Optional offline access for background operations (`ENABLE_MULTI_USER_BASIC_AUTH=true`)
|
||||
- Best for: Multi-user setups without OAuth infrastructure
|
||||
|
||||
**Multi-User (OAuth):**
|
||||
- Each MCP client authenticates separately with their own Nextcloud account
|
||||
- Per-user scopes and permissions (clients only see tools they're authorized for)
|
||||
- More secure: tokens expire, credentials never shared with server
|
||||
- Best for: Teams, multi-user deployments, production environments with multiple users
|
||||
- Requires: Patches to the `user_oidc` app (experimental)
|
||||
|
||||
**Hybrid Mode (Multi-User BasicAuth + OAuth):**
|
||||
- MCP clients use BasicAuth (simple, stateless)
|
||||
- Admin operations use OAuth (webhooks, background sync)
|
||||
- Best for: Nextcloud deployments with admin-managed webhooks and semantic search
|
||||
- Requires: `ENABLE_MULTI_USER_BASIC_AUTH=true` + `ENABLE_OFFLINE_ACCESS=true`
|
||||
**Multi-User (Login Flow v2):**
|
||||
- Uses Nextcloud's native Login Flow v2 to obtain per-user app passwords
|
||||
- No OAuth patches required — works with stock Nextcloud
|
||||
- Each user authenticates via browser, server manages app passwords
|
||||
- Best for: Multi-user deployments without OAuth infrastructure (`ENABLE_LOGIN_FLOW=true`)
|
||||
- Experimental: See [ADR-022](docs/ADR-022-deployment-mode-consolidation.md) for details
|
||||
|
||||
See [docs/authentication.md](docs/authentication.md) for detailed setup instructions.
|
||||
|
||||
|
||||
@@ -25,6 +25,15 @@ annotations:
|
||||
# Grafana dashboard support
|
||||
grafana_dashboard: "true"
|
||||
grafana_dashboard_folder: "Nextcloud MCP"
|
||||
artifacthub.io/changes: |
|
||||
- kind: added
|
||||
description: Login Flow v2 auth mode for Helm chart (ADR-022)
|
||||
- kind: added
|
||||
description: Multi-user BasicAuth guidance in post-install NOTES
|
||||
- kind: added
|
||||
description: Version and changelog info in post-install NOTES
|
||||
- kind: changed
|
||||
description: Updated appVersion to 0.64.4
|
||||
dependencies:
|
||||
- name: qdrant
|
||||
version: "1.17.0"
|
||||
|
||||
@@ -57,6 +57,28 @@ Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentic
|
||||
|
||||
IMPORTANT: OAuth mode is experimental and requires patches to the user_oidc app.
|
||||
See: https://github.com/cbcoutinho/nextcloud-mcp-server#authentication
|
||||
{{- else if eq .Values.auth.mode "multi-user-basic" }}
|
||||
|
||||
3. Multi-User BasicAuth Mode (Pass-Through):
|
||||
- Users provide credentials via Authorization header
|
||||
- Connected to: {{ .Values.nextcloud.host }}
|
||||
{{- if .Values.auth.multiUserBasic.enableOfflineAccess }}
|
||||
- Offline access: Enabled (background operations with app passwords)
|
||||
- Token storage: {{ .Values.auth.multiUserBasic.tokenStorageDb }}
|
||||
{{- else }}
|
||||
- Offline access: Disabled (stateless pass-through)
|
||||
{{- end }}
|
||||
{{- else if eq .Values.auth.mode "login-flow" }}
|
||||
|
||||
3. Login Flow v2 Mode (Experimental, ADR-022):
|
||||
- Server URL: {{ include "nextcloud-mcp-server.mcpServerUrl" . }}
|
||||
- Connected to: {{ .Values.nextcloud.host }}
|
||||
- Token storage: {{ .Values.auth.loginFlow.tokenStorageDb }}
|
||||
|
||||
Users authenticate via Nextcloud's native Login Flow v2 — no OAuth patches required.
|
||||
Each user gets a per-device app password managed by the MCP server.
|
||||
|
||||
IMPORTANT: Login Flow v2 is experimental. See ADR-022 for details.
|
||||
{{- end }}
|
||||
|
||||
{{- if .Values.documentProcessing.enabled }}
|
||||
@@ -169,6 +191,12 @@ After migrating, remove the deprecated settings:
|
||||
================================================================================
|
||||
{{- end }}
|
||||
|
||||
Deployed version:
|
||||
- Chart: {{ .Chart.Version }}
|
||||
- App: {{ .Chart.AppVersion }}
|
||||
|
||||
Full changelog: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/charts/nextcloud-mcp-server/CHANGELOG.md
|
||||
|
||||
For more information and documentation:
|
||||
- GitHub: https://github.com/cbcoutinho/nextcloud-mcp-server
|
||||
- Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme
|
||||
|
||||
@@ -105,6 +105,17 @@ Create the name of the secret to use for OAuth
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{/*
|
||||
Create the name of the secret to use for Login Flow v2
|
||||
*/}}
|
||||
{{- define "nextcloud-mcp-server.loginFlowSecretName" -}}
|
||||
{{- if .Values.auth.loginFlow.existingSecret }}
|
||||
{{- .Values.auth.loginFlow.existingSecret }}
|
||||
{{- else }}
|
||||
{{- include "nextcloud-mcp-server.fullname" . }}-login-flow
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{/*
|
||||
Create the name of the PVC to use for OAuth storage
|
||||
*/}}
|
||||
@@ -147,6 +158,8 @@ Checks new dataStorage.enabled OR legacy persistence configs
|
||||
true
|
||||
{{- else if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled -}}
|
||||
true
|
||||
{{- else if eq .Values.auth.mode "login-flow" -}}
|
||||
true
|
||||
{{- else if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled -}}
|
||||
true
|
||||
{{- else -}}
|
||||
|
||||
@@ -46,8 +46,10 @@ spec:
|
||||
args:
|
||||
- "--transport"
|
||||
- "{{ .Values.mcp.transport }}"
|
||||
{{- if eq .Values.auth.mode "oauth" }}
|
||||
{{- if or (eq .Values.auth.mode "oauth") (eq .Values.auth.mode "login-flow") }}
|
||||
- "--oauth"
|
||||
{{- end }}
|
||||
{{- if eq .Values.auth.mode "oauth" }}
|
||||
- "--oauth-token-type"
|
||||
- "{{ .Values.auth.oauth.tokenType }}"
|
||||
{{- end }}
|
||||
@@ -134,6 +136,21 @@ spec:
|
||||
name: {{ include "nextcloud-mcp-server.oauthSecretName" . }}
|
||||
key: {{ .Values.auth.oauth.clientSecretKey }}
|
||||
{{- end }}
|
||||
{{- else if eq .Values.auth.mode "login-flow" }}
|
||||
# Login Flow v2 mode (ADR-022)
|
||||
- name: ENABLE_LOGIN_FLOW
|
||||
value: "true"
|
||||
- name: NEXTCLOUD_MCP_SERVER_URL
|
||||
value: {{ include "nextcloud-mcp-server.mcpServerUrl" . | quote }}
|
||||
- name: NEXTCLOUD_PUBLIC_ISSUER_URL
|
||||
value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
|
||||
- name: TOKEN_STORAGE_DB
|
||||
value: {{ .Values.auth.loginFlow.tokenStorageDb | quote }}
|
||||
- name: TOKEN_ENCRYPTION_KEY
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: {{ include "nextcloud-mcp-server.loginFlowSecretName" . }}
|
||||
key: {{ .Values.auth.loginFlow.tokenEncryptionKeyKey }}
|
||||
{{- end }}
|
||||
{{- if .Values.documentProcessing.enabled }}
|
||||
# Document processing
|
||||
@@ -282,7 +299,7 @@ spec:
|
||||
volumeMounts:
|
||||
- name: tmp
|
||||
mountPath: /tmp
|
||||
{{- if and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled }}
|
||||
{{- if or (and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled) (eq .Values.auth.mode "login-flow") }}
|
||||
- name: oauth-storage
|
||||
mountPath: /app/.oauth
|
||||
{{- end }}
|
||||
@@ -294,7 +311,7 @@ spec:
|
||||
volumes:
|
||||
- name: tmp
|
||||
emptyDir: {}
|
||||
{{- if and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled }}
|
||||
{{- if or (and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled) (eq .Values.auth.mode "login-flow") }}
|
||||
- name: oauth-storage
|
||||
persistentVolumeClaim:
|
||||
claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
|
||||
|
||||
@@ -16,6 +16,21 @@ spec:
|
||||
storage: {{ .Values.auth.oauth.persistence.size }}
|
||||
{{- end }}
|
||||
---
|
||||
{{- if eq .Values.auth.mode "login-flow" }}
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: {{ include "nextcloud-mcp-server.fullname" . }}-oauth-storage
|
||||
labels:
|
||||
{{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
|
||||
spec:
|
||||
accessModes:
|
||||
- ReadWriteOnce
|
||||
resources:
|
||||
requests:
|
||||
storage: 100Mi
|
||||
{{- end }}
|
||||
---
|
||||
{{- if and (eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true") (not .Values.dataStorage.existingClaim) }}
|
||||
{{- $legacyMultiUserBasic := eq (include "nextcloud-mcp-server.legacyMultiUserBasicPersistence" .) "true" }}
|
||||
{{- $legacyQdrant := eq (include "nextcloud-mcp-server.legacyQdrantPersistence" .) "true" }}
|
||||
|
||||
@@ -45,3 +45,17 @@ data:
|
||||
{{ .Values.auth.oauth.clientSecretKey }}: {{ .Values.auth.oauth.clientSecret | b64enc | quote }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
---
|
||||
{{- if eq .Values.auth.mode "login-flow" }}
|
||||
{{- if not .Values.auth.loginFlow.existingSecret }}
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: {{ include "nextcloud-mcp-server.fullname" . }}-login-flow
|
||||
labels:
|
||||
{{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
|
||||
type: Opaque
|
||||
data:
|
||||
{{ .Values.auth.loginFlow.tokenEncryptionKeyKey }}: {{ .Values.auth.loginFlow.tokenEncryptionKey | b64enc | quote }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
@@ -40,12 +40,13 @@ nextcloud:
|
||||
publicIssuerUrl: ""
|
||||
|
||||
# Authentication configuration
|
||||
# Choose one mode: "basic", "multi-user-basic", or "oauth"
|
||||
# Choose one mode: "basic", "multi-user-basic", "oauth", or "login-flow"
|
||||
auth:
|
||||
# Authentication mode: "basic", "multi-user-basic", or "oauth"
|
||||
# Authentication mode: "basic", "multi-user-basic", "oauth", or "login-flow"
|
||||
# basic: Single-user with username/password (recommended for personal use)
|
||||
# multi-user-basic: Multi-user with BasicAuth pass-through (credentials in request headers)
|
||||
# oauth: Uses OAuth2/OIDC (experimental, requires patches)
|
||||
# login-flow: Multi-user via Nextcloud Login Flow v2 (experimental, ADR-022)
|
||||
mode: basic
|
||||
|
||||
# Basic authentication settings (single-user mode)
|
||||
@@ -139,6 +140,21 @@ auth:
|
||||
# Use existing PVC
|
||||
existingClaim: ""
|
||||
|
||||
# Login Flow v2 settings (experimental, ADR-022)
|
||||
# Uses Nextcloud's native Login Flow v2 to obtain app passwords per user.
|
||||
# No OAuth patches required — works with stock Nextcloud.
|
||||
# See: docs/ADR-022-deployment-mode-consolidation.md
|
||||
loginFlow:
|
||||
# Token encryption key (required, ignored if existingSecret is set)
|
||||
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||||
tokenEncryptionKey: ""
|
||||
# Token storage database path
|
||||
tokenStorageDb: "/app/data/tokens.db"
|
||||
# Use existing secret instead of creating one
|
||||
existingSecret: ""
|
||||
# Key in the existing secret
|
||||
tokenEncryptionKeyKey: "token_encryption_key"
|
||||
|
||||
# Data Storage Configuration
|
||||
# Persistent volume for /app/data directory
|
||||
# Used for: token databases, qdrant persistent storage, and any app data
|
||||
@@ -147,6 +163,7 @@ dataStorage:
|
||||
# Enable persistent storage for /app/data
|
||||
# Set to true when using:
|
||||
# - Multi-user basic auth with offline access (stores tokens.db)
|
||||
# - Login flow mode (stores app passwords in tokens.db)
|
||||
# - Qdrant persistent mode (stores vector database)
|
||||
# - Any feature requiring persistent app data
|
||||
# Set to false for basic auth without persistence (uses emptyDir)
|
||||
|
||||
Reference in New Issue
Block a user