Keycloak and Nextcloud SSO integration

The first question is which protocol your organization already standardizes on in Keycloak. Keycloak supports OpenID Connect, OAuth 2.0 and SAML 2.0, and Nextcloud documents both an OpenID Connect user authentication backend and a SAML app. Either can provide browser sign-in for the Nextcloud web interface, so the decision should rest on what your Keycloak realm already runs for other applications. Export the list of existing clients, note which ones use OpenID Connect and which use SAML, and identify the team that owns those client definitions. Adding a second protocol only for Nextcloud means one more client type, one more set of certificates or keys to rotate, and one more configuration for your administrators to document and maintain.

The second question is whether API clients and desktop or mobile sync clients need token-based access. Nextcloud's sync clients and mobile apps authenticate differently from a browser, and integrations that call the Nextcloud APIs usually expect bearer tokens. Before choosing, list every client type that will connect, including scripts, third-party tools and the official sync clients, and confirm in the current Nextcloud app documentation how each one authenticates against the protocol you are considering. If token validation for API calls is a requirement, verify that the option you pick supports it for your Nextcloud version, and test that path with a non-browser client before you commit to the design.

The third question is how group claims will arrive. Group mapping decides which users receive which Nextcloud group memberships, and therefore which shares, quotas and app permissions they get. Check what Keycloak can place in the token or assertion for your chosen protocol, how group names are formatted, and whether nested groups need flattening. Decide early whether Keycloak groups or the directory remains the source of truth, and keep LDAP for sharing lookups if your users need to find colleagues in the share dialog. Write down the claim names, the attribute mapping and the expected group list for a test user, so the verification step has a clear baseline.

The fourth question is who maintains the app after upgrades. Nextcloud releases a new major version every four months, and its upgrade guidance requires moving one major version at a time, backing up before each upgrade and disabling third-party apps until they are confirmed compatible. An authentication app is a third-party app that must stay compatible with each Nextcloud release, so it belongs on your upgrade checklist. Name the owner of the app, the owner of the Keycloak client settings and the person who tests sign-in after each upgrade. Confirm the choice against the current app documentation and the Nextcloud version you plan to run before the build starts.

Sign-in and directory lookups are separate jobs, and an SSO design should decide who does each one before any configuration starts. Keycloak handles authentication: it checks a user's password or session and issues the tokens or SAML assertions that Nextcloud trusts. The share dialog, group selectors and the sharing autocomplete need a list of people and groups that Nextcloud can search. Nextcloud's LDAP app can supply that list from Active Directory or another LDAP directory, and it can also let directory users sign in with their directory credentials. Those two capabilities do not have to be bundled, so the team needs to decide which one it wants from LDAP.

There are three practical options. LDAP can stay as a read-only source for the sharing lookups only, with Keycloak handling every login. LDAP can supply group membership that Nextcloud uses for quotas, group folders and access rules, while Keycloak handles login and provisioning. Or LDAP can keep both roles. Each option has a different cost. Keeping LDAP for lookups alone means Nextcloud may hold two records for the same person, one created by the SSO backend on first login and one read from the directory, and the team must agree on how those records are matched. Keeping LDAP for groups means group membership has two possible owners, so a group change in Keycloak may not reach Nextcloud in the expected order. Keeping LDAP for both means the directory may remain the source of truth for credentials even though sign-in appears to run through Keycloak, which weakens the reason for adding Keycloak.

The most important decision is which system is authoritative for disabling accounts. If a leaver is disabled in Keycloak, Nextcloud sign-in should fail at the next token or session check. However, the user may still appear in the sharing dialog because the LDAP lookup reads the directory, where the account might still be enabled. That gap is a data exposure risk, since a former employee or contractor could still be selected as a share recipient and a file could be shared with a person who should no longer have access. The reverse gap also exists if the directory is disabled but a Keycloak account remains active. Write down, for each identity attribute and each lifecycle event, which system changes first and which system the other one follows.

Confirm two things before design sign-off. First, check how the LDAP app and the chosen SSO app coexist on the Nextcloud version you plan to run, including how each handles user creation, display names, and group sync, and whether a directory account that is disabled still resolves in the lookup. Settings and behavior differ between releases, so verify this against the documentation for your exact version rather than assuming it. Second, test deprovisioning explicitly. Create a test account in the directory and in Keycloak, sign in, share a file, then disable the account in each system in turn and record whether sign-in stops, whether the user disappears from the share dialog, and whether existing shares remain. Repeat the test for group removal and for a deleted account. Treat any case where the user remains selectable as a defect to fix before go-live.

Ask the implementation partner to document the chosen LDAP role in the design record, along with the attribute used to match identities, the sync interval for lookups and groups, and the runbook steps for a leaver. Those answers determine the test cases, so they should be settled before the build begins.

Browser sign-in and API or client access are separate paths, and the team has to decide how each non-browser client authenticates before the Keycloak integration goes live. A browser user signs in through Keycloak and receives a Nextcloud session. Desktop sync clients, mobile apps and scripts usually do not carry that session, so they need either a token issued by Keycloak that Nextcloud accepts or a credential that Nextcloud issues to the client after a login. List every client type your organization uses, including older builds, WebDAV scripts and third-party tools, because each one may behave differently. For each type, decide whether it authenticates through Keycloak, through a Nextcloud-issued credential, or not at all.

Where clients present Keycloak-issued bearer tokens to the Nextcloud API, the Nextcloud side has to validate each token before it grants access. Ask the chosen app which checks it performs: signature verification against Keycloak's published keys, issuer, expiry, and the audience or client identifier the token was issued for. Confirm whether the app validates tokens locally or asks Keycloak to introspect them, because that choice changes how quickly a revoked token stops working. Scopes need the same attention. Decide which Keycloak scopes allow file reads, writes and sharing, and confirm whether Nextcloud enforces scopes or only checks that a token is valid. Verify these behaviors against the documentation for your Nextcloud version, since the exact options depend on the app and release.

Token lifetimes determine how sync clients behave. Access tokens are typically short, so a client that runs unattended depends on its refresh token to keep syncing. Set the access token lifetime, refresh token lifetime and session idle and maximum limits in the Keycloak realm, then test a laptop that sleeps overnight, a phone that loses network access for a day, and a script that runs on a schedule. Confirm whether each client refreshes silently, prompts the user to sign in again, or fails. Ask each client vendor how it stores tokens and whether it picks up lifetime changes made in Keycloak. Longer lifetimes reduce sign-in prompts but extend the period in which a stolen token remains usable, so record that trade-off as a decision with your security owner.

Disabling a user needs its own test because Keycloak and Nextcloud can hold separate state. Disabling the account in Keycloak stops new sign-ins, but tokens already issued may keep working until they expire unless the app checks token status with Keycloak or sessions are revoked. Nextcloud may also keep the local account record until its user backend syncs or the account is disabled there. Run a test in which a disabled user has an active desktop client, a mobile session and a script token, and record how long each keeps access. Confirm the expected behavior with the documentation for your app and version, and agree a maximum acceptable window with your security team. Test LDAP-based sharing lookups separately, since directory lookup and token validation are different checks that each need their own verification.