Available in:

• English
• German
• Spanish
• French
• Italian
• Dutch
• Portuguese (Brazil)

Overview

Agnease Multi-Factor Authentication (MFA) adds a second step to the XWiki login: after the password, users enter a verification code generated by an authenticator app on their phone. Someone who only knows the password can't log in.

This guide is organized by audience: users set up MFA and keep access to their account, administrators enable it, decide who must use it and help users.

How the Login Works

1. The user enters their user name and password on the login page.
2. The authenticator selected for the wiki, standard XWiki, LDAP or Active Directory, checks the password as it does without MFA.
3. The MFA policies of the wiki decide whether the user must set up MFA.
4. The user enters a verification code, or sets up MFA first when it is required and not set up yet.
5. The user is logged in.

Key Terms

Install and Enable

Requirements

• XWiki 16.10 or later.
• Administration rights on the main wiki, and the right to install extensions on the whole farm.
• Access to the xwiki.properties file of the installation, to add the Agnease extension repository.
• For directory logins, the LDAP or Active Directory authentication extension, installed and configured.
• An authenticator app for each user.

Add the Agnease Extension Repository

The application is distributed by the Agnease extension repository, which XWiki doesn't use by default.

1. Open the WEB-INF/xwiki.properties file of the XWiki installation.
2. In the extension.repositories section, uncomment the three default repositories so that XWiki keeps using them.
3. Add the Agnease repository after them:
   extension.repositories = maven-xwiki:maven:https://nexus.xwiki.org/nexus/content/groups/public
   extension.repositories = store.xwiki.com:xwiki:https://store.xwiki.com/xwiki/rest/
   extension.repositories = extensions.xwiki.org:xwiki:https://extensions.xwiki.org/xwiki/rest/
   extension.repositories = agnease.com:xwiki:https://agnease.com/rest/
4. Restart XWiki.

Install the Extension

1. Log in to the main wiki as an administrator.
2. Open Administration > Extensions.
3. Search for MFA Application: the Agnease repository lists it with the other extensions.
4. Click Install on farm, and choose to install it on the whole farm.
5. Check that Standard XWiki Authenticator + MFA is now listed in Administration > Users & Rights > Authentication.

Enable MFA on a Wiki

1. Open Administration > Users & Rights > Authentication on the wiki to protect.
2. Select Standard XWiki Authenticator + MFA, or LDAP Authenticator + MFA or Active Directory Authenticator + MFA when the wiki uses a directory.
3. Click Save.
4. Open Administration > Users & Rights > MFA Settings and review who must use MFA, as explained in Configure MFA Settings.
5. Log out and log in again: users who set up MFA are now asked for a verification code after their password.

Each wiki selects its own authenticator: enabling MFA on the main wiki doesn't enable it on the subwikis.

Test Before Enforcing

1. Open a private browser window, so that no trusted device or login cookie hides the verification.
2. Log in with a test account, set up MFA from its profile and save the recovery codes.
3. Log out, log in again and check that the verification code is asked.
4. Log in once with a recovery code, then once with an app password from a tool, if your users need them.
5. Require MFA for the administrators and a pilot group only, then extend it, as described in Roll Out MFA Gradually.

For Users

Set Up MFA from Your Profile

You can set up MFA at any time, even when it is not required.

1. Install an authenticator app on your phone.
2. Click your avatar at the top right of the wiki, then Multi-Factor Authentication in the profile menu.
3. Scan the QR code with your authenticator app. If you can't scan it, click Can't scan the code? and enter the account name and the key in the app as a time-based key.
4. If a Confirmation code field is displayed, enter the code you received by email, or the setup code given by an administrator.
5. Enter the code displayed by your authenticator app in Code.
6. Optionally, check Trust this device for ... days to skip the verification code in this browser.
7. Click Verify code.
8. Copy the recovery codes into a safe place, such as a password manager: they are shown only once.

