TOTP Plugin 1.2
Description
Enhance the access security of your JPlatform site with a strong two-factor authentication based on TOTP (Time based One Time Password).
When to use this plugin?
Do some of your staff require a more secured access to your Digital Workplace? With the TOTP plugin, you can activate two-step authentication for a target population: for these users, the authentication verifies that they possess the mobile phone they have previously configured to access the site.
What does this plugin do?
The TOTP module enables a strong two-factor authentication: this requires users to enter, in addition to tehri usual password, a Time based One Time Password (TOTP). This password is generated by a two-step authentication application that users will have previously installed on their mobile phone.
For users whose authentication is configured as two-factor with this plugin:
- At their first login, they will need to scan a QR code with a two-step authentication application (Google Authenticator, Microsoft Authenticator, Lastpass Authenticator, etc.)
- They will have to fill in the generated TOTP in order to validate their phone
- To authenticate themselves, they will now also have to enter the TOTP generated by the two-step authentication application
- Once authenticated, they can choose to declare the device they are using as a trusted device: the TOTP code is then no longer required for this device for the duration of the trusted device's validity.
The plugin also provides an easy administration tool to configure :
- the ability to use recovery keys
- which groups require a strong two-factor authentication
- which groups do not require a strong two-factor authentication
- if two-factor strong authentication is required for administrators
- the validity period of trusted devices
The administrator can also reset a user's TOTP when the user no longer has access to it and is unable to authenticate.
What our customers like about it
Compatibility with multiple authentication applications
This solution is compatible with all authentication applications following the RFC-6238, including many free, proprietary or open source applications to be installed on mobile, iOS or Android. Our users can therefore choose to install the application that suits them best on their own phone.
Ease of implementation
The security policy defined by our ISSM indicated that all accesses with advanced write privileges, technical and functional administrators, be subject to strong two-factor authentication. With the TOTP module, the configuration was quick and users were able to configure their TOTP very easily.
Screenshots
Installation
1. Administration
1.1 Installation
Add the plugin to your JPlatform application and restart.
The plugin is ready to use.
1.2 Plugin configuration
1.2.1 Require 2-step authentication for some users (groups)
In the default configuration of the plugin, the 2-step authentication can be configured explicitly by users from their profile edition, but it remains optional.
You can require its use for some members :
- Acces admin area.
- [Optional] Create dedicated group in which you will reference the users or subgroups that will have to use the 2-step authentication.
- Accces plugin properties
- Fill the "Require TOTP for Member of Groups" with the newly created group or any group of your choice
- Save
1.2.2 Require 2-step authentication for administrators
You can require the use of 2-step authentication for administrators to do this:
- Access the site administration interface.
- Access the plugin properties
- Select "Yes" on the "Require TOTP for Administrators" option.
- Save
1.2.3 Require 2-step authentication following other conditions through access rules
You can require the use of 2-step authentication under certain technical conditions through the implementation of an access rule.
Please refer to the SSO plugin access rules documentation for more information on this topic: Règles d'accès des plugins de SSO (aka AccessRules)
The declaration of the access rule is performed through property, using the prefix jcmsplugin.totp.target.access-rule
.
Example of a rule requiring 2-step authentication as soon as the application is accessed from a specific IP address range:
jcmsplugin.totp.target.access-rule.class: com.jalios.jcms.authentication.rules.IpAccessRule
jcmsplugin.totp.target.ip-access-rule.regex: ^192\\.168\\.0\\..*
1.2.4 Exclude 2-step authentication through access rules
Since version 1.2 of the plugin, you can specify an acces rule to specify when 2-step authentication is not required.
The declaration of the access rule is performed through property, using the prefix jcmsplugin.totp.excluded-target.access-rule.
Example of a rule to exclude the need for a 2-step authentication as soon as the application is accessed from a specific IP address range:
jcmsplugin.totp.excluded-target.access-rule.class: com.jalios.jcms.authentication.rules.IpAccessRule
jcmsplugin.totp.excluded-target.ip-access-rule.regex: ^172\\.16\\.0\\..*
1.2.5 Exclude certain accounts from 2-step authentication
Depending on your security policy and your organization, it may be useful or necessary to always exclude 2-step authentication for some accounts:
- User Support Account
- Shared Accounts
- Technical account
- ...
You can exclude users via their membership of a group for this purpose
- Go to the administration interface of the site.
- [Optional] Create a dedicated group in which you will reference users or subgroups that should NEVER use 2-step authentication
- Access the plugin properties
- Fill in the field "Never require TOTP for Member of Groups" with the newly created group or with another group of your choice
- Save
1.3 Advanced plugin configuration
1.3.1 Disabled recovery key
In the default configuration of the plugin, recovery keys are displayed to the user during the initial configuration of the 2-step authentication:
These keys can be used by the user to access the application, in case of loss of his authentication application or if the latter is not accessible to him.
You can disable the use of recovery keys from the plugin properties.
If the user authentication application is lost, an administrator can reset it from the member management interface. (see dedicated section below)
1.3.2 Hash algorithm SHA-1, SHA-256 or SHA-512, code length, validity period
Many of the most used TOTP applications on the market do not support other hash algorithms than SHA-1
(the only one required by default in the RFC 6238): Google Authenticator, Microsoft Authenticator, LastPass Authenticator, Duo Mobile, Authy, 2FAS Auth, ...
Only a few less popular applications support the other algo explicitly: Oracle Mobile Authenticator, Auth0 Guardian, Sophos Authenticator, FreeOTP Authenticator, IBM Verify, andOTP, ...
For this reason, and as it seems preferable to us to guarantee users the possibility to use a TOTP code (and thus to increase the security of their access), rather than absolutely wanting to do secure by default at the risk of preventing the implementation of the two-factor authentication (MFA), the plugin is delivered as standard with the use of the SHA-1
.
If you are able to impose a specific TOTP authentication application to your users, supporting a stronger algorithm, it is possible to use SHA-256
or SHA-512
To do so set the following property with the value SHA256
or SHA512
:
jcmsplugin.totp.code-generation.hashing-algorithm: SHA256|SHA512
The same type of restrictions also apply for other settings specific to the implementation of RFC 6238.
If you can impose the TOTP application to be used and it supports settings different from those provided as standard in the plugin, you can change them with the following properties :
- Code length (which most applications require 6 digits). with a value between 6 and 10 digits :
jcmsplugin.totp.code-generation.code-digits: 8
- Code validity period (default 30 seconds)
jcmsplugin.totp.code-verification.time-period: 30
1.4 Reset the 2-step authentication of a user
If user loses the 2-step authentication application, user authentication on the site is no longer possible.
The administrator can reset the 2-step authentication for this user:
- Go to the administration interface of the site members.
- Open a user's context menu
- Click "Reset 2-step authentication..."
- Validate
- The user can now re-configure the 2-step authentication.
Note that configuration will be required if a group is configured in the site administration and the user belongs to this group.
2. User documentation
2.1 Configuration de l'application d'authentification
You can explicitly enable 2-step authentication from your user profile, or the site administrator can force you to use it.
In any case, the configuration is done using an authentication application (usually on a smartphone):
- Either by scanning the QR code with the camera
- Either by manually entering the secret code
After entering this information in your application, a code is displayed and must be entered on the site to proceed with authentication
See section What authentication applications are supported?
2.2 Trusted device management
When you frequently connect from a device, you can choose to trust the device during the authentication phase so that entering the code is not required for a certain period of time.
By assigning a name to this device, you will be able to find it and identify it precisely from your user profile
Note: an explicit disconnection from a trusted device automatically causes it to be deleted.
3. FAQ
3.1 What authentication applications are supported?
Here are some authentication applications that are compatible with 2-step TOTP authentication.
This list is not exhaustive and is not a recommendation.
- Android
- iOS
- Desktop (Linux, macOS ou Windows)
3.2 How to authenticate with a non-interactive client (monitoring, OpenAPI, etc.)
If one of the following authentication methods is used, the authentication is considered secure and the entry of a TOTP code is not required
- JSON Web Token (JWT) Authentication
- AuthKey authentication
For your non-interactive clients, it is imperative that you use one of these authentication methods.
Otherwise, you will need to use an account for which 2-step authentication is not required.
3.3 Is it possible to use the delegation on an account that has configured 2-step authentication?
Yes.
You do not need to enter a TOTP code to use the delegation.
3.4 Is 2-step authentication compatible with JDrive?
2 prerequisites are required to use 2-step authentication with JDrive:
- JDrive client version 4.4 is required.
https://community.jalios.com/download/jdrive - When logging in, the user must select the browser authentication mode:
3.5 Is 2-step authentication compatible with the JMobile application?
Version 1.1 of the JMobile application is required.
https://community.jalios.com/plugin/jmobile
3.6 Is 2-step authentication compatible with WebChat / OpenFire
Version 3.3 of the WebChat plugin is required.
https://community.jalios.com/plugin/webchat
Changes
https://issues.jalios.com/browse/TOTP?report=com.atlassian.jira.plugin.system.project:versions-panel
Version 1.2 :
- évolution :
- possibilité de définir une règle d'accès précisant les circonstances durant lesquelles un code TOTP n'est pas demandé (même si l'utilisateur l'a configuré)
- correction :
- erreur CSRF si le formulaire est soumis trop rapidement avant chargement complete de la page
Version 1.1 :
- évolution :
- Ajout de traductions supplémentaires
- Focus par défaut sur les champs de saisi pour une meilleure expérience utilisateur
- correction :
- redirection vers la page d'accueil après expiration de la session
- corrections mineures sur les messages affichés aux utilisateurs
Version 1.0 : diffusion initiale du module