How XWiki Keycloak OpenID Connect SSO works for teams that already run Keycloak
If your organization already runs Keycloak and wants XWiki users to sign in with those existing accounts, the xwiki-contrib OpenID Connect extension is the component that handles it. It authenticates XWiki users against an external OpenID Connect provider such as Keycloak, so XWiki no longer needs to hold the password for each person who uses the wiki. The extension is an open source project maintained in the xwiki-contrib repositories. It is not a Keycloak feature, and it is not part of the XWiki core product, so it has its own configuration, its own release history and its own compatibility notes that you need to check separately from both products.
The login flow works in plain steps. A user opens an XWiki page that requires login and XWiki redirects the browser to the Keycloak sign-in page for the configured realm. After the user authenticates, Keycloak redirects the browser back to XWiki with an authorization code. XWiki then exchanges that code with Keycloak for tokens and reads the identity claims from them, usually the subject and the user's name and email. The extension then looks for an existing XWiki user that matches those claims. If one exists, the session is established for that user. If none exists, the extension can create a new XWiki account on first login, depending on how it is configured. Keycloak remains the place where passwords, multi-factor authentication and account disablement are managed.
Several decisions follow from this flow and should be made before any configuration starts. First, decide which claim XWiki uses to match an account, because changing it later can leave duplicate or orphaned wiki users. Second, decide whether first-time users should be created automatically or provisioned by an administrator, since that determines who can get a wiki account at all. Third, decide how Keycloak groups or roles will reach XWiki, if you need group-based rights. Each of these depends on the claims your Keycloak realm actually emits and on the extension version you run with your XWiki release.
Because the extension is community-maintained, confirm its exact capabilities against its own documentation for the XWiki version you run. Check which options exist for account matching, automatic user creation, group handling and logout, and whether they behave the same on the stable, LTS and intermediate LTS lines. Test the flow in a non-production XWiki instance against a Keycloak realm that mirrors production, including a user who already has a wiki account and a user who does not. Record which claims arrive, which account is matched and what the browser does at each redirect. That test result is the basis for the scope discussion with your team or any implementation partner.
What you need in place before configuring XWiki and Keycloak SSO
Six checkpoints must be settled before you change any XWiki or Keycloak configuration: the XWiki line and image variant, the Keycloak release and production database, how Keycloak is deployed, the network paths between the systems, and the extension version. The XWiki line comes first because it determines which extension release you can use.
XWiki release line and image variant
Choose the XWiki line before anything else. The stable, LTS and intermediate LTS lines are all options. At research time the official Docker tags were 18.8.0 for stable, 17.10.14 for LTS and 18.4.7 for the intermediate LTS, so confirm the current tags before you pin one. Official images come in MySQL, PostgreSQL and MariaDB variants running on Tomcat, so match the variant to your database standard.
Keycloak release and admin access
Use a currently supported Keycloak release. At research time the current release was 26.8.1, published October 13, 2026. Minor releases ship several times a year, and breaking changes in minor releases are opt-in. Confirm that an administrator can sign in to the admin console, work in the target realm and create clients there. Without that access, the OpenID Connect client cannot be configured.
Keycloak production database
Keycloak supports PostgreSQL 14 to 18 for production, along with other enterprise databases. The default development file database is for development only, so a test instance must never become the production identity store. Confirm the database version, backup routine and network connectivity from Keycloak before enabling SSO. Keycloak migrates its schema at startup by default, so decide whether that suits your change process or whether you will apply the migration manually.
Keycloak on Kubernetes
If Keycloak runs on Kubernetes, install it through the Keycloak Operator. The recommended method uses Operator Lifecycle Manager, with kubectl or an experimental Helm chart as alternatives. The Operator can also manage a KeycloakOIDCClient resource, which lets you define the XWiki client as code. Keycloak's Operator documentation strongly recommends manual approval mode for operator updates, so upgrades do not run unannounced against live XWiki sign-in.
HTTPS and endpoint reachability
XWiki must be served over HTTPS at the address users type, because the redirect and callback addresses in the OpenID Connect flow depend on it. The XWiki server must reach Keycloak's token and discovery endpoints directly, and user browsers must reach the Keycloak login page. Check DNS, firewall rules, reverse proxies and certificate trust along both paths before configuration starts, and confirm the exact callback format in the extension documentation.
Extension compatibility with XWiki
The xwiki-contrib OpenID Connect extension is the authenticator this topic uses. Its release must be compatible with the XWiki line you chose. Confirm this in the xwiki-contrib/oidc project before installation, including which XWiki versions each extension release targets and which Keycloak settings it expects. Record the extension, XWiki and Keycloak versions together in your change record so that future upgrades can be checked against the same matrix.
How to configure the XWiki OIDC extension against a Keycloak realm, step by step
This sequence connects an XWiki instance to a Keycloak realm through the xwiki-contrib OpenID Connect extension, from realm and client setup to a verified login. Each step closes with a check that the next step depends on. The result is an XWiki that sends users to Keycloak for sign-in and creates their profile on first login.
Create a dedicated Keycloak realm
The platform team, working with whoever administers Keycloak, creates a dedicated realm for XWiki or selects an existing one reserved for it and the users who need access. Keep the realm's login policy, password rules and user sources separate from other applications, so a change made for one service does not affect the others. Record the realm name and its issuer URL, because later steps depend on both. Done when the realm's OpenID Connect discovery document loads in a browser from the network segment where XWiki runs.
Create a confidential OpenID Connect client
In the realm, create an OpenID Connect client for XWiki and turn on client authentication so that it is confidential. Set the valid redirect URI to the callback URL that the xwiki-contrib OIDC extension documentation gives for your XWiki version and base address, and use HTTPS. Limit web origins to the XWiki address only. Check the client settings page: client authentication is on, the standard authorization code flow is enabled, and the redirect URI matches your XWiki address exactly.
Store the client secret in a secrets store
Generate the client secret from the client's credentials tab in Keycloak and copy it into your organization's secrets store, such as a vault your platform team already operates. Restrict read access to the XWiki deployment identity and the few people who maintain its configuration. Keep the secret out of tickets, chat threads and wiki pages. Done when the process that will configure XWiki can retrieve the secret from the store, and the stored value matches the one shown in Keycloak.
Install the xwiki-contrib OIDC extension
Install the xwiki-contrib OpenID Connect extension on the XWiki instance using the packaging method your installation uses, following the extension documentation. Confirm that the extension version is compatible with your XWiki release, since the project documentation lists supported combinations. Restart XWiki if the installation requires it. Done when the extension appears in the installed extensions list and the OpenID Connect authenticator is available in the XWiki configuration.
Set the discovery endpoint and client credentials
Enter the realm's discovery endpoint, which follows the standard OpenID Connect form ending in the well-known configuration path, along with the client ID and the client secret read from the secrets store. Where your deployment allows it, inject the secret at deployment time instead of typing it into the administration interface. Check that XWiki fetches the discovery document and that its logs show no client authentication errors. If the discovery request fails on certificate trust, fix trust between XWiki and Keycloak before continuing.
Test login with a non-admin account
Sign in with a non-admin Keycloak test account that belongs to the group expected to use XWiki. The browser should go to the Keycloak login page, return to the XWiki callback address, and land on a logged-in page. Confirm that XWiki created a user profile matching the Keycloak username and email, and that the account holds only the rights you expect. Sign out and check that the session ends as the logout section describes. Record the results so later tests follow the same path.
Which Keycloak claims and groups map to XWiki users and groups
This table compares each identity attribute and group decision between Keycloak tokens and XWiki accounts. Read each row as a question to settle before configuring the client, starting with the stable user identifier. The main takeaway is that identity and group claims can be mapped, but administrative rights should stay under XWiki administrator control. Exact claim names and mapping options must be confirmed in the extension configuration reference.
| Mapping item | What to map from Keycloak | Decision or check before go-live |
|---|---|---|
| User identifier | Keycloak subject or username claim, used to match the XWiki user ID. Confirm which claim the extension reads. | Choose a stable identifier. Renaming usernames in Keycloak can leave wiki accounts unmatched. |
| Email, first and last name | Standard profile claims for email, given name and family name, emitted by the client scope. | Test with a sample user. Missing claims leave profile fields blank in XWiki. |
| Groups to XWiki groups | A groups claim built from Keycloak group membership, mapped to XWiki group names. | Keycloak group names should match the XWiki groups that control space access. Check how nested groups are flattened. |
| Groups scope or protocol mapper | A group membership mapper added to the client scope so groups appear in the ID or access token. | Confirm in the extension reference which token carries the claim and whether the mapper must be in the default scope. |
| Administrator and wiki-owner rights | No mapping from claims. Administrator and wiki-owner rights are assigned inside XWiki by an administrator. | Token claims should never grant these rights, because users or self-service attributes could influence them. |
| Profile creation on first login | Whether a XWiki user profile is created automatically at first sign-in. | Automatic creation simplifies onboarding but creates accounts for every Keycloak user who can sign in. Confirm the setting name in the reference. |
| Users who lose group membership | Removal of a mapped group in Keycloak, which should be reflected in XWiki at the next login. | Test whether the extension removes group memberships or only adds them. If it only adds, plan a periodic review of stale access. |
What logout does across XWiki and Keycloak sessions
Signing out of XWiki ends the XWiki session in that browser, but it does not automatically end the Keycloak session. Keycloak keeps its own single sign-on session cookie, so a user who signs out of XWiki and then opens XWiki again may be sent to Keycloak and signed back in without a password prompt. This is normal OpenID Connect behavior, but it is not the behavior most people expect from a sign-out button. Decide before go-live whether that gap is acceptable for your users and your risk appetite, because it changes what the security team should expect to see in testing.
Three points need confirmation from the extension documentation, its source code or a test in your own environment. First, check whether the xwiki-contrib OpenID Connect extension calls the end-session endpoint of the Keycloak realm when a user logs out of XWiki. If it does, confirm whether the request includes an id token hint and whether Keycloak then ends the SSO session. Second, confirm how post-logout redirect URIs are configured. Keycloak only redirects to URIs registered on the client, so the XWiki client's valid post-logout redirect URIs must match the page users land on after sign-out exactly. A mismatch usually produces an error page rather than a clean sign-out.
Third, confirm what happens when an administrator disables a user in Keycloak. Disabling the account stops new logins, but an XWiki session that already exists may remain usable until it expires or until the extension checks the user's tokens again. Confirm whether the extension validates tokens on each request or only at login, and how the XWiki session lifetime relates to the token and SSO session lifetimes set in Keycloak. Also check whether revoking the user's sessions in the Keycloak administration console reaches the XWiki session. Test this with a disposable account that has an active session in XWiki.
Test logout in every browser your organization supports, in both normal and private windows, and on a shared workstation where one user signs out and another signs in. For each case, record whether the XWiki session ends, whether the Keycloak session remains, whether the browser back button can show cached XWiki pages, and whether the next user can reach the previous user's account. Then write the expected behavior into a short document for the security team, covering each trigger (user sign-out, idle timeout, account disabled), the resulting XWiki and Keycloak state, the user experience and who owns each check. That record becomes the baseline for future upgrades of XWiki, the extension and Keycloak.
Security settings to decide for XWiki Keycloak SSO
The settings below determine how far a compromised login, token or client can reach. Your team should choose and record each one before XWiki relies on Keycloak for sign-in. Verify every setting against your own threat model and the extension's security notes before go-live.
HTTPS on every endpoint
Serve XWiki, Keycloak and the redirect and issuer URLs over HTTPS, including every Keycloak endpoint that the browser and XWiki call during login, token exchange and logout. Check that the discovery document lists only HTTPS addresses, that certificates chain to a certificate authority your users trust, and that reverse proxies forward the original scheme so XWiki builds correct callback URLs. Plain HTTP in any step of the flow exposes authorization codes and tokens to anyone on the network path.
Confidential client with a rotated secret
Register XWiki as a confidential OpenID Connect client in Keycloak so that the token exchange is authenticated with a client secret. Avoid configuring it as a public client. Store the secret in your secrets manager, limit who can read the XWiki configuration that holds it, and set a rotation schedule with a named owner. Test rotation in a non-production realm first, because a secret change without a coordinated XWiki restart breaks sign-in for every user.
Exact redirect URIs
List each XWiki callback address as a full URI in the Keycloak client, including the host, port and path that the extension uses, and avoid wildcards. Wildcard or broad redirect patterns can let an attacker direct a login response to another application path on the same host. Review the post-logout redirect list separately, since logout targets form a second redirect surface. Confirm the exact callback path in the extension documentation for the version you deploy.
Break-glass local administrator login
Keep at least one XWiki administrator account on a local login that does not depend on Keycloak. If the Keycloak realm, the client secret or the network path fails, this account lets your team repair the SSO configuration. Store its credentials in a sealed, audited location, test the login after go-live, and confirm that the extension leaves local authentication available for administrators in your chosen setup.
Limit access by Keycloak group
Decide which Keycloak groups may sign in to XWiki and configure the extension to enforce that list, so realm users outside it cannot log in. Map Keycloak groups to XWiki groups only where the extension documents the mapping. Check group claims in a test token, confirm that membership changes take effect at the next login, and review nested groups, because a parent group can carry access that you did not intend to grant.
Token lifetimes and login monitoring
Set short access and session lifetimes in the Keycloak realm, and enable brute-force detection so repeated failed passwords lock accounts. Turn on Keycloak event logging for logins, failures and token events, and configure XWiki to record authentication outcomes. Forward both sets of logs to your log platform, then test that a disabled or locked Keycloak user loses wiki access within the lifetimes you chose.
How to test the XWiki Keycloak login path before users depend on it
Start by treating the login path as a set of cases you can run, record and repeat, not as a single sign-in you check by hand. A useful plan covers at least seven cases: a successful login for a standard user, a successful login for a user in each relevant group, a login attempt against a disabled Keycloak account, a login for a user with no group membership, a login with an expired session, a login that fails because the client secret is wrong, and a logout followed by a fresh login. Each case should state the expected XWiki outcome, such as the account created or updated, the groups applied, the access granted or the error shown, so that a failure is unambiguous.
Run these cases on a staging XWiki and a non-production Keycloak realm that mirrors production. The realm should use the same client configuration, the same protocol mappers that emit user and group claims, the same redirect URIs pattern and the same group structure that XWiki maps into its own groups. Confirm with your Keycloak administrator that the test realm's claims match production claims exactly, because a test realm that emits simpler tokens will pass cases that will fail in production. Keep the test users, groups and client secret separate from production values so that test results cannot be mistaken for production evidence.
Some cases need deliberate setup. For the disabled account, disable a test user in Keycloak and confirm that an existing XWiki session and a new login attempt both behave as your security policy requires. For the expired session, shorten the relevant Keycloak session or token lifetime in the test realm only, then confirm what XWiki does when its own session outlives the Keycloak session. For the failed client secret, change the secret in XWiki or in Keycloak, not both, and record the error the user sees and the entry written to the XWiki and Keycloak logs. Confirm the exact session and token settings with the extension documentation for the version you deploy, since these behaviors depend on configuration.
Record each run with the XWiki version, the extension version, the Keycloak version, the realm configuration export, the test user list and the pass or fail result for each case. Store the record where your change and audit teams can find it. Repeat the full set after any XWiki upgrade, after any change to the OpenID Connect extension, and after each Keycloak minor release, because minor releases can change defaults and the project states that breaking changes in a minor release are opt-in. Check the Keycloak upgrading guide and backwards compatibility notes for the target release before you run the repeat cycle, and treat any changed claim or redirect behavior as a reason to re-test every case, not only the ones you expect to be affected.
Decide before the first run who signs off on a pass, who can approve a production change when a case fails, and what evidence is retained. Agree with your team whether you will test on an XWiki instance built from the same official image tag you plan to run in production, since the official images are published by tag for stable, LTS and intermediate LTS lines. If the test plan is outsourced, ask the implementation partner to deliver the written case list, the executed results and the repeat procedure as part of the fixed scope, so that the evidence remains with your organization after the engagement ends.
Why XWiki Keycloak SSO logins fail and how to fix them
This table lists the failures that most often block XWiki sign-in through Keycloak with the OpenID Connect extension. Each row gives the likely cause, a check to run first and the fix. Work through the checks in order, because a proxy or redirect problem can look like a secret or group error.
| Failure | Likely cause | Check to run | Fix |
|---|---|---|---|
| Redirect URI mismatch | The redirect URI registered on the Keycloak client does not exactly match the callback URL XWiki sends. | Compare the valid redirect URIs on the client with the redirect_uri parameter in the failed authorization request. | Register the exact XWiki callback URL, including scheme, host, port and path, then retry the login. |
| Wrong or rotated client secret | The secret stored in XWiki differs from the client secret in Keycloak, often after a regeneration. | Check the client's Credentials tab and the Keycloak event log for invalid client credential errors. | Copy the current secret into the XWiki OIDC settings, restart if required, and record who owns secret rotation. |
| Discovery URL unreachable from the XWiki container | The container cannot resolve or reach the realm's OpenID configuration endpoint, often because the hostname is only public. | From inside the XWiki container, request the realm's discovery document and check DNS resolution. | Fix DNS or routing from the container, or use an internal hostname and confirm the token issuer still matches the configured value. |
| Certificate trust error from an internal CA | Keycloak presents a certificate from an internal authority that the Java truststore used by XWiki does not trust. | Inspect the certificate chain from the XWiki host and search XWiki logs for PKIX or SSL handshake errors. | Import the internal CA root certificate into the truststore used by XWiki's Tomcat runtime, then restart XWiki. |
| HTTP instead of HTTPS in the redirect | A reverse proxy does not forward the original scheme, so XWiki builds an http callback URL. | Read the redirect_uri in the authorization request and the forwarded protocol headers set by the proxy. | Forward the original protocol and host at the proxy and set XWiki's public URL to https so callbacks match the registration. |
| Missing group claim because the mapper is absent | The Keycloak client has no protocol mapper that adds group membership to the ID token or userinfo response. | Check the userinfo response or a test token for the groups claim, and confirm the mapper exists on the client. | Add a group membership mapper to the client with the claim name the XWiki extension expects, then test with a fresh login. |
| Users locked out after group changes | Group-based access is typically checked at login, so moved or renamed groups block users who no longer match the allowed group. | Compare the user's Keycloak group membership with the allowed groups in XWiki and review active sessions. | Agree a group change procedure, sign affected users out after changes, and keep a local administrator account for recovery. |
| Clock skew affecting token validation | Keycloak, XWiki or proxy hosts have clocks far enough apart that tokens appear expired or not yet valid. | Compare UTC time on each host and look for iat, nbf or exp errors in the logs. | Sync all hosts to a trusted time source and retry. Do not widen token validation to hide the drift. |
Questions buyers ask before hiring help with XWiki Keycloak SSO
How much does XWiki Keycloak SSO implementation cost?
DeployOpen does not publish prices. A quote follows a written scope, so the cost depends on what you ask us to build and test. The main cost components are planning, Keycloak client and realm configuration, installing and configuring the xwiki-contrib OpenID Connect extension in XWiki, mapping user and group claims to XWiki groups, testing login and logout, and writing handover documentation. Cost goes up with the number of environments (for example, development, test and production), a complex group model, a Keycloak deployment that needs new infrastructure, deeper testing, and an organization that does not yet run Keycloak in production. Setup work is one-time. Upgrades, monitoring and support recur if you retain them. Ask for the quote to list each environment, each group mapping rule, the Keycloak deployment assumptions and the test cases separately.
How long does an XWiki Keycloak SSO project take?
The duration depends on the agreed scope, and no timeline is stated here. The same drivers that affect cost also set the schedule: the number of environments, how many groups and roles must map to XWiki rights, whether Keycloak already runs in production with a realm you can reuse, and how much testing is needed before cutover. Scheduling also depends on access. Client-side approvals, change windows and the availability of Keycloak and XWiki administrators can add time that is outside the build itself. Ask for the schedule in the written scope, with the milestones for configuration, test sign-off and production cutover, and with the client tasks that must finish before each milestone starts.
Can our internal team set up XWiki Keycloak SSO alone?
Often yes, if your team has the right skills and time. The xwiki-contrib OpenID Connect extension is open source and can authenticate XWiki users against an external OpenID Connect provider, so the core work is configuration rather than custom development. Your team needs three skill sets: XWiki administration (extension installation, configuration and upgrades), Keycloak administration (clients, scopes, mappers and realm settings), and operations work such as TLS, DNS and testing. The risky parts are group and claim mapping, which decides who gets which rights, and logout behavior, which must be tested across the wiki and Keycloak sessions. Before you start, confirm that the extension version you choose supports your XWiki line: stable, LTS or intermediate LTS.
What does our team need to provide for the SSO setup?
The client side of the work decides how smoothly the build goes, so prepare these inputs before the work starts. You need administrator access to the Keycloak realm (or a named Keycloak administrator who can make changes) and administrator access to the XWiki instance, including its exact version and database type. You also need the public wiki URL, DNS records, a TLS certificate plan for that URL, and a list of the Keycloak groups or roles that should map to XWiki groups and rights. Provide test users for each role, the non-production environments to test in, and the change window for production. Decide in advance how logout should behave, whether it ends only the wiki session or also the Keycloak session, because that choice affects user expectations and testing.
Is XWiki SAS Pro SSO an alternative to Keycloak OIDC?
It can be, but the choice depends on licensing and supported providers, and you should confirm both with XWiki SAS before you decide. XWiki Pro lists Active Directory and Azure Active Directory SSO applications among its business applications. The product information supplied for this page does not confirm that XWiki Pro SSO applications support Keycloak or a generic OpenID Connect provider, so do not assume it does. Ask XWiki SAS which SSO applications and providers are included in the license, which tier applies to your user count (Starter, Basic, Business or Enterprise, where Starter is for XWiki Cloud only), and whether the same features apply to on-premises deployments. If you already run Keycloak, compare that path with the open source extension and the support you would need for each option.
Does an XWiki Keycloak SSO engagement include upgrades and ongoing support?
Most DeployOpen engagements are fixed-scope, so the agreed deliverables and timeline are written down before the work starts. Ongoing support, upgrades and continuous testing are available as retainers and are priced separately from the build. The upgrade work has two moving parts. XWiki publishes stable and LTS lines, and the extension must stay compatible with the version you run. Keycloak releases come often: the project plans four minor releases a year, and it states that breaking changes in a minor release are opt-in. If you run the Keycloak Operator, the project strongly recommends manual approval for operator updates to avoid unintended upgrades. Ask for the upgrade and support scope in writing, including which versions are covered and how regression tests are repeated after each change.
What usually breaks after XWiki Keycloak SSO goes live?
The most common failures come from the mapping between Keycloak and XWiki rather than from login itself. Check that the group or role claim is present in the token your XWiki instance receives, that the claim name matches the configuration exactly, and that users in nested or newly created Keycloak groups get the rights you expect. Redirect URI mismatches are another frequent cause of failed logins, especially after a URL or DNS change. Logout can leave a user signed in to Keycloak or to XWiki if the front-channel and back-channel settings are not tested. Keycloak also migrates its database schema automatically at startup by default, so plan database backups and check the upgrade notes before a Keycloak upgrade reaches production. Build tests for login, group change, removal from a group and logout in every environment.
How DeployOpen scopes, delivers and supports XWiki Keycloak SSO
DeployOpen plans, builds and documents XWiki and Keycloak OpenID Connect SSO inside your own infrastructure, so login, group claims and logout behavior run where your Keycloak already runs. Work starts from a written, fixed scope and is handed over with documentation your team can operate. Ongoing support is available as a retainer.
How we scope
- The written scope names the XWiki version, database variant and Keycloak realm that the SSO work covers.
- Scope records the xwiki-contrib OpenID Connect extension version and the Keycloak client settings it depends on.
- Engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before work starts.
How we build
- Configure a Keycloak client for XWiki with the redirect URIs, client secret handling and scopes agreed in scope.
- Map Keycloak user and group claims to XWiki profile fields and groups, then test with accounts from each target group.
- Test login, logout and session expiry on the XWiki and Keycloak versions in scope before go-live.
How we hand over
- Handover documents the Keycloak client, claim mappings, extension configuration and the XWiki settings changed during setup.
- Runbooks cover adding a group to XWiki access, rotating the client secret and checking the login path.
- Walkthrough sessions with your identity and wiki administrators prepare them to own day-to-day changes.
How we support
- Ongoing support is available as a retainer covering XWiki and extension upgrades tested against your Keycloak release.
- Keycloak minor releases can include opt-in breaking changes, so each release is reviewed before any planned upgrade.
- Backups of the XWiki database and Keycloak realm configuration are tested with restore runs, not only taken.