Your profile now says Your account uses an authenticator app for multi-factor authentication, and you receive an email and a notification confirming the setup.

Set Up MFA When You Log In

When MFA becomes required for you, the login page asks you to set it up after your password.

1. Enter your user name and password, and click Log-in.
2. Scan the QR code, or enter the key, in your authenticator app.
3. If a Confirmation code field is displayed, enter the code you received by email, or a setup code from an administrator.
4. Enter the code of your authenticator app in Verification code, and click Verify code.
5. Open the Multi-Factor Authentication section of your profile and click Generate recovery codes.

You are logged in and your profile displays your recovery codes once.

While a grace period applies, the login page also offers Set up later, and a banner with a Configure MFA now link reminds you on every page of the days left.

Log In with MFA

1. Enter your user name and password, and click Log-in.
2. Enter the code of your authenticator app in Verification code, or one of your recovery codes when you don't have your phone.
3. Optionally, check Trust this device for ... days.
4. Click Verify code.

You are logged in. This browser doesn't ask for a verification code again while it stays open, for up to 24 hours, or until the trust expires when you trusted the device.

• You have 5 minutes to enter the code after the password, then you must enter the password again.
• When your administrator allows it, and your profile has an email address, click Send me a code by email instead. The code is valid for 5 minutes and works once. It logs you in, but it isn't accepted to change your MFA configuration.

Use Several Authenticator Apps

You can set up up to 5 authenticator apps, for instance on your phone and on a tablet. The code of any of them is accepted.

1. Open the Multi-Factor Authentication section of your profile.
2. In Authenticator Apps, click Add an authenticator app.
3. Scan the QR code with the new app, or enter the key displayed.
4. Enter a Name, such as Tablet, and the code displayed by the new app.
5. If a verification code is requested, enter a current code from an app you already set up.
6. Click Add the authenticator app.

The new app is listed in Authenticator Apps. The first app is named Authenticator app.

To stop using an app, for instance after changing your phone, click Remove next to it: its codes are refused from then on, and your other apps, recovery codes, trusted devices and app passwords are kept. Add the app of the new phone before removing the old one. Your last app can't be removed: reset your MFA instead.

Manage Your Recovery Codes

Each recovery code works once, in place of a verification code. When you use one, you receive an alert telling how many are left.

1. Open the Multi-Factor Authentication section of your profile.
2. Click Regenerate recovery codes, or Generate recovery codes if you have none.
3. Enter a current verification code if requested.
4. Copy the new codes into a safe place.

Your previous recovery codes no longer work.

Manage Your Trusted Devices

1. Open the Multi-Factor Authentication section of your profile.
2. Expand Trusted Devices: the current browser is marked with a dot.
3. Click Remove next to a device you no longer use, or Remove All Trusted Devices if you lost one.

The removed devices ask for a verification code at their next login.

Reset Your MFA

Reset MFA to start over, for instance when you lost all your authenticator apps.

1. Open the Multi-Factor Authentication section of your profile.
2. Expand Danger zone, and enter a current verification code if requested.
3. Click Reset MFA and confirm.

Your authenticator apps, recovery codes, trusted devices and app passwords are removed. Set up MFA again from your profile, or at your next login if MFA is required for you.

Follow Your MFA Activity

Once you set up MFA, the MFA Activity table of your profile lists the MFA events of your account, the most recent first: setup, reset, recovery codes, wrong codes, locks and app passwords, with who performed them.

You also receive a security alert, by email and in the notifications menu, when MFA is set up or reset, when recovery codes are generated or used, when your codes are locked after wrong codes, and when an app password is generated or revoked. The emails always go to the address of your profile; the notifications can be turned off in your notification preferences, under Multi-factor authentication.

For Administrators

Configure MFA Settings

Open Administration > Users & Rights > MFA Settings, change the settings and click Save. The settings are grouped in Who must use MFA, Setup and login and Integrations.

Decide Who Must Use MFA

A user must use MFA when one of these applies:

