Integrations · OIDC

Nextcloud SSO

Configure Nextcloud to authenticate users via Clavex using the user_oidc app. Supports automatic account provisioning, quota assignment, group membership, and avatar synchronisation from Clavex claims.

Prerequisites

Nextcloud ≥ 22 with the user_oidc app installed (recommended) or the sociallogin app
Nextcloud admin access
Clavex at https://id.acme.eu, org slug acme

Recommended app: Use the official user_oidc app by Nextcloud GmbH — it supports discovery, PKCE, and full claim mapping. The sociallogin app is a fallback for older Nextcloud versions.

Step 1 — Install user_oidc

bash

# Via Nextcloud app store (recommended) # Admin panel → Apps → Search "OpenID Connect user backend" → Install
# Or via occ CLI $ php occ app:install user_oidc $ php occ app:enable user_oidc

Step 2 — Register OIDC Client in Clavex

Admin API (curl)

$ curl -X POST https://id.acme.eu/api/v1/organizations/acme/clients \ -H 'Authorization: Bearer $ADMIN_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "nextcloud", "client_name": "Nextcloud", "grant_types": ["authorization_code", "refresh_token"], "redirect_uris": ["https://nextcloud.acme.eu/apps/user_oidc/code"], "scopes": ["openid", "profile", "email", "groups"], "token_endpoint_auth_method": "client_secret_basic" }'

Step 3 — Configure user_oidc in Nextcloud Admin

Go to Admin Settings → OpenID Connect

Click Add provider and fill in:

Field	Value
Identifier	`clavex`
Client ID	`nextcloud`
Client secret	`cs_xxxxxxxxxxxxxxxx`
Discovery endpoint	`https://id.acme.eu/acme/.well-known/openid-configuration`
Scope	`openid profile email groups`

Expand Attribute mapping:

Nextcloud attribute	Clavex claim
User ID	`sub`
Display name	`name`
Email	`email`
Quota	(leave empty or map from custom claim)
Groups	`groups`

Enable Use PKCE (recommended)
Click Save

Step 4 — Configure via occ CLI (alternative)

bash

$ php occ user_oidc:provider clavex \ --clientid="nextcloud" \ --clientsecret="cs_xxxxxxxxxxxxxxxx" \ --discoveryuri="https://id.acme.eu/acme/.well-known/openid-configuration" \ --scope="openid profile email groups" \ --mapping-uid="sub" \ --mapping-displayname="name" \ --mapping-email="email" \ --mapping-groups="groups" \ --pkce=1

Step 5 — Disable Local Login (optional)

Once SSO is working, disable password-based login to enforce Clavex as the only auth method:

bash

# Disable local password login for non-admin users $ php occ config:app:set --value=0 user_oidc allow_multiple_user_backends

Troubleshooting

Symptom	Cause	Fix
Login button not shown on Nextcloud login page	user_oidc app not enabled or no provider configured	Run `php occ app:enable user_oidc` and verify provider list
`Error: The provided code is not valid`	Redirect URI mismatch	Ensure redirect URI in Clavex matches `/apps/user_oidc/code` exactly
Groups not syncing	`groups` scope not requested or claim not included	Verify scope includes `groups`; ensure Clavex client is configured to return groups claim
Duplicate user accounts	User ID claim changed (e.g. email vs sub)	Always use `sub` as the User ID — it is stable and unique across sessions
SSL certificate error	Nextcloud can't verify Clavex cert	Add Clavex CA to Nextcloud's trusted certs: `php occ security:certificates:import clavex-ca.crt`