Keycloak and Nextcloud SSO integration

The sign-in flow is an OpenID Connect authorization code exchange in which Keycloak handles the password and any second factor, and Nextcloud only receives the result. When a user opens Nextcloud, the user_oidc app redirects the browser to the Keycloak realm's authorization endpoint with the Nextcloud client ID and a redirect URI pointing back to Nextcloud. The user authenticates in Keycloak, which may also enforce MFA, passkeys or a conditional authentication step defined in your realm. Keycloak then sends the browser back to Nextcloud with a short-lived authorization code. Nextcloud, through user_oidc, exchanges that code directly with Keycloak's token endpoint over a back-channel request, which is why the client secret and the token endpoint must be reachable from the Nextcloud server as well as from the browser.

The token response contains an ID token, and usually an access token and a refresh token, depending on the client configuration. Nextcloud reads identity claims from the ID token or the userinfo endpoint, such as the subject, preferred username, email and any group claim you have mapped. The user_oidc app uses these claims to create a local Nextcloud account on first sign-in or update attributes on later sign-ins. Group membership is only synchronized if the claim is present and the app is configured to read it, so the claim name, its format and its values must match what the user_oidc settings expect. Mismatches here are the most common cause of users who log in successfully but land with no group rights.

Bearer token validation is a separate path from browser sign-in. Desktop and mobile sync clients, and scripts that call Nextcloud APIs, present an access token in the Authorization header. Nextcloud must then validate that token against Keycloak, typically by checking its signature against the realm's published keys or by calling an introspection endpoint, and confirm the audience and expiry. Decide which clients will use bearer tokens, which scopes they need and whether you want Nextcloud to accept tokens issued to other clients. Confirm in the user_oidc documentation for your installed version which validation methods it supports and how it is enabled, because this behavior has changed between releases.

Backchannel logout is the path that ends Nextcloud sessions when a user logs out of Keycloak or an administrator revokes a session. Keycloak sends a signed logout token as a direct server-to-server request to a logout endpoint registered for the Nextcloud client, so the Nextcloud server must be reachable from Keycloak, and that endpoint must be enabled in the user_oidc settings and the Keycloak client. Browser-based front-channel logout is a different mechanism and depends on the browser. Plan for the case where a session is not terminated because the backchannel request failed, and decide how long you accept that exposure. Keycloak 26.8 upgrade notes state that backchannel logout tokens from external providers must have their signatures validated, so confirm how your Nextcloud and user_oidc versions handle this before relying on it.

Before go-live, verify the redirect URI, callback path, logout endpoint and token settings against the user_oidc documentation for the exact Nextcloud and app versions you run, since these paths and option names are version-specific. Confirm the access token lifetime, refresh behavior and whether refresh tokens are issued to the Nextcloud client. Test a full sign-in, a token-based API call, a sign-out from Keycloak and an administrator-forced session revocation, and record which step fails and why. These checks identify configuration errors early and show who owns each part of the flow: the realm, the client, the Nextcloud server and the network path between them.

The first decision is whether a successful Keycloak sign-in should create a new Nextcloud account or attach to an account that already exists. Creating from the token means the first login builds a local Nextcloud user from the claims in the token. Linking means the sign-in is matched to a user that already came from a directory, either through Nextcloud's LDAP app, which lets LDAP and Active Directory users log in with their directory credentials, or through the LDAP or Active Directory user federation that Keycloak documents. If both paths feed the same person, the wrong setting produces a second account for one employee, with its own files, shares and group memberships. Before enabling soft provisioning, confirm in the current user_oidc and Nextcloud LDAP documentation how each product matches an incoming identity to an existing user.

Duplicate accounts usually come from identifiers that differ between sources. Keycloak may import the directory username as the federated username, while the token carries an email address or a preferred username from another source, and Nextcloud may key users on a different attribute again. Choose one authoritative identifier for each person, ideally an attribute that does not change when a person's name or email changes, and map it consistently in Keycloak's attribute mappers and in Nextcloud's LDAP attribute settings. Then test the mapping with three cases: a directory user signing in for the first time, a user who exists in Keycloak but not in the directory, and a user whose email address changed in the directory after their first sign-in. Use test accounts created for this purpose, and record which account each login resolved to.