• they are an administrator of the wiki or have programming rights, and Require MFA for administrators is enabled;
• Require MFA for all users is enabled, and they are in no exempt group;
• they are a member of a group of Require MFA for these groups, and in no exempt group.

With LDAP or Active Directory, the policies apply after the directory synchronized the groups of the user, so directory groups mapped to wiki groups can be required or exempt.

Users who don't have to use MFA can still set it up: once they do, they always enter a verification code. When MFA becomes required for a user who hasn't set it up, the login page offers Set up later during the grace period; after it, the user must set up MFA to log in.

Protect the First Setup

Without confirmation, someone who knows the password of a user who hasn't set up MFA yet can set it up with their own phone and keep the account. Enable Confirm the setup of MFA to prevent it. Users then confirm their first setup with a code sent to the email address of their profile, valid for 15 minutes, or with a setup code.

To give a setup code to a user who can't receive email:

1. Open the profile of the user, then Multi-Factor Authentication.
2. In Setup Code, enter a current verification code if requested.
3. Click Generate a setup code.
4. Give the code to the user in person or through another trusted channel.

The code is displayed once. It works for one setup, for 7 days, and replaces the previous one. Administrators can't generate a setup code for themselves, and the Setup Code section is displayed only while the user hasn't set up MFA.

Help a User Who Lost Access

When the user lost one device only, open their profile, then Multi-Factor Authentication, and click Remove next to its app in Authenticator Apps. The user keeps logging in with their other apps.

When the user has no app and no recovery code left:

1. Open the profile of the user, then Multi-Factor Authentication.
2. Enter a current verification code if requested.
3. Click Reset MFA and confirm.
4. If Confirm the setup of MFA is enabled and the user can't receive email, generate a setup code.

The user receives an alert and sets up MFA again. Their recovery codes, trusted devices and app passwords were revoked: the tools using these app passwords need new ones.

Monitor MFA Adoption

Open Administration > Users & Rights > MFA Overview. The figures count the users with and without MFA, and the tables marked with a warning sign, expanded at first, show what needs attention:

The tables can be sorted and filtered by their columns. The activity only includes the events recorded since the application records them.

Roll Out MFA Gradually

1. Check that the wiki uses an authenticator ending with + MFA.
2. Set up MFA on an administrator account and test the recovery procedure.
3. Enable Confirm the setup of MFA if your users' email addresses are reliable.
4. Keep Require MFA for administrators enabled, and add a pilot group to Require MFA for these groups.
5. Follow Users exposed without MFA during the grace period.
6. Enable Require MFA for all users, and exempt the service accounts.

Authentication and Integrations

Choose the Authenticator

XWiki uses one authenticator per wiki. The + MFA authenticators check the password as the authenticator they are named after, then ask for a verification code.

Configure the directory as usual, then select its + MFA authenticator. Selecting an authenticator without + MFA turns MFA off on the wiki: the administrators of the wiki and of the main wiki are alerted by email, and the change is recorded in the MFA activity.

LDAP, Active Directory and Single Sign-On

MFA applies to the passwords entered on the login page. Single sign-on, where a directory authenticator logs the user in without a password, is not followed by a verification code.

Add Another Password Authenticator

MFA is offered for the password authenticators listed in the mfa.passwordAuthenticators property of xwiki.properties. Each + MFA authenticator has the identifier totp- followed by the identifier of the password authenticator, and totp for the standard one.

Add an identifier only for an authenticator that checks a password typed on the login page, and test the login after restarting XWiki.

Connect Tools with App Passwords

Scripts and tools using the REST API, WebDAV or HTTP Basic authentication can't enter a verification code, so once a user has MFA their password alone is refused. They connect with the user name and an app password.

