• Version 2.x
  • Steps to configure Microsoft Entra ID
  • Steps to configure Microsoft Entra ID after upgrade
  • Selecting the right Authentication service
  • Administration page
    • Configuration options
  • Login options
  • Known limitations
• Version 1.x
  • Configuration
    • Preparing your wiki
    • Registering for OAuth access
  • xwiki.cfg properties
• FAQ

Version 2.x

Steps to configure Microsoft Entra ID

1. You need to register an application in Microsoft Entra ID. (You can use the link for quick access Register Application)

• Choose/add a name (that will be user visible) and the desired account types
• The redirect URI should be like the following: https://<YOUR XWIKI URL WITH PORT IF NECESSARY>/xwiki/oidc/authenticator/callback
• Click on the Register button

 You should be able to view the new application overview. Here you can find your:

• Application (client) ID
• Directory (tenant) ID

Copy the client and tenant ids (using the roll-over-button "Copy to clipboard" can work well). You can go back later on the registered app, Overview section, to recopy them.

2. Create a secret. Go to "Certificates & secrets", select "Client secrets" and click "New client secret"

• Click on "+ New client secrets"
• Add a Description and an Expiration time
• Click on the Add button

• Copy the Value field (using the roll-over-button "Copy to clipboard") and write it down (store it somewhere as it will become hidden and inaccessible - it will be used as secret key in the Entra ID configuration section of the wiki administration)

3. Go to "Token configuration" and add "optional" claims. Token type should be "ID". Select "preferred_username" and "upn" from the list

4. To be able to use the groups mapping, you need to add the "groups" claim and select the "Group ID" as ID, and the type of groups you want to be imported from EntraID.

• To get all the groups associated with a user, use the "All groups" option.

5. Go to "API permissions" and make sure email, openid, profile and User.Read are set and granted as delegated

Steps to configure Microsoft Entra ID after upgrade

Following the update to the 2.0 version, the old AzureAD configuration is completely removed and replaced with the OIDC configuration and authentication service. This will require the user to modify the Azure configurations to adapt to the OIDC properties.

To configure the Azure application, steps 3 to 5 need to be done.

In addition to the above steps, a new redirect URI needs to be configured:

• Go to "Authentication" and add a new redirect URI like the following: https://<YOUR XWIKI URL WITH PORT IF NECESSARY>/xwiki/oidc/authenticator/callback

Selecting the right Authentication service

To use the Microsoft Entra ID SSO, you first need to select the right Authentication service. To do this, you must go to administration and navigate to "Users & Rights -> Authentication" section and in the bottom of the page, select the OpenID Connect Authenticator:

The authentication service can also be configured by default in xwiki.cfg by modifying the authentication management class to:

xwiki.authentication.authclass=org.xwiki.contrib.oidc.auth.OIDCAuthServiceImpl

In addition, the Entra ID configuration can be selected by default by adding the following line in xwiki.properties:

oidc.defaultClientConfiguration=EntraID

This fixes a limitation of the application, that does not correctly redirect the user to the Microsoft login page when a guest user tries to access a page where he lacks view rights.

Administration page

The application administration page is in the section Entra ID 

Configuration options

• Groups claim:
  • The key to the user groups.
  • If added, but no group mapping is done, when a user will log in with EntraID it will also create all the allowed groups from EntraID that the user is part of.
  • By default, the "groups" value should be used (corresponding to the claim from the EntraID Token configuration).
  • Needs to be configured to be able to use "Groups mapping", "Allowed groups" and "Forbidden groups" settings.
• Groups mapping:
  • The XWiki group can be selected by using a picker, while for the EntraID group it should be used the group Object ID from EntraID.
• Allowed groups:
  • The groups from EntraID that the user needs to belong to be allowed to authenticate. The EntraID group Object ID needs to be used.
• Forbidden groups:
  • The groups from EntraID that if the user belongs to, it will not be allowed to authenticate. The EntraID group Object ID needs to be used.
• User name format: The default configuration will generate the username based on UPN of the user. It will be converted to lowercase (as it uses "_loweCase") and removed all dots and other symbols (as it uses "_clean").
  • Other format examples: 
    • "oidc.idtoken.preferred_username"
    • "oidc.user.name"
• User mapping - associate the name of the XWiki user property with properties coming from OpenID Connect side:Allow XWiki login: Enable the "Login with XWiki" option in the drawer header for a guest user.
  • The  Microsoft user info endpoint only returns the basic user information. To access additional details, an admin must map XWiki user properties to the attributes received in the ID token.
  • To include more user attributes in the ID token, a Microsoft Azure admin must first configure the necessary optional claims in the "Token configuration" tab of the application, as shown in the example above. Once this setup is complete, the properties association can be configured in XWiki.
  • For XWiki properties association, the XWiki user property name should be used; for Azure association, a format similar to the one at User name format should be used.
  • For more information regarding the optional claims: https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims.
