Written by
Oana Elena Florea
, Customer Support Manager
In today's digital landscape, seamless and secure authentication is a key feature for enhancing user experience and safeguarding sensitive information. At XWiki, we have taken a step forward by integrating our platform with Microsoft Entra ID (formerly Azure Active Directory) through the OpenID Connect (OIDC) protocol. This integration, now available starting with version 2.x, offers a robust solution for organizations looking to leverage their existing identity management infrastructure.
The XWiki extension for Microsoft Entra ID allows users to authenticate with their Entra ID credentials, providing a new login experience. This integration is particularly beneficial for enterprises that use Microsoft's identity management services, as it simplifies the authentication process and enhances security.
- Key features of version 2.x
- How to configure Microsoft Entra ID
- How to select the right authentication service
- Administration and login options
- Frequently asked questions
- Closing thoughts
Key features of version 2.x
#1 Simplified configuration: Version 2.x allows administrators to easily register an application in Microsoft Entra ID, configure necessary permissions, and set up the integration with minimal effort.
#2 Enhanced security: By leveraging the OIDC protocol, the integration ensures secure authentication and authorization processes. This protocol is widely recognized for its robust security features, making it a reliable choice for identity management.
#3 User group mapping: This allows administrators to control access based on group memberships, ensuring that users have the appropriate permissions within XWiki.
#4 Customizable username format: The new version offers flexibility in defining the username format. Administrators can choose from various options to match their organizational standards, enhancing consistency across platforms.
#5 Improved administration interface: We updated the administration page to provide an intuitive user experience dedicated to Entra ID.
How to configure Microsoft Entra ID
#1 Register an application: Begin by providing a name, selecting account types, and setting the redirect URI to your XWiki instance.
#2 Configure permissions: Ensure that the necessary permissions, such as email, OpenID, profile, and User.Read, are set and granted as delegated. This step is crucial for enabling the required access levels.
#3 Create a secret: Generate a client secret in the Entra ID portal. This secret will be used in the XWiki configuration to authenticate requests.
#4 Configure a token: Add optional claims to the token configuration. This includes selecting the "preferred_username" and "upn" from the list to ensure that the necessary user information is included in the token.
#5 Use group mapping: Add the groups claim and select the appropriate group ID. This allows for seamless integration of user groups from Entra ID to XWiki.
#6 Update the redirect URI: After upgrading to version 2.x, update the redirect URI in the Entra ID configuration to match the new OIDC settings. This ensures that the authentication flow is correctly routed.
How to select the right authentication service
To use the Microsoft Entra ID SSO, administrators must select the OpenID Connect Authenticator in the XWiki Administration section. This can be done by navigating to the Users & Rights > Authentication section and selecting the appropriate authentication service. Additionally, the default client configuration can be set in the xwiki.properties file to ensure that the Entra ID configuration is used by default.
Administration and login options
For administrators
The administration page for the Entra ID integration provides a comprehensive interface for managing the configuration. You can define groups claims, map user groups, and set allowed or forbidden groups to control access effectively.
For users
We improved the login process by adding new login options. You can choose to log in with the XWiki credentials or be redirected to the Microsoft sign-in page, depending on the configured authentication service. For more details, you can also check the FAQ section regarding login.
Frequently asked questions
#1 What are the known limitations for this integration?
While the integration offers numerous benefits, it's essential to be aware of some known limitations. For instance, when accessing a page as a guest without view rights, you may be redirected to the default OIDC login page. Additionally, if you fail to log in with the "Log in with XWiki" option, you may encounter issues with the login option until the session is restarted, or until you log in and then log out.
For a permanent solution, you should add the following line in the xwiki.properties XWiki configuration file:
oidc.defaultClientConfiguration=EntraID
This will force the OIDC authenticator to use the Entra ID configuration by default.
#2 What happens if I change the username format?
Changing the username format will not break anything as existing users will still use their old user page name, (after migration to EntraID) only new users will have their user page name created based on the new format.
Note that you can modify the username format on the EntraID administration.
Currently, the cleaned UPN is used, but you can use other attributes exposed by the provider (ex :"oidc.idtoken.preferred_username", "oidc.user.name", etc ), even a combination of different attributes. For example: ${oidc.user.givenName}${oidc.user.familyName}
It is also possible to clean or transform the attributes. (clean special characters, lowercase, uppercase)
#3 How to bypass the Entra ID login to access XWiki?
When the XWiki login is hidden, and you still need to access the wiki with an admin or superadmin user, you can use this URL format directly in the browser.
Users that come from Entra ID have the option to switch to an XWiki user account. This option is available only for those users that are coming from Entra ID and are members of a group defined in the XWiki login user groups configuration option on the Entra ID administration settings.
Closing thoughts
The integration of XWiki with Microsoft Entra ID through the OpenID Connect protocol in version 2.x provides organizations a clear configuration for a secure and seamless login experience for their users. This integration not only simplifies the authentication process, but also ensures that security and access control are maintained at the highest standards.
For more detailed information and step-by-step guidance, you can refer to the official documentation.
