TOTP Plugin 1.2

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
  • 1Password
  • Auth0 Guardian
  • andOTP - Android OTP Authenticator
  • FreeOTP Authenticator
  • Google Authenticator 
  • IBM Verify
  • LastPass Authenticator
  • Microsoft Authenticator
  • Oracle Mobile Authenticator
  • Sophos Authenticator
  • ...
• iOS
  • 1Password
  • Auth0 Guardian
  • FreeOTP Authenticator
  • Google Authenticator
  • IBM Verify
  • LastPass Authenticator
  • Microsoft Authenticator
  • Oracle Mobile Authenticator
  • Sophos Authenticator
  • ...
• Desktop (Linux,  macOS ou Windows)
  
  • 1Password
  • KeePassXC

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:

1. JDrive client version 4.4 is required.
   https://community.jalios.com/download/jdrive
2. 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