xWiki + Keycloak: Centralized SSO

The Authentication Problem Every Growing Organization Faces

When an organization deploys its first internal tool, authentication is simple: create user accounts in the application, assign passwords, and move on. By the time the organization is running five tools — a wiki, a project manager, a file storage platform, a messaging client, a video conferencing service — the simplicity has become a liability. Users manage five sets of credentials. IT administrators maintain five user directories. Offboarding an employee means remembering to revoke access in five separate systems, and missing even one creates a security gap that auditors will find.

This is not a hypothetical scenario. It is the daily reality for organizations that adopt best-of-breed tools without a centralized identity strategy. The solution is single sign-on (SSO), and for open-source infrastructure stacks, the solution is Keycloak — the identity and access management platform that serves as the authentication backbone for the openDesk sovereign productivity suite and countless enterprise deployments worldwide.

For organizations running xWiki as their knowledge management platform, integrating Keycloak transforms authentication from a per-application concern into a centralized, policy-driven capability. Users authenticate once. Administrators manage identities in one place. Security policies — including multi-factor authentication, session management, and password complexity — are enforced consistently across every tool in the stack.

Keycloak Architecture for xWiki

OAuth2 and OpenID Connect: The Foundation

Keycloak functions as an OAuth2 and OpenID Connect (OIDC) identity provider. In this architecture, xWiki does not manage authentication directly. Instead, when a user attempts to access xWiki, the platform redirects them to Keycloak's login page. The user authenticates with Keycloak — providing their username, password, and any additional factors required by policy — and Keycloak issues an identity token that xWiki validates to establish the user's session.

This delegation model has profound implications for security. xWiki never sees the user's password. It never stores password hashes. It never implements password reset flows, account lockout logic, or brute-force protection — because all of those responsibilities belong to Keycloak. The attack surface on xWiki's authentication is reduced to token validation, which is a well-understood, standardized operation with minimal room for implementation error.

The OIDC protocol also enables rich identity information to flow from Keycloak to xWiki through claims embedded in the identity token. Beyond basic attributes like username and email, Keycloak can include group memberships, organizational roles, department information, and custom attributes that xWiki uses to provision user profiles and determine access rights. This is not a one-time synchronization — it happens with every authentication event, ensuring that xWiki's understanding of the user's identity always reflects the current state in Keycloak.

Session Management

Keycloak manages session lifecycle across all connected applications. When a user logs in through Keycloak, a session is established that grants access to xWiki and every other Keycloak-integrated tool. When the user logs out — or when the session expires according to policy — access is revoked across all tools simultaneously. This single-logout capability is critical for security: when an employee leaves or a compromise is suspected, revoking the Keycloak session immediately terminates access to the entire tool ecosystem, not just one application.

Session policies in Keycloak are highly configurable. Administrators can set maximum session duration, idle timeout, and remember-me duration independently. They can require re-authentication for sensitive operations — such as accessing xWiki administrative pages — even within an active session. These policies apply uniformly to all users or can be scoped to specific groups or roles, providing the granularity that enterprise security teams require.

Configuration and Setup

Registering xWiki as a Keycloak Client

The integration begins with registering xWiki as a client application in Keycloak's administration console. This registration establishes the trust relationship between the two systems and defines the parameters of their interaction. The key configuration elements include the client identifier (a unique string that identifies xWiki to Keycloak), the client protocol (openid-connect), and the access type (confidential, meaning xWiki authenticates to Keycloak with a client secret in addition to the user's credentials).

The client registration also specifies the valid redirect URIs — the xWiki URLs that Keycloak is permitted to redirect users to after authentication. This is a security-critical setting: restricting redirect URIs to your xWiki domain prevents authorization code interception attacks where an attacker tricks Keycloak into sending tokens to a malicious endpoint. For an xWiki instance running on MassiveGRID infrastructure, the redirect URI would be configured to the specific domain assigned to the deployment, ensuring tokens are only delivered to the legitimate xWiki instance.

User Attribute Mappers

Keycloak's protocol mapper system controls which user attributes are included in the tokens sent to xWiki. By default, OIDC tokens include basic claims — subject identifier, email, name — but Keycloak mappers can enrich these tokens with custom attributes that xWiki uses for provisioning and access control.

A typical configuration for xWiki includes mappers for first name, last name, email address, and group memberships. The group membership mapper is particularly important: it serializes the user's Keycloak group memberships into a token claim that xWiki reads to assign the user to corresponding xWiki groups. If a user belongs to the "Engineering" and "Documentation" groups in Keycloak, the token claim carries both group names, and xWiki's OIDC authenticator creates or updates the user's group memberships accordingly.

