Nextcloud with SAML and OIDC: 8 errors that keep showing up in support

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.