• XWiki login user groups:
  • Group a user needs to belong to so that he would have the option to switch to a XWiki user. 
  • Only visible for Microsoft EntraID users belong to aforementioned groups. 
• Scope:
  • After following the configuration steps above, the scope should be modified to use the new settings (the default for the given instruction are the values "openid,profile,email,address"). 

Login options

A new login option has been added to the drawer:

• Using "Log in with XWiki", the user will be redirected to the standard XWiki login page.

• Using the "Log-in" option, the user will be redirected to the Microsoft sign in page (if the OpenID Connect Authenticator is selected)

In addition, 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 "XWiki login user groups" configuration option.

Known limitations

• When accessing a page as a guest with no view rights, the user will be redirected to the default OIDC login page:

This is a known limitation as the OIDC authentication configuration is selected by using cookies, which cannot be added if the guest cannot use the built in login option. The cookie authentication is meant as a temporary solution for using the Entra ID configuration, or for those wikis where view access is not fully restricted. For a more permanent solution, the following line should be added in the xwiki.properties file: 

oidc.defaultClientConfiguration=EntraID

This will force the OIDC authenticator to use the EntraId configuration by default.

• If the user selects the `Log in with XWIki` option, but fails to log in (for example returns to the previous page without logging in), the `Log in` option will no longer redirect the user to the Microsoft sign in page. Instead, the user will be redirected to the standard login page. This will happen until the session is restarted, or the user logs in and then logs out. The cause of this limitation is due to the fact that OIDC registers the authentication service skip in the session cache. 

Version 1.x

Configuration

Preparing your wiki

Make sure that you know the (https) URL of your wiki.

Registering for OAuth access

1. Navigate to portal.azure.com , select "App registrations".

2. Click on "+ New registration"

3. Choose/add a name (that will be user visible) and the desired account types

• The return URL (Redirect URI in the portal) can generated later and copied from the Entra ID configuration section, in the wiki administration. It will be the login URL which the users will use, e.g. for main wiki - https://yourserver/xwiki/bin/login/XWiki/XWikiLogin
• Click on the Register button

4. Resulted App Overview

You are now defining what the "app" (the XWiki) as: 

• Display name
• Application (client) ID
• Directory (tenant) ID

Copy the client and tenant ids (using the roll-over-button "Copy to clipboard" can work well). You can go back later on the registered app, Overview section, to recopy them.

 5. Click on "Branding" from the left panel

• Add useful information as possible to get the trust of the users (for the wiki to access the permissions).

• Click on "Save"

 6. Click on "Authentication" from the left panel

