Two Factor Authentication - Deployment Guide

Purpose

This guide aims to assist in configuring the necessary settings to ensure smooth functionality of two-factor authentication, which is implemented in Keycloak NodeJS Adapter, with EF applications.

Prerequisite

Before configuring two-factor authentication, you must have a Twilio account.

Two-Factor Authentication Channels

There are 2 two-factor authentication channels, implemented in the Keycloak Adapter, which will be available to the end user for authenticating himself with two-factor authentication. These channels are:

Google Authenticator Mobile App
SMS

For Google Authenticator, the user will simply scan a QR code displayed on the screen, and it will bind the user profile to that code for generation and validation of OTP in future. A new OTP will be displayed to the user after every 30 seconds and it will invalidate the previous/old OTP. This functionality is internally managed in Google Authenticator, alleviating the need for configuration in the Keycloak Adapter, configuration file (config.json), or elsewhere. Therefore, for the Google Authenticator scenario/channel, no additional settings need to be configured.

For SMS, the Keycloak Adapter uses Twilio’s Verify Service. This service generates OTPs, allows us to send them to valid phone numbers and also verifies them by keeping track of which OTP is sent to which phone number. To ensure seamless flow of two-factor authentication using SMS, you need to set up Twilio’s Verify Service, fetch the important/required information from there and enter it in the config (config.json) file.

Information Required from Twilio

Following is the information required from Twilio to enable two-factor authentication seamlessly via SMS:

Twilio Account SID
Twilio Auth Token
Twilio Verify Service SID

Setting Up Twilio’s Verify Service

Here is the step-by-step guide to set up Twilio’s Verify Service using Twilio’s console and extract required information:

After login, you will see the following screen. Some content or its positioning might be different based on Twilio’s version, but every important option will be visible to you.
If you don’t see this screen, click on your account under ‘Console’ in the top left corner, for example, ‘My first Twilio account’ in the picture above.
From the ‘Account Info’ section, copy both ‘Account SID’ and ‘Auth Token’, as these are first and foremost requirements. Save this information to some safe location/folder on your machine.
Next, click on ‘Verify’ under ‘Phone Numbers’ in the navigation menu on the left side.
Click on ‘Services’ in the submenu.
Click on the ‘Create new’ button for creating a new service. You may not see any list of services if you are creating a service for the first time.
Fill in the required information, check ‘Authorize the use of friendly name’ and enable SMS channel. Add notes (description of service) if you want to and click ‘Continue’.
A new form/box will be displayed. Don’t make any changes and click ‘Continue’.
After your service is created, you will see following screen:
Copy ‘Service SID’, visible under Friendly name, and save it along with Account SID and Auth Token.
No changes are required on this page but if you make any, make sure to click ‘Save’ button.
You’re done from Twilio’s end.

Setting Up Configuration File (`config.json`)

The configuration file for Keycloak Adapter is the one where all the necessary information is stored which is required by the adapter to work properly. It is a JSON file which contains information in key-value pairs. Default config file contains following information:

JSON

{
  "realm": "yourRealmName",
  "auth-server-url": "https://your-auth-server.com/auth/",
  "ssl-required": "external",
  "resource": "yourResourceName",
  "verify-token-audience": false,
  "credentials": {
    "secret": "ef61df80-061c-xxxx-xxxx-387e6bf67052"
  },
  "use-resource-role-mappings": true,
  "confidential-port": 0,
  "policy-enforcer": {},
  "CLIENT_ID": "yourClientID",
  "CLIENT_DB_ID": "ef61df80-061c-xxxx-xxxx-387e6bf67052",
  "GRANT_TYPE": "password",
  "GRANT_TYPE_PAT": "client_credentials",
  "USERNAME_ADMIN": "admin",
  "PASSWORD_ADMIN": "admin",
  "SCOPE_NAME": "Any default scope",
  "bearer-only": true,
  "GROUP": "Agent_Group"
}

After ‘GROUP’ key, you need to add the information that you extracted from Twilio. After adding the information, the file will look like:

JSON

{
  "realm": "yourRealmName",
  "...": "...",
  "GROUP": "Agent_Group",
  "TWILIO_SID": "yourTwilioSID",
  "TWILIO_AUTH_TOKEN": "yourTwilioAuthToken",
  "TWILIO_VERIFY_SID": "yourTwilioVerifySID"
}

After adding all this information into config.json, you’re done with all the configurations/settings and are good to go!

Be careful about the spellings and case of the key-value pairs entered.

Setting Up Environment Variables for Agent Manager

Add the following environment variables in agent manager to enable/disable 2FA

CHANNEL_2FA could be ‘app' or 'sms’ depending on the channel you are using

CODE

IS_ENABLED_2FA=true
CHANNEL_2FA=app

Be careful about the spellings and case of the variable and values.