Nextcloud SAML/OIDC: 8 common SSO errors and fixes

Nextcloud offers two apps for single sign-on: SSO & SAML authentication (user_saml) for SAML 2.0 and the OpenID Connect user backend (user_oidc) for OIDC. Both work reliably — as long as Nextcloud, the reverse proxy and the identity provider agree on URLs, time and user IDs. Almost every SSO ticket comes down to one of those three.

First: know the emergency exit

Before touching the SSO configuration, make sure you can get in without SSO. https://cloud.example.com/login?direct=1 shows Nextcloud's classic login form, so a local admin can still sign in when the identity provider is down. Test it beforehand and you will save yourself a lot of stress.

1. Redirect loop behind the reverse proxy

Symptom: After logging in at the IdP the browser bounces endlessly between Nextcloud and the IdP, or the IdP reports an invalid return URL.

Cause: Nextcloud runs behind a proxy that terminates TLS and therefore generates http:// URLs or the wrong hostname. The Assertion Consumer Service URL (SAML) or redirect URI (OIDC) no longer matches what is configured at the IdP.

Fix: In config.php set overwriteprotocol to https, overwrite.cli.url to the public URL and add the proxy to trusted_proxies. Then check the expected endpoints: for SAML /apps/user_saml/saml/acs (metadata at /apps/user_saml/saml/metadata), for OIDC /apps/user_oidc/code.

2. Clock skew

Symptom: Sporadic or permanent “assertion expired” or “not yet valid” errors, even though the configuration is correct.

Cause: SAML assertions and OIDC tokens have tight validity windows. A few minutes of drift between the Nextcloud server and the IdP is enough.

Fix: Enable NTP on both sides and check with timedatectl. In containers, the host's clock is what counts.

3. The IdP certificate was renewed

Symptom: From one day to the next every login fails with a signature error.

Cause: The IdP rotated its signing certificate, but Nextcloud still has the old X.509 certificate.

Fix: Copy the current certificate from the IdP metadata. Many IdPs publish the new certificate before the switch — if you know both dates, you plan the rotation instead of discovering it.

4. UID mapped to the wrong attribute

Symptom: After a name or e-mail change, a user logs in and finds an empty, brand-new account.

Cause: A mutable attribute, such as the e-mail address, was mapped as the unique user ID. When it changes, Nextcloud creates a new account.

Fix: Use an immutable attribute from the start — the sub claim for OIDC, a fixed ID such as the directory object ID for SAML. Changing the mapping later is a migration, not a setting: back up the data and shares of affected accounts first.

5. Account missing — or created twice

Symptom: “Account not provisioned”, or a login without access to existing data, when LDAP or local accounts are also involved.

Cause: It is unclear which backend provides the users. With SAML, Nextcloud can create accounts itself or only admit users that already exist in another backend (e.g. LDAP).

Fix: Define a single source of truth and set the “only allow existing accounts” option deliberately. The mapped UID must match the UID in the other backend exactly — including case.

6. OIDC: provider not reachable

Symptom: An error fetching the discovery URL when creating the provider or logging in.

Cause: The Nextcloud server itself must be able to reach the IdP's /.well-known/openid-configuration. Nextcloud blocks internal IdPs on private IP addresses by default, and firewalls or a proxy without an exception get in the way.

Fix: Test from the server with curl. For an IdP on the internal network set 'allow_local_remote_servers' => true in config.php — deliberately and documented, as the option affects other features too. Providers can be managed in scripts with occ user_oidc:provider.

7. Groups don't arrive

Symptom: Login works, but group shares or admin rights are missing.

Cause: The IdP does not send a groups claim or attribute, or the name in the mapping is wrong.

Fix: Use a browser add-on like SAML-tracer (or the decoded ID token for OIDC) to see what actually arrives, and align the mapping with that — not the other way round.

8. Logout doesn't log out everywhere

Symptom: After logging out of Nextcloud you are logged straight back in on the next click.

Cause: Only the Nextcloud session ended; the session at the IdP is still active. That is expected SSO behaviour, but it is often reported as a bug.

Fix: Configure single logout or the IdP's logout URL if a full logout is required — and explain to users what “log out” means in an SSO environment.

Checklist for the next SSO ticket

Emergency login via /login?direct=1 tested?
Public URL, overwriteprotocol and trusted_proxies correct?
ACS URL or redirect URI at the IdP identical to Nextcloud?
Time in sync on Nextcloud and the IdP?
Current IdP certificate configured?
UID mapped to an immutable attribute?
Actual attributes/claims checked with SAML-tracer or a token decoder?
For analysis, temporarily set loglevel 0 and read nextcloud.log — then reset it.

Most SSO problems aren't bugs but two systems disagreeing about a detail. Check URLs, time and IDs systematically and you usually find the cause in minutes instead of hours.