Enterprise wiki deployments without centralized authentication are a liability. Every user account managed locally inside XWiki is an account that does not follow your organization's password policies, does not respect your access revocation procedures, and does not appear in your identity audit trail. Connecting XWiki to your existing LDAP directory, Active Directory domain, or modern SSO provider transforms the wiki from an isolated application into an integrated part of your enterprise identity fabric. This guide covers the full spectrum of enterprise authentication for XWiki -- from classic LDAP and Active Directory binding to modern OIDC and SAML federation with Keycloak, Azure AD, and Okta -- along with group mapping, permission synchronization, and multi-factor authentication considerations.
If you are setting up XWiki for the first time, start with our XWiki production installation guide to get the base platform running before configuring authentication. Authentication integration is a post-installation step that builds on a working XWiki instance with administrative access.
LDAP and Active Directory Authentication
LDAP authentication is the most established method for connecting XWiki to enterprise directories. The XWiki LDAP Authenticator extension supports both OpenLDAP and Microsoft Active Directory, providing username and password validation against the directory server, automatic user profile creation on first login, and group membership synchronization.
Installing the LDAP Extension
Navigate to the XWiki Administration panel, open the Extension Manager, and search for the LDAP Authenticator extension. Install it and restart XWiki to activate the authentication module. Alternatively, if you are deploying XWiki via Docker, you can pre-install the extension by adding it to the Docker Compose configuration as an environment variable that triggers installation on first boot.
Configuring LDAP Connection Parameters
The LDAP configuration is set in XWiki's administration interface under the LDAP section. The essential parameters are the LDAP server hostname or IP address, the bind DN (the distinguished name of the service account XWiki uses to query the directory), the bind password, the base DN (the root of the directory tree to search), and the UID attribute (typically sAMAccountName for Active Directory or uid for OpenLDAP).
For Active Directory environments, the configuration typically looks like this: the LDAP server points to your domain controller, the bind DN uses a service account in the format CN=xwiki-svc,OU=Service Accounts,DC=corp,DC=example,DC=com, the base DN is the top-level organizational unit containing your users, and the UID attribute is sAMAccountName to match the Windows login name format that users expect.
Secure LDAP (LDAPS) and StartTLS
Never configure LDAP authentication over unencrypted connections in production. LDAP credentials are transmitted in cleartext unless you use either LDAPS (LDAP over SSL on port 636) or StartTLS (encryption upgrade on the standard port 389). LDAPS is the simpler option -- set the LDAP server URL to ldaps://dc.corp.example.com:636 and ensure that XWiki's Java truststore contains the CA certificate that signed the domain controller's certificate. For organizations using internal certificate authorities, you will need to import the CA certificate into the JVM truststore using keytool.
User Profile Mapping
When a user authenticates via LDAP for the first time, XWiki creates a local user profile and populates it with attributes from the directory. The default mapping covers first name, last name, and email, but you can extend it to include department, phone number, job title, or any other LDAP attribute. This mapping ensures that the wiki user directory stays current without manual data entry -- any changes to the LDAP directory are reflected in XWiki at next login or at the next scheduled synchronization cycle.
OIDC and SAML: Modern SSO Protocols
While LDAP handles direct directory authentication, modern enterprise environments increasingly use federated identity protocols -- OpenID Connect (OIDC) and SAML 2.0 -- to provide single sign-on across all applications. These protocols separate authentication (handled by the identity provider) from authorization (handled by each application), enabling centralized login experiences, multi-factor authentication enforcement, and session management across the entire application portfolio.
OpenID Connect with Keycloak
Keycloak is the most widely deployed open-source identity provider and pairs naturally with XWiki in organizations committed to open-source infrastructure. The XWiki OIDC Authenticator extension connects XWiki to any OIDC-compliant provider, and Keycloak's comprehensive feature set -- user federation, identity brokering, MFA, and fine-grained authorization -- makes it the preferred choice for self-hosted SSO. For a dedicated walkthrough of this integration, see our XWiki and Keycloak SSO configuration guide.
The configuration involves creating a client application in Keycloak's admin console for XWiki, setting the valid redirect URIs to your XWiki instance's callback URL, and configuring XWiki's OIDC extension with the Keycloak issuer URL, client ID, and client secret. Keycloak can federate to your existing LDAP or Active Directory, meaning users authenticate with the same credentials they use everywhere else, but the authentication flow passes through Keycloak rather than directly from XWiki to the directory.
Azure Active Directory (Entra ID) Integration
Organizations using Microsoft 365 can configure XWiki to authenticate against Azure AD (now Microsoft Entra ID) using either OIDC or SAML. The OIDC path is generally simpler: register XWiki as an application in the Azure portal, configure the redirect URI, generate a client secret, and point XWiki's OIDC extension to the Azure AD tenant endpoints. Azure AD handles the authentication, MFA enforcement, and conditional access policies, while XWiki receives a verified identity token with user claims.
For organizations using Azure AD's SAML capabilities, the XWiki SAML extension provides the service provider side of the integration. Register XWiki as an enterprise application in Azure AD, upload XWiki's metadata XML, configure the SAML claims mapping, and set the entity ID and assertion consumer service URL in XWiki's SAML configuration. SAML is more complex to configure than OIDC but may be required by organizations that have standardized on SAML for all application integrations.
Okta Integration
Okta is the dominant commercial identity-as-a-service provider, and many enterprises use it as their central authentication hub. Configuring XWiki with Okta follows the same OIDC pattern: create an application integration in the Okta admin console, select Web Application as the type, configure the sign-in redirect URI to XWiki's OIDC callback, note the client ID and client secret, and configure XWiki's OIDC extension with the Okta issuer URL. Okta's group assignment features allow you to control which Okta users have access to XWiki and what groups they are placed in upon authentication.
Group Mapping and Permission Synchronization
Authentication gets users through the door. Group mapping determines what they can do once inside. XWiki's group-based permission model becomes truly powerful when groups are synchronized from the identity provider rather than managed manually within the wiki.
LDAP Group Synchronization
The LDAP Authenticator extension supports automatic group synchronization. When configured, XWiki queries the LDAP directory for group memberships and creates corresponding XWiki groups, adding and removing users as their directory memberships change. The group mapping configuration allows you to specify which LDAP groups correspond to which XWiki groups, including one-to-many and many-to-one mappings. For example, the LDAP group CN=Engineering,OU=Groups,DC=corp,DC=example,DC=com can be mapped to the XWiki group XWiki.EngineeringTeam.
Synchronization can occur at login time (updating each user's groups when they authenticate), on a scheduled basis (batch synchronization at regular intervals), or both. Login-time synchronization ensures that permission changes take effect immediately for active users. Scheduled synchronization catches users who have not logged in recently and cleans up deactivated accounts.
OIDC and SAML Group Claims
When using OIDC or SAML, group memberships are typically passed as claims in the authentication token. The identity provider (Keycloak, Azure AD, Okta) includes a groups claim that lists the user's group memberships, and XWiki's OIDC or SAML extension maps these claims to XWiki groups. The key configuration step is ensuring that the identity provider is configured to include group claims in the token -- this is not always enabled by default, particularly in Azure AD where you must explicitly enable group claims in the application registration.
Permission Design Patterns
Effective permission synchronization starts with thoughtful group design. Rather than mapping every directory group to a wiki group, define a set of wiki-specific roles -- such as Wiki Admins, Content Editors, Department Viewers, and External Collaborators -- and map directory groups to these roles. This abstraction layer lets you change directory group memberships without rethinking your wiki permission structure, and it makes the wiki's access control auditable without requiring knowledge of the full directory topology.
XWiki's permission model supports inheritance: permissions set at the wiki level cascade to spaces and pages unless explicitly overridden. Combine this with group synchronization to create efficient permission structures. For example, all authenticated users inherit read access to the company-wide knowledge base, the Engineering group gets edit access to engineering spaces, and the Wiki Admins group gets full administrative access. Override inheritance only where necessary to keep the permission model manageable. For a broader look at how XWiki compares to Confluence on enterprise features including permissions, see our enterprise comparison guide.
Multi-Factor Authentication Considerations
Multi-factor authentication is increasingly a baseline requirement for enterprise applications, and for good reason -- passwords alone are insufficient protection for a knowledge base that may contain sensitive organizational information. The approach to MFA in XWiki depends on your authentication architecture.
MFA via Identity Provider (Recommended)
The most robust and maintainable approach is to enforce MFA at the identity provider level rather than within XWiki itself. When XWiki authenticates users via OIDC or SAML, the identity provider handles the MFA challenge before issuing the authentication token. This means Keycloak's OTP or WebAuthn policies, Azure AD's conditional access with MFA requirements, or Okta's adaptive MFA all apply to XWiki logins without any XWiki-specific configuration. This approach is recommended because it provides consistent MFA enforcement across all applications, not just the wiki, and it centralizes MFA policy management in the identity provider.
MFA with LDAP Authentication
If you are using direct LDAP authentication without a federated identity provider, MFA becomes more complex. LDAP itself does not support MFA natively. Options include placing an MFA-aware reverse proxy (such as Authelia or Authentik) in front of XWiki, which intercepts authentication requests and enforces a second factor before passing the request to XWiki. Alternatively, migrating from direct LDAP to Keycloak-brokered LDAP authentication gives you Keycloak's MFA capabilities while still authenticating against your existing directory.
Conditional Access and Adaptive MFA
Enterprise identity providers support conditional access policies that adjust MFA requirements based on context -- location, device, network, risk level, and application sensitivity. For example, you might require MFA for XWiki access from outside the corporate network but allow password-only access from managed devices on the internal network. These policies are configured in the identity provider and apply transparently to XWiki when using OIDC or SAML authentication.
Troubleshooting Common Integration Issues
Certificate Trust Failures
The most common LDAPS failure is a certificate trust error where the JVM does not trust the CA that signed the LDAP server's certificate. Import the CA certificate into the JVM's truststore at $JAVA_HOME/lib/security/cacerts using keytool -importcert. Restart Tomcat after importing the certificate.
Group Synchronization Not Working
If LDAP groups are not synchronizing, verify that the group search base DN is correct, the service account has read access to group objects, and the group object class filter matches your directory schema (typically groupOfNames for OpenLDAP or group for Active Directory). Enable debug logging for the LDAP extension to trace the group search queries.
OIDC Redirect Loop
A redirect loop between XWiki and the identity provider usually indicates a mismatch between the configured redirect URI in the identity provider and the actual callback URL XWiki is sending. Ensure that the redirect URI registered in Keycloak, Azure AD, or Okta exactly matches XWiki's OIDC callback URL, including the protocol (HTTPS), hostname, port, and path.
Managed XWiki with Enterprise Authentication
Configuring enterprise authentication correctly requires attention to security details -- encrypted LDAP connections, proper certificate management, secure client secret storage, and group synchronization tuning. For organizations that want XWiki with enterprise SSO but prefer to offload the operational complexity, MassiveGRID's managed XWiki hosting includes assistance with authentication configuration as part of the managed service.
MassiveGRID deploys XWiki on high-availability infrastructure with Proxmox HA clusters and Ceph distributed storage, pre-configured with SSL, automated backups, and 24/7 monitoring. With data centers in Frankfurt, London, New York, and Singapore, you can deploy your authenticated XWiki instance in the jurisdiction that matches your compliance requirements while your identity provider handles authentication from wherever your users are.
Written by MassiveGRID -- As an official XWiki hosting partner, MassiveGRID provides managed XWiki hosting on high-availability infrastructure across data centers in Frankfurt, London, New York, and Singapore.