• Click on "+ Add a platform" > Web
• Add the desired Redirect URI: e.g. main wiki - https://yourwikiserver/xwiki/bin/login/XWiki/XWikiLogin
• Optional - Add an Front-channel logout URL (an absolute URL such as https://yourwikiserver/xwiki/bin/view/AzureAD/OAuthLogout)
  
• Select "ID tokens"
  
• Click on the "Save" button

7. Click on "Certificates & secrets" from the left panel

• Click on "+ New client secrets"
• Add a Description and an Expiration time
• Click on the Add button
• Copy the Value field (using the roll-over-button "Copy to clipboard") and write it down (store it somewhere as it will become hidden and inaccessible - it will be used as secret key in the Entra ID configuration section of the wiki administration)

8. Click on "API permissions" from the left panel

• Click on "+ Add a permission"
  
• Select "Microsoft Graph"
  
• Select "Delegated permissions"
  
• Under "Select permissions" search and select openid, User.Read and User.ReadBasic.All 
  
• Click on the "Add permissions" button

We now have finished the configuration on the Microsoft side.

9. Log-in to the wiki as Admin

• From the Drawer access "Administer Wiki" >  "Extensions" > "Extensions"
• Search for Entra ID, install the appropriate version (install it on farm if you want to use it on both the main wiki and all your other subwikis) and get a License for it

10. Click on Other > Entra ID

• Input Client ID, Secret Value and Tenant ID as copied above
• The Return URL is computed by the server and it is optional to complete it
• From PERMISSIONS TO REQUEST select/unselect User image
• Click on the "Save" button

We now have finished on the XWiki side and can test the Entra ID login.

11. Logout or choose another browser to access the wiki if you want to still be logged in with an XWiki user in the current browser.

12. Click Login

• Click on "Login with Entra ID"
  
• Fill in the credentials for the Microsoft account (also used to login in to https://portal.azure.com/)
• Accept the Permissions requested
  

xwiki.cfg properties

You can set each of these parameters by setting:

xwiki.idoauth.<param_name>=<param_value>

FAQ

• Can I login with Entra ID on both the main wiki and my subwikis?
• How to sync the XWiki profile with the Entra ID Account information?
• I have an Active-Directory Server; can I use it with this app?
• Can this app import user images? (avatars)
• Can I block some users from logging in ?
• Can I add login with the OAuth provider X/Y/Z ?
• Can I use this service with our http-based wiki?
• Can I jump directly to the Microsoft Entra ID login form?
• I meet the error that the return-URL is not allowed

Can I login with Entra ID on both the main wiki and my subwikis?

Yes. For this option, we recommend you install the Microsoft Entra ID Single Sign-On (SSO) (Pro) on farm from the start.

Then, you need to follow the steps shown in the Registering for OAuth access documentation section, and to add the obtained client ID, tenant ID, secret value on the main wiki administration > Other > Entra ID configuration.

It will not be needed to add a Redirect URL towards the subwiki login or to complete the Entra ID configuration from the subwiki administration. 

Once you finish the setup, you will obtain the following results:

• The ability to login from the main wiki with an Entra ID account.
• You can access a link towards the subwiki that was placed on a main wiki page without being prompted to login.
• When someone accesses directly a link from the subwiki Sandbox page, for example, and they will be able to login with an Entra ID account and it will show them the Sandbox page.

How to sync the XWiki profile with the Entra ID Account information?

On the Administration section, the "Permissions to request" options allow the user to specify which information will be copied from the Entra ID Account to the XWiki profile upon login.

I have an Active-Directory Server; can I use it with this app?

No. This app is solely designed for the Entra Cloud based Active-Directory server by Microsoft Inc.
However, Microsoft offers methods to migrate from a local active-directory server to an Entra ID service.

Can this app import user images? (avatars)

Yes, this app can do so if the accounts are allowed to use Outlook. The images will be imported as long as the user does not manually modifes the avatar in XWiki. To restart the import, select the default avatar or delete the manually added one.

Can I block some users from logging in ?

Provided that a user has logged in with an Entra ID identity, a wiki page for this user has been created and can be modified.
Setting this user to inactive, or removing view rights on this user will prevent this Entra ID-based login to work.

Can I add login with the OAuth provider X/Y/Z ?

This app is based on IdentityOAuth which is designed to be used with multiple identity providers. Creating another provider requires implementing a provider java class as well as configuration XWiki objects and administration XWiki sheets. See the documentation there.

Can I use this service with our http-based wiki?

Except for ``localhost`` (including ``localhost:8080`, Entra ID does not allow users to be sent to URLs that are not using the ``https`` protocol. Hence this app can be used for development but not for hosting a local http-based server.

Can I jump directly to the Microsoft Entra ID login form?

Yes, you can select from Administer Wiki -> Other -> Identity OAuth the Entra ID as the default provider. Now, after a click on the login button, users will be redirected to the Microsoft Entra ID login page.

This option can also be used to hide the Entra ID login option by selecting a different provider. Note that the default provider hint refers to the standard XWiki login form.

I meet the error that the return-URL is not allowed

This error occurs as soon as the URL that was used by the XWiki server at time of configuring the administration is not the same as the URL configured in the Entra ID service as redirect URL. Since XWiki can often be accessed from different URLs, it may be safer to configure the app with a hand-written redirect-URL.

Installation Steps

This paid extensions requires XWiki 14.10.2 or above. In order to install the extension, follow the next steps inside your XWiki instance (on cloud or on premise).

Navigate to the Extension Manager

In the Applications Panel click on "More Applications..." and then "Install new applications...". Alternatively navigate directly to the Administration and select the "Extensions" section.

Install the Extension

Search for the extension you wish to install and use the Install button to install it.

Get a License

Navigate to the "Licenses" section of the Administration, fill your details, look for the extension you just installed in the live table and click the buttons to get a trial license or to buy a license.

Install the License

If you have selected a trial license then you're good and there's nothing else to do. Your trial license is automatically installed.

However if you've selected to buy a license you'll be redirected to a page to perform the payment. At the end you need to come back to the "Licenses" administration section and click on the "Check for Updates" button. This will download and apply the license you bought.

Use the Extension

Start using the Extension! Refer to the extension's documentation to know how to use it.

Installing Paid Apps on Subwikis

If you want to install an application on the whole farm (main wiki + subwikis), you can do so directly from the main wiki’s Extension Manager, as seen below:

Extensions can also be installed only on a particular subwiki by global admins. Subwiki admins will not be able to install these extensions due to their limited rights.

Uninstall the extension

To rapidly see the effect of the uninstall, you can navigate to the administration of Azure AD and deactivate the app.

You can then navigate to the wiki administration, Extensions section, search for the Microsoft Azure Active Directory extension and uninstall it. Check the Licenses tab for remaining dependency extensions, and search for them as well in the Installed Extensions so that you can completely remove the Azure AD application. There are curently 4 dependency extensions that need to be uninstalled: Configuration Pages for Microsoft Azure Active Directory Single Sign-On (SSO) (Pro), Identity OAuth (Pro), Microsoft Azure Active Directory Single Sign-On (SSO) (pro) API and Identity OAuth Integration (API).

See an example in the image gallery below:

Options

The price is per year and varies depending on the support level and the number of users.

Benefits

What do you get when you purchase an XWiki extension?

How to Buy

To buy, install this extension from inside your XWiki instance and follow the instructions.

Release notes

v2.0

• #48: Replace identity-oauth use with OIDC
• #42: Create a custom display for the new configuration properties
• #41: Migrate old objects values to the OIDC class

v1.9

Upgrades:

• #45 Do not sync the avatar picture if the user manually set it in XWiki

v1.8

Upgrades:

• #46 Upgrade parent to 14.10

v1.7.5

Upgrades:

• #39 Upgrade Licensor dependency to version 1.25
• #40 Upgrade Identity OAuth to 1.7.5

v1.7.4

Upgrades:

• #38 Upgrade Identity OAuth to 1.7.4

v1.7.3

Upgrades:

• #34 Upgrade Licensor dependency to version 1.24.3
• #35 Upgrade Identity OAuth to 1.7.3

v1.7.2

Bugs fixed:

• #32 Cannot login on a page with an anchor when the user's session has expired

Upgrades:

• #33 Upgrade the Identity OAuth dependency version to 1.7.2

v1.7.1

Upgrades:

• Identity OAuth Integration 1.7.1

v1.7

New features:

• #10 Allow to turn on SSO only login for the wiki

Upgrades:

• Identity OAuth Integration 1.7

v1.6

Bugs fixed:

• #14 Setting the scope of the ConfigurableClass of the AzureADConfig page to 'wiki level' breaks authentication on XWiki 13.7+
• #17 The homepage of the application is not hidden so it's visible in the page tree and in search

Upgrades:

• #26 Upgrade parent to 13.10-3.
• Licensing Application 1.24.1

Security upgrades:

• Identity OAuth Integration 1.6 fixes https://github.com/xwikisas/identity-oauth/security/advisories/GHSA-h2rm-29ch-wfmh

v1.5.9

Dependency upgrades:

• Identity OAuth Integration 1.5.3

v1.5.8

Bugs fixed:

• #23 Login button is missing since 1.5.6 version

Dependency upgrades:

• Identity OAuth Integration 1.5.2

v1.5.7

Dependency upgrades:

• Identity OAuth Integration 1.5.1

v1.5.6

Bugs fixed:

• #11 Sporadic failed authentication when provider becomes null

Dependency upgrades:

• Identity OAuth Integration 1.5

v1.5.5

Bugs fixed:

• #11 Access to subwiki forbidden if the View right is allowed for any group either on the main wiki level or subwiki level, and there are still rights issues after removing the right
• #12 Login option is shown after uninstalling the Microsoft Azure Active Directory Single Sign-On (SSO) (Pro)

Dependency upgrades:

• Identity OAuth Integration 1.4.1

v1.5.4

Dependency upgrades:

• Licensing Application 1.22.1
• Identity OAuth Integration 1.4

v1.5.3

Update the application description

v1.5.2

Update the Licensing dependency version to 1.22

v1.5

Bugs:

• #2: Failed to instantiate AzureADIdentityOAuthProvider

v1.4

Bugs:

• #5: The login button is not displayed
• #4: Broken login after reinstall on farm
• #2: Failed to instantiate AzureADIdentityOAuthProvider

Also update the licensor and Identity OAuth versions.

v1.2

• #6: Azure users with empty name get an error upon login

v1.1

• #1: Polish project descriptor

v1.0

Initial release.

Extension details

License

• GNU Lesser General Public License 2.1

Sources

• https://github.com/xwikisas/integration-azure-oauth/tree/master/integration-azure-oauth-ui

Issues

• GitHub

Type

• xar

Developed by

• XWiki SAS

Compatibility

• Requires XWiki 14.10.2 or above.

Dependencies

• com.xwiki.integration-azure-oauth:integration-azure-oauth-api 2.0
• com.xwiki.licensing:application-licensing-licensor-api 1.25
• org.xwiki.contrib:authservice-backport-ui 1.1.1