1. Open the Multi-Factor Authentication section of your profile and expand App Passwords.
2. Enter a Name for the tool, such as Backup script, and choose when it Expires.
3. Enter a current verification code if requested.
4. Click Generate an app password, and copy it: it is shown only once.
5. Configure the tool with your user name and the app password, for instance:
   # Keep the app password out of the script, in an environment variable or a secret store
   curl --user "jdoe:$XWIKI_APP_PASSWORD" \
    "https://wiki.example.com/xwiki/rest/wikis/xwiki/spaces/Main/pages/WebHome"
6. Check that the tool connects: the request above returns the XML description of the page, where the account password alone returns 401 Unauthorized.

The same request from a Python script, with the requests library:

App passwords don't work on the login page. Give each tool its own app password, and click Revoke next to it when the tool no longer needs it. Resetting MFA revokes all of them.

Wiki Farms and Subwikis

Each subwiki selects its own authenticator. A subwiki using MFA takes the settings of the main wiki for the settings it leaves empty, when the main wiki uses MFA too; otherwise the defaults apply. A value set on the subwiki overrides the main wiki.

Users of the main wiki use the same authenticator setup on the subwikis. When the wikis have their own domain names and share the login with the xwiki.authentication.cookiedomains property of xwiki.cfg, they also share the verification and the trusted devices: users going from one wiki to another are asked neither for their password nor for a verification code.

Security and Operations

Protect the MFA Encryption Key

The authenticator keys, recovery codes, app passwords and setup codes are protected with a key kept outside of the database. By default it is generated on first use in the mfa/secret-encryption.key file of the XWiki permanent directory.

When several XWiki nodes share the database, configure the same key on all of them in xwiki.properties, as a Base64-encoded 32-byte key. To keep the key of an existing installation, encode its key file; for a new installation, generate one:

Sessions, Trusted Devices and Locks

Upgrade and Uninstall

To upgrade:

1. Upgrade the extension from the Extension Manager.
2. Test a login with and without MFA, with a recovery code, from a trusted device and with an app password.
3. Check the MFA Overview.

To uninstall, first select an authenticator without + MFA on each wiki using MFA and check that an administrator can log in, then uninstall the extension from the Extension Manager.

Troubleshooting and FAQ

Why Isn't the Verification Code Asked?

Check, in this order, that:

1. the wiki uses an authenticator ending with + MFA, in Administration > Users & Rights > Authentication;
2. the user set up MFA, or MFA is required for them;
3. the browser is not a trusted device, nor verified in the last 24 hours;
4. the user logged in with the login page and not through single sign-on, which MFA doesn't cover;
5. the user is not superadmin.

Why Is the Verification Code Rejected?

• Set the time of the phone automatically: the codes depend on it.
• Wait for the next code: each code works once.
• Choose the right account in the authenticator app, as named by Issuer name shown in authenticator apps.
• Enter the password again if it was entered more than 5 minutes ago.
• After 5 wrong codes, wait for the lock to expire, or ask an administrator.

I Lost My Phone. How Do I Log In?

Log in with a recovery code, then reset your MFA and set it up on the new phone. Without recovery codes, ask an administrator to reset your MFA for you.

Why Can't My Tool Connect Anymore?

Once a user has MFA, the password alone is refused for HTTP Basic authentication. Generate an app password for the tool, and check that the existing one didn't expire, wasn't revoked, and that Allow app passwords is enabled.

Why Isn't the Setup Proposed After a Reset?

Resetting removes the MFA setup without requiring a new one. To require it, enable Require MFA for all users or add the user to a group of Require MFA for these groups.

Why Does a Subwiki Behave Differently?

Check the authenticator selected on the subwiki: inheriting the settings of the main wiki doesn't enable MFA on a subwiki using an authenticator without + MFA. Then check the values set locally in its MFA Settings, which override the main wiki.

Which Authenticator Apps Can I Use?

Any app supporting time-based one-time passwords (TOTP), such as Google Authenticator, Microsoft Authenticator, FreeOTP or 2FAS.

Is It Two-Factor or Multi-Factor Authentication?

Two-factor authentication is a form of multi-factor authentication: the application combines the password with a verification code, which makes two factors.