Google 2FA Authenticator module

Edition

Incubator (services)

Issues

Git

Git

Latest

1.0

Compatible with Magnolia 6.2.

The Google 2FA Authenticator module helps you leverage Google’s 2-step verification (second factor authentication - 2FA) mechanism for Magnolia’s default login form. A QR code is generated and sent to the user’s email where the user scans the code with the Google Authenticator app. Only after this step is the user allowed access to AdminCentral.

Prerequisites

  • You must have the Mail module installed and the mail server configured in order to proceed.

This module is at the INCUBATOR level.

Administrators need to generate QR codes for users and verify them before enabling the 2FA feature.

If you have already enabled 2FA:

  1. Disable 2FA in Rescue App in case you lose the QR Code.

  2. Generate the QR code.

  3. Enable the 2FA again.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.security</groupId>
  <artifactId>google-2fa-authenticator</artifactId>
  <version>1.0</version>
</dependency>

Configuration

There are a few places in that you’ll need to configure in AdminCentral.


securityCallback

  1. In AdminCentral, go to the Configuration app.

  2. Go to /server/filters/securityCallback/clientCallbacks/form/.

  3. Change the loginForm property to:

    /defaultMagnoliaLoginForm/2fa-login.html

loginHandlers

  1. In AdminCentral, go to the Configuration app.

  2. Go to /server/filters/login/loginHandlers/Form.

  3. Change the class property to:

    info.magnolia.security.googleauthenticator.auth.login.Google2FAFormLogin

qrCodeEmailTemplate

  1. In AdminCentral, go to the Configuration app.

  2. Go to /modules/mail/config/templatesConfiguration/.

  3. Add a new template entitled ga2faQrCodeEmailTemplate. You can do this by clicking Add content node in the edit panel to the right.

  4. In the new ga2faQrCodeEmailTemplate template, give it a Subject property.

    1. Click Add property in the edit panel to the right.

      • Name = Subject

      • Value = Your desired subject line.

      • Type = String

        qrCodeEmailTemplate

OTP Issuer Config

To complete this step, you need to ensure the Google 2FA incubator module is already installed.

  1. Go to /modules/google-2fa-authenticator/config/.

  2. For optIssuer, enter the Opt Auth Issuer configuration which should be specific for each environment.

Usage

This sections covers how to use the module.

Generate token

  1. In AdminCentral, go to the Security app.

  2. Go to System Users.

  3. Select the desired user.

    1. In edit panel, click Generate Security Token.

      ga2fa generate

User interaction

Once the security token is generated, the selected user receives an email prompting them to scan a QR code with the Google Authenticator app.

ga2fa email

Use the token

For the flow to be completed:

  1. The user scans the QR code with the Google Authenticator app.

  2. The user receives a code in the Google Authenticator app.

  3. The user enters the code in the field on Magnolia login screen.

ga2fa login

Manage 2FA

You can manage the 2FA flow within the app itself or via the Rescue app.

  • Enable 2FA

  • Disable 2FA

  • Disable 2FA (Rescue)

  1. Go to /modules/google-2fa-authenticator/config/.

  2. Set enable2FA to true.

    ga2fa config

  1. Go to /modules/google-2fa-authenticator/config/.

  2. Set enable2FA to false.

    ga2fa config

  1. Ensure the Rescue App is enabled.

  2. Use the script to disable 2FA.

    s = MgnlContext.getJCRSession("config");
    s.getNode("/modules/google-2fa-authenticator/config/").setProperty("enable2FA", false);
    s.save();

Changelog

Version Notes

1.0

Initial release of the module

Feedback

Incubators

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Google 2FA Authenticator module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules