Nextcloud SSO: signing in through an OpenID Connect provider

Nextcloud signs users in through an OpenID Connect provider with the OpenID Connect user backend app, usually called user_oidc. Once it is configured, users sign in to Nextcloud with their identity provider account, and the provider's groups can become Nextcloud groups.

The setup is mostly command line, but it is short: create an application in the identity provider, install user_oidc, register the provider with the occ command, and verify the claim mapping.

What you need

• A Nextcloud instance where you can run occ as the web server user (typically www-data).
• HTTPS on Nextcloud and the identity provider.
• An identity provider where you can create an OIDC application: Casdoor, Keycloak, Entra ID, Okta or authentik.

Step 1: create the application in the IdP

Create an application for Nextcloud and add its callback URL:

https://cloud.example.com/apps/user_oidc/code

If your Nextcloud installation uses /index.php in URLs, use:

https://cloud.example.com/index.php/apps/user_oidc/code

Note the client ID and client secret. If the provider lets you choose how groups are formatted, use a plain group name rather than a full path, so Nextcloud receives finance instead of my-org/finance.

With Casdoor, set Token group format to Name (group) on the application's OIDC/OAuth tab, and keep the default JWT token format: user_oidc reads the user's attributes from the ID token, and the default format carries the groups there.

Step 2: install the app

Install OpenID Connect user backend from the Nextcloud app store, or run:

sudo -u www-data php occ app:install user_oidc

Step 3: register the provider

From the Nextcloud directory, run the provider command. The example below uses Casdoor; the same fields apply to any provider.

sudo -u www-data php occ user_oidc:provider Casdoor \
  --clientid="<your-client-id>" \
  --clientsecret="<your-client-secret>" \
  --discoveryuri="https://door.example.com/.well-known/openid-configuration" \
  --scope="openid email profile" \
  --unique-uid=0 \
  --mapping-uid=name \
  --mapping-display-name=displayName \
  --mapping-email=email \
  --mapping-groups=groups \
  --group-provisioning=1

The options that matter most:

• --discoveryuri points at the provider's discovery document. user_oidc reads the authorization, token, userinfo and issuer endpoints from it.
• --unique-uid=0 uses the mapped user ID as the Nextcloud user ID. Without it, Nextcloud stores a hash of the provider and user ID, which makes accounts hard to recognize.
• --mapping-uid=name maps the Casdoor username claim. In Casdoor's default ID token, name is the username and displayName is the display name.
• --group-provisioning=1 creates Nextcloud groups from the groups claim and keeps memberships in sync at each sign-in.

What the provider sends

With Casdoor's default JWT token format, the ID token contains:

If you switch the Casdoor application to JWT-Standard, the ID token uses the standard names instead (preferred_username for the username and name for the display name) and leaves out groups. Change the mappings accordingly and turn off group provisioning.

For Keycloak, the username claim is usually preferred_username and groups arrive under groups or a custom mapper. For Entra ID, check the app's token configuration for the groups claim and its overage behavior.

Step 4: verify and make it the default

Open Nextcloud in a private window. The sign-in page should show Log in with Casdoor (or the provider name you registered). Sign in and check:

• The account name matches the mapped username.
• The email and display name are populated.
• The user's groups appear under Users in the Nextcloud admin settings.

With one provider configured, you can send everyone straight to it:

sudo -u www-data php occ config:app:set --type=string --value=0 user_oidc allow_multiple_user_backends

Administrators can still reach the local sign-in form by adding ?direct=1 to the sign-in URL, which is useful for a local admin fallback.

Troubleshooting

FAQ

Does Nextcloud support SAML? Nextcloud has a separate user_saml app for SAML. This guide is for OIDC; if your provider only speaks SAML, use user_saml or put a broker in front that exposes OIDC.

Can I keep local Nextcloud accounts? Yes, but plan the fallback carefully. Keep a local admin, document it, and do not let the SSO configuration lock you out of the admin account.

How do I map IdP groups to Nextcloud groups? Use --mapping-groups and --group-provisioning=1. The provider must send the groups claim in the ID token or userinfo response.

Can I configure more than one provider? user_oidc supports multiple providers, but managing several back-ends adds ambiguity. If you need multiple IdPs, put a broker in front and expose one OIDC connection to Nextcloud.

If you need an identity provider for Nextcloud and the rest of your self-hosted stack, Casdoor supports OIDC, SAML, CAS, LDAP and SCIM. Casdoor Cloud starts at $6.67/month billed yearly for a dedicated instance. See the Casdoor Nextcloud guide for the exact values.