Google Authenticator Connector

Category: Modules
Subcategory: Authentication

Overview

Authorize users by validating codes which are generated on the device of the user.

Documentation

GoogleAuthenticator Connector

Introduction

This connector enables you to generate a secret key and a otp authentication URL to register an application in the Google Authenticator app on the device of a user. Furthermore, you can use a validation action to validate codes being generated on the device of a user with a secret key.

Configuration

Available actions

Create credentials

  • Create a 'credentials' entity which contains or is associated with a user to store the secret key. Don't forget to set your entity access rules appropriately! Only the business logic of your app should be able to read the secret key.

  • Use a QR code viewer from the Mendix App Store to view the generate otp authentication URL.

  • Create a microflow which receives your 'credentials' entity and passes it as a parameter to the 'Google Authenticator Connector - Create user credentials' action. The action only changes the 'ga_SecretKey' attribute in your entity so you need to commit the entity yourself. (This way you're free in how you take care of your entities and storing of objects).

  • The 'Google Authenticator Connector - Create user credentials' also requires a username and the name of your application(issuer). These values will be reflected in Googles 'Google Authenticator' app on the device of the user, so the user knows which code belongs to an application.

  • Create a page which shows the otp authentication URL as a QR-code to your user. You can use the ImageViewer widget from the App Store for this, for example. It's recommended to show the QR code to the user just once and to not store the value in the database.

Create credentials

Validate code

  • Create a page in your applications where the user can fill in the code which is generated on the device of the user.

  • Pass this code to the 'Google Authenticator Connector - Check validation code' action together with the secretkey stored with the user. (The secret key is available in the 'Credentials' entity which is described under 'Create Credentials' above.)

  • The result of this authentication (boolean) can be used in any way you like.

  • Since TOTP passwords are time-based, it is essential that the clock of both the server and the client are synchronised within the tolerance used by the library (30 seconds by default).

Validate code

Example

The GitHub project of this module contains a working example.

Dependencies

  • googleauth-1.5.0.jar
  • commons-codec-1.15.jar
  • httpclient-4.5.13.jar

Collaboration on this connector

Development of this connector is done through a git project on Github.

This connector uses the GoogleAuth library. https://github.com/wstrange/GoogleAuth/

License

This connector is licensed under the Apache v2 license.

Copyright & Disclaimer GoogleAuth java library

Please find the Copyright notice in the disclaimer on https://github.com/wstrange/GoogleAuth/ or in the GoogleAuthenticator module.

Releases

Version: 2.2.0
Framework Version: 9.3.0
Release Notes: - Converted module to Runtime 9.3.0 - Added how to steps to module
Version: 2.1.0
Framework Version: 7.23.19
Release Notes: - Updated module to MxRuntime version 7.23.19. - Upgraded libraries.
Version: 2.0.0
Framework Version: 6.6.0
Release Notes: CreatedCredemtials action now returns the otp auth url (thanks for feedback Wouter Kremer)
Version: 1.0.1
Framework Version: 6.6.0
Release Notes: - Reduced tolerance time window. - Removed requirement to add an attribute to store a 3rd party generated url, for displaying the qr code.
Version: 1.0
Framework Version: 6.6.0
Release Notes: Initial version