When an organisation already runs Keycloak, people expect to use the same account everywhere. XWiki can do that through its OpenID Connect Authenticator: XWiki sends people to Keycloak to sign in, receives who they are and which groups they belong to, and keeps managing what they can see with its own rights.
Everything in this guide was done on a real test installation, and the same steps are shown in the video. The values (addresses, names, groups) come from that test setup: replace them with yours.
Tested with: XWiki 18.8.0, OpenID Connect Authenticator 2.29.1 and Keycloak 26.4, the
wiki at http://localhost:8099 and Keycloak at http://keycloak.localhost:8180
(realm acme). The authenticator requires XWiki 14.10.2 or later.
How XWiki and Keycloak work together
- Someone opens a page that needs a login. XWiki sends the browser to Keycloak.
- The person signs in on Keycloak's page. The password goes to Keycloak only, never to XWiki.
- Keycloak sends the browser back to XWiki's callback address with a one-time code.
- XWiki exchanges the code directly with Keycloak, server to server, for signed details: name, e-mail and groups.
- XWiki creates or updates the user's profile, links it to the Keycloak account and fills the mapped XWiki groups. The user lands on the page they asked for.
The call people forget: step 4 is made by the XWiki server, not by the browser. The XWiki server must reach Keycloak's address (DNS, firewall, certificates), and that address must be the same one the browser uses.
Before you start
- A running XWiki and an administrator account in it that does not depend on Keycloak (your way back in).
- A Keycloak realm with your users, and groups for the people who need specific rights in XWiki.
- The public address of your wiki, exactly as users type it (scheme, host, port, path such as
/xwiki). - Network access from the XWiki server to Keycloak.
- A test environment or a maintenance window: you will restart XWiki once.
1. Create the client in Keycloak
In the Keycloak administration console of your realm:
- Open Clients and click Create client.
- General settings: keep Client type OpenID Connect, set Client ID
to
xwikiand a name such as XWiki. Click Next. - Capability config: turn Client authentication on. XWiki runs on a server, so it gets its own secret. Keep Standard flow (the only flow XWiki needs). You can also set PKCE Method to S256: the authenticator supports it. Click Next.
- Login settings: Root URL = your wiki address; Valid redirect URIs and
Valid post logout redirect URIs = your wiki address followed by
/*; Web origins = your wiki address. Click Save. - Open the Credentials tab and copy the Client Secret.
Why the post logout redirect URI matters: with it, logging out of XWiki also ends the Keycloak session. Without it, the next "Log in" signs the user back in without asking anything.
2. Send the groups to XWiki
- In the client, open Client scopes and click the dedicated scope (
xwiki-dedicated). - Click Configure a new mapper and choose Group Membership.
- Set Name and Token Claim Name to
xwiki_groups, the claim XWiki reads by default. - Turn Full group path off, so groups arrive as
wiki-editorsand not/wiki-editors. Keep Add to ID token, Add to access token and Add to userinfo on. Click Save.
3. Install the OpenID Connect Authenticator
- In XWiki, as an administrator, open Administration › Extensions.
- Search for OpenID Connect Authenticator and click Install on farm, so every wiki of the instance can use it.
- XWiki lists the extensions that come with it (OpenID Connect API, Nimbus libraries, Token Authenticator…). Click Continue until the extension shows Installed.
On a brand-new instance, the search can miss it while the extension index is still being built (a note "Index started on…" is shown): wait a minute and search again.
4. Connect XWiki to Keycloak
Add these lines to xwiki.properties (in the official Docker image, edit the copy in the data
volume, /usr/local/xwiki/data/xwiki.properties, which is restored over the webapp's copy at each
start), then restart XWiki:
oidc.provider=http://keycloak.localhost:8180/realms/acme
# The client created in Keycloak
oidc.clientid=xwiki
oidc.secret=<the Client Secret from the Credentials tab>
oidc.scope=openid,profile,email
# Profile name from the Keycloak user name: alice -> XWiki.alice
oidc.user.nameFormater=${oidc.user.preferredUsername._clean}
# One line per group: XWiki group = Keycloak group
oidc.groups.mapping=XWikiAdminGroup=wiki-admins
oidc.groups.mapping=WikiEditors=wiki-editors
| Setting | What it does |
|---|---|
oidc.provider | Your realm's issuer. XWiki reads its .well-known/openid-configuration to find the authorization, token, userinfo, logout and key endpoints. |
oidc.clientid, oidc.secret | Identify XWiki to Keycloak in the server-to-server call. |
oidc.user.nameFormater | Builds the profile page name of new users. The default adds the provider host (keycloaklocalhost-alice). |
oidc.groups.mapping | Which XWiki group each Keycloak group fills. Members are added and removed at each sign-in. Without any mapping, every group received is synchronized under the same name. |
5. Select the authenticator
- Open Administration › Users & Rights › Authentication.
- In Authentication service, choose OpenID Connect Authenticator and click Save. Current Authentication service confirms it. No restart is needed for this choice.
Alternatively, set it in xwiki.cfg (restart needed). A class set there overrides the
administration choice and hides it:
6. Test the sign-in
- As a guest, open a page that needs a login: you are sent to Keycloak, and back to that page after signing in.
- The new profile has the first name, last name and e-mail from Keycloak, and no XWiki password.
- A member of a mapped Keycloak group is in the matching XWiki group (Administration › Groups).
- A user in no mapped group can sign in but only sees what XWiki's rights allow.
- Logging out of XWiki and logging in again shows the Keycloak sign-in form (the Keycloak session ended).
- Signing in a second time reuses the same profile.
Keep a way back in
If Keycloak is unreachable or a setting is wrong, add ?oidc.skipped=true to a wiki address, for
example /bin/view/Main/?oidc.skipped=true: XWiki shows its own login form and your local
administrator account still works.
Be careful with oidc.tryLocal=false: it removes every local login (the form,
?oidc.skipped=true and Basic authentication on the REST API). Enable it only after testing, and
when you are sure you won't need a local account.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Keycloak: "We are sorry… Invalid parameter: redirect_uri" | The address XWiki sends doesn't match a valid redirect URI: missing context path (/xwiki), port, or http/https behind a proxy. | Register the wiki's real public address with /*; make the proxy pass X-Forwarded-Host, -Proto and -Port. |
| Users sign in but get no groups | No Group Membership mapper, a claim name other than xwiki_groups, or Full group path on (/wiki-editors). | Fix the mapper; groups update at the user's next sign-in. |
| "HTTP Status 500" right after signing in | The user is not in oidc.groups.allowed; the authenticator shows an error page instead of a message (and the Keycloak session stays open). | Prefer XWiki rights on spaces to restrict content, or warn users. |
Error after signing in on a subwiki, log says invalid_grant "Incorrect redirect_uri" | xwiki.home set with an explicit port. | Remove xwiki.home and fix the forwarded headers. |
Timeout (504) on /oidc/authenticator/callback | The XWiki server can't reach Keycloak's token or userinfo endpoint. | Make the issuer address reachable from the server (DNS, firewall, certificate trust). |
| Logging out of XWiki doesn't log out of Keycloak | No valid post logout redirect URI, or an old version of the authenticator. | Register the post logout URI; keep the extension up to date. |
| Users must sign in again after closing the browser | The XWiki session cookie ends with the browser; the authenticator does not re-authenticate silently. | Known limitation; some setups give the session cookie a lifetime at the reverse proxy. |
| Scripts and REST calls fail for SSO users (401) | SSO users have no XWiki password. | Use the Token Authenticator (personal access tokens). |
Duplicate profiles such as alice-0 | Profiles are matched only by Keycloak issuer and user id: the issuer address changed, or the profile existed before (local or LDAP). | Never change the issuer address; when migrating, link existing profiles first. |
For anything else, open Administration › Logging, set org.xwiki.contrib.oidc to
DEBUG and sign in again: the log shows what Keycloak answered.
Rolling out single sign-on on a production XWiki? We can review your Keycloak and XWiki configuration, plan the switch and migrate existing users without duplicates.
Talk to AgneaseBefore production
- Use HTTPS for both XWiki and Keycloak, with the public addresses in the client settings.
- Behind a reverse proxy, pass the forwarded headers and avoid
xwiki.home. - Plan how existing XWiki or LDAP users will be linked to their Keycloak accounts before the switch.
- Decide which XWiki groups come from Keycloak, and keep the rights on groups, not on individual users.
- Keep a local administrator account and document the way back in.
- Store the client secret safely and plan its rotation (Keycloak: Credentials › Regenerate).
- Keep the OpenID Connect Authenticator up to date: security and logout fixes ship in it.
- In a cluster, use the same configuration on every node.
- Give scripts and integrations API tokens instead of passwords.
XWiki and Keycloak FAQ
Does XWiki see the users' passwords with Keycloak?
No. With OpenID Connect, the password is typed on Keycloak's page and checked by Keycloak. XWiki only receives a signed answer saying who the user is and which groups they belong to.
Do Keycloak groups replace XWiki rights?
No. Keycloak groups fill XWiki groups; XWiki rights decide what those groups can view or edit. Authentication and access control should be designed together.
Can I still log in with a local XWiki account?
Yes, by default. Add ?oidc.skipped=true to a wiki address to get the XWiki login form. Setting
oidc.tryLocal=false removes that possibility.
Does multi-factor authentication work with this setup?
Yes. Multi-factor authentication is configured in Keycloak; XWiki receives the result of the sign-in. For XWiki's own logins (standard, LDAP or Active Directory), Agnease XWiki MFA adds a verification code.
Does it work with other OpenID Connect providers?
The same authenticator works with other OpenID Connect providers, such as Microsoft Entra ID, Google, Authentik or LemonLDAP::NG. The provider's client settings and group claims differ.