Group membership is the second source of conflict. A person can receive groups from the directory through Keycloak's federation mappers, from Keycloak-local group assignments, and from a groups claim in the token. Nextcloud can also sync groups directly from LDAP. When two sources assign the same group, or when one source removes a membership the other still asserts, the result depends on which sync runs last. This matters most for groups that grant administrator rights, group folder access or storage quotas. For each Nextcloud group, decide which system owns its membership and make sure the other sources do not write to it.

Before turning on soft provisioning, write a short ownership table that lists each attribute and group that Nextcloud stores for a user, such as username, email, display name, group membership, quota and admin rights, and name the system that owns each one. Keycloak, the directory and Nextcloud should each write only the attributes they own. Then verify the behavior that matters most: a disabled directory account should lose access to Nextcloud, a deleted group should stop granting access, and a changed attribute should update in the place the table names as the owner. Confirm each of these against the sync and disable settings in the versions you run, because account lifecycle behavior differs between LDAP-backed and token-created users.

Before go-live, the team should run a scripted test plan that proves the Keycloak and Nextcloud integration does what the design says for each identity path. Sign-in working once is not enough. The tests need to cover first sign-in, returning users whose group membership has changed, removed users, existing LDAP users under soft provisioning, API calls that carry a bearer token, and logout started in Keycloak. Each test should have a named owner, a pass condition written before the run, and a place to store evidence. Agree on this plan with the security team before the first test runs, because the same plan is what you will repeat later.

Start with first sign-in. Create a test user in the Keycloak realm that carries the group claims your mapping expects, sign in to Nextcloud through the user_oidc login, and confirm that the account appears with the expected display name, email address and group memberships. Then repeat for a returning user whose Keycloak group membership changed since the last sign-in. The pass condition is that Nextcloud reflects the current groups, not the groups from the first login, and that any group the user lost no longer grants access. Next, disable or delete a test user in Keycloak and confirm what Nextcloud does on the next sign-in attempt and on any scheduled sync. Record the behavior exactly, because it is the behavior your offboarding process will depend on.

For an existing LDAP user under soft provisioning, sign in with the directory credentials and confirm that Nextcloud links the account to the OIDC identity without creating a duplicate user. Check that the stored user ID, the attribute mapping and the group membership match what the directory and the Keycloak token say. For bearer tokens, obtain an access token for a client that is allowed to call a Nextcloud API, send a request with the Authorization header, and confirm that the request is accepted. Then send an expired token and a token whose audience or issuer does not match, and confirm that each is rejected. These checks depend on the token validation settings you chose, so confirm them against the user_oidc documentation for your release rather than from memory.

Logout is the test most often skipped. Start a Nextcloud session through Keycloak, then end the Keycloak session from the Keycloak account console or an admin action, and confirm that the Nextcloud session is terminated on the next request or after the backchannel logout message is processed. Verify that the backchannel logout endpoint is reachable from Keycloak and that signature validation of logout tokens is enabled, which the Keycloak 26.8 upgrade notes make mandatory for tokens from external providers. Keep the evidence for every test. Store token samples with the signature, client secret, refresh token and personal data removed, but keep the header, the claim names, the expiry and the audience so a reviewer can see what was checked. Save the Nextcloud log entries for each sign-in and rejected request, and record a dated export of the Keycloak client settings for the Nextcloud client, including redirect URIs, mappers and logout URI.

Repeat the same test plan after every Keycloak minor release and after every Nextcloud major upgrade. Keycloak plans four minor releases a year, and Nextcloud publishes a new major version every four months, so the schedule matters for budgeting the retest effort. Each rerun should use the same users, the same expected results and the same evidence format, so differences are easy to see. Treat a changed result as a finding to resolve before the upgrade is accepted, and do not assume that a passing sign-in means provisioning, token checks and logout still work. Ask any partner quoting this work to show how the retest is scoped, who runs it, and whether it is covered by a retainer or billed for each upgrade.