Custom attributes extend this further. An organization might define a "department" attribute in Keycloak that xWiki uses to personalize the user's wiki experience — displaying department-specific content on the dashboard, pre-filtering search results, or applying department-level access policies. The attribute mapper makes this possible without any custom code in xWiki: the attribute flows through the standard OIDC token, and xWiki's user profile system stores it alongside the standard attributes.

Auto-Synchronization of Roles and Groups

The xWiki OIDC authenticator module supports automatic synchronization of group memberships on every login. This means that changes to a user's groups in Keycloak take effect in xWiki the next time the user authenticates — no manual synchronization, no scheduled batch jobs, no risk of stale permissions lingering in xWiki after they have been revoked in Keycloak.

For organizations with complex group hierarchies, the synchronization can be configured to map Keycloak groups to xWiki groups with flexible naming conventions. Keycloak groups can be nested hierarchically, and the mapper can be configured to include only leaf groups, all groups in the hierarchy, or groups matching specific patterns. This flexibility ensures that the group structure in Keycloak — which may serve many applications beyond xWiki — can be mapped to xWiki's group model without requiring the two to mirror each other exactly.

Role synchronization extends beyond group membership to xWiki's permission model. Keycloak roles — which represent functional capabilities rather than organizational groupings — can be mapped to xWiki access rights. A Keycloak role of "wiki-admin" might grant xWiki administrative privileges, while "wiki-editor" grants edit rights and "wiki-viewer" grants read-only access. This role-based mapping provides a clean separation between identity management (Keycloak's responsibility) and access control (xWiki's responsibility), with Keycloak roles serving as the bridge between the two.

Multi-Factor Authentication and Advanced Security

Enforcing MFA for Sensitive Wiki Spaces

Multi-factor authentication is no longer optional for enterprise applications. Credential stuffing attacks, phishing campaigns, and password database breaches have made single-factor authentication — no matter how complex the password policy — insufficient for protecting sensitive information. Keycloak provides MFA capabilities that xWiki inherits automatically through the OIDC integration, without any MFA implementation in xWiki itself.

Keycloak supports multiple second-factor methods: time-based one-time passwords (TOTP) through authenticator apps like Google Authenticator or Authy, WebAuthn/FIDO2 hardware security keys such as YubiKeys, and SMS or email-based verification codes. The choice of method — or the requirement for multiple methods — is configured in Keycloak's authentication flow, which defines the sequence of steps a user must complete to authenticate.

The power of Keycloak's policy engine becomes apparent when organizations need to enforce MFA selectively. Not every wiki page warrants the friction of a second factor, but administrative pages, HR documentation, financial records, and security policies certainly do. Keycloak's conditional authentication flows can require MFA based on the user's role, group membership, IP address, or the client application being accessed. An organization might configure Keycloak to require MFA for all users in the "admin" group when accessing xWiki, while allowing standard users to authenticate with a password alone for routine wiki access.

Per-Realm Security Policies

Keycloak organizes configuration into realms — isolated tenants with independent user directories, authentication policies, and client registrations. For organizations operating multiple xWiki instances — perhaps one for internal documentation and another for customer-facing knowledge bases — each instance can be registered as a client in a different Keycloak realm with distinct security policies.

The internal wiki might require MFA, enforce session timeouts of four hours, and restrict access to users in the corporate directory. The customer-facing wiki might allow social login (Google, GitHub), implement longer session durations for convenience, and permit self-registration with email verification. Both wikis delegate authentication to Keycloak, but each operates under its own security policy without any compromise or configuration conflict.

For multi-national organizations deployed across MassiveGRID's data centers in Frankfurt, London, New York, and Singapore, realm-based isolation can also support jurisdictional requirements. A European realm might enforce GDPR-specific policies — such as mandatory consent prompts and data retention limits — while an Asia-Pacific realm implements the policies appropriate to that regulatory environment.

Auditing and Compliance

Comprehensive Authentication Event Logging

Keycloak logs every authentication event: successful logins, failed login attempts, token refreshes, logouts, MFA challenges, password changes, account lockouts, and administrative actions. These logs are essential for security monitoring and incident investigation, providing a timestamped record of who authenticated, when, from which IP address, and which client application they accessed.

For xWiki deployments, Keycloak's event log complements xWiki's own audit trail. While xWiki logs content-level events — page views, edits, deletions, permission changes — Keycloak logs the authentication events that precede them. Together, they provide end-to-end visibility: Keycloak records that a user authenticated at 09:15 from a specific IP address, and xWiki records that the same user edited a sensitive policy document at 09:17. This combined audit trail is invaluable for compliance and forensic investigation.

SOC 2, ISO 27001, and HIPAA Audit Support

Organizations pursuing SOC 2 Type II certification need to demonstrate that access controls are consistently enforced and monitored. Keycloak's centralized authentication model, combined with its event logging, provides the evidence that auditors require: proof that authentication policies are defined, that they are enforced across all applications, and that authentication events are captured and retained.

ISO 27001 compliance — which MassiveGRID's infrastructure already supports through its ISO 9001 certification and security practices — requires documented access control policies and evidence of their implementation. Keycloak's configuration serves as both the policy definition and the enforcement mechanism: the authentication flows, password policies, MFA requirements, and session management rules are simultaneously the documented policy and the running implementation.

For HIPAA-regulated organizations managing protected health information in xWiki, Keycloak's audit logs satisfy the access control and audit trail requirements of the Security Rule. Every access to the wiki — successful or failed — is logged with sufficient detail to identify the individual, the time, and the outcome. Combined with MassiveGRID's 100% uptime SLA and 24/7 support, the infrastructure foundation for HIPAA-compliant wiki deployment is comprehensive.

Organizations evaluating xWiki for enterprise knowledge management can review the xWiki vs Confluence enterprise comparison to understand how xWiki's open-source authentication model — including Keycloak integration — compares to Confluence's proprietary Atlassian Access approach.

Deploying xWiki with Keycloak on MassiveGRID

Running both xWiki and Keycloak on MassiveGRID infrastructure ensures that authentication traffic stays within the same data center, minimizing latency and maximizing security. With data centers in Frankfurt, London, New York, and Singapore, organizations can deploy their identity infrastructure in the jurisdiction that aligns with their regulatory requirements. MassiveGRID's managed hosting includes provisioning, monitoring, backup, and 24/7 support — covering both the xWiki application and the Keycloak identity platform that secures it.

Frequently Asked Questions

Does Keycloak SSO automatically synchronize with xWiki's internal group system?

Yes. The xWiki OIDC authenticator module supports automatic group synchronization on every user login. When a user authenticates through Keycloak, the identity token includes a groups claim (configured through Keycloak's group membership mapper) that lists all the groups the user belongs to. xWiki reads this claim and updates the user's group memberships to match, creating groups in xWiki if they do not already exist. This synchronization is bidirectional in the sense that it happens every time the user logs in, so changes made in Keycloak — adding a user to a new group or removing them from an existing one — are reflected in xWiki at the next authentication event. However, xWiki groups can also contain additional members who are not managed by Keycloak, allowing a hybrid model where some group assignments come from the identity provider and others are managed locally in xWiki.

Can I enforce MFA for wiki administrators only, while allowing regular users to log in with just a password?

Yes, this is a standard Keycloak configuration. Keycloak's conditional authentication flows support role-based or group-based MFA requirements. You create a Keycloak group (for example, "xwiki-admins") and configure a conditional authentication flow that checks the user's group membership after the initial password authentication step. If the user is a member of the admin group, the flow requires a second factor — TOTP, WebAuthn, or another configured method. If the user is not in the admin group, the flow skips the MFA step and issues the token immediately. This approach provides strong security for privileged access without imposing unnecessary friction on standard users who are reading or editing routine wiki content. The same pattern can be extended to any group or role, allowing nuanced MFA policies that match the sensitivity of the resources each user group accesses.

Does adding Keycloak SSO introduce noticeable latency to xWiki login?

In a well-configured deployment, the latency impact of Keycloak SSO is negligible — typically adding fewer than 100 milliseconds to the initial authentication redirect. The OIDC flow involves a redirect from xWiki to Keycloak, the user authenticating with Keycloak, and a redirect back to xWiki with an authorization code that is exchanged for tokens. When both xWiki and Keycloak run on the same MassiveGRID data center, the redirects and token exchange happen over the local network with single-digit millisecond latency between services. The user-perceptible delay is dominated by the Keycloak login page rendering — which is a single, lightweight HTML page — rather than by protocol overhead. After the initial authentication, xWiki maintains its own session, so subsequent page loads do not involve Keycloak at all until the session expires or the user logs out. For organizations with geographically distributed users, deploying Keycloak in the same MassiveGRID region as xWiki (Frankfurt, London, New York, or Singapore) ensures that the authentication flow stays as fast as possible for each user population.