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.

Steps to add configurations

Add bellow configurations in the following deployment file
- vi cim-solution/kubernetes/cim/ConfigMaps/ef-common-environment.yaml

CODE

  IS_ENABLED_2FA: "true"
  CHANNEL_2FA: "app"
  TWILIO_SID: ""
  TWILIO_VERIFY_SID: ""
  TWILIO_AUTH_TOKEN: ""

Add bellow environment variables in the following deployment files (admin and agent manager)
- vi cim-solution/kubernetes/cim/Deployments/ef-unified-admin-deployment.yaml
  vi cim-solution/kubernetes/cim/Deployments/ef-agent-manager-deployment.yaml

CODE

            - name: IS_ENABLED_2FA
              valueFrom:
                configMapKeyRef:
                  key: IS_ENABLED_2FA
                  name: variables-common-env-cm
            - name: CHANNEL_2FA
              valueFrom:
                configMapKeyRef:
                  key: CHANNEL_2FA
                  name: variables-common-env-cm
            - name: TWILIO_SID
              valueFrom:
                configMapKeyRef:
                  key: TWILIO_SID
                  name: variables-common-env-cm
            - name: TWILIO_VERIFY_SID
              valueFrom:
                configMapKeyRef:
                  key: TWILIO_VERIFY_SID
                  name: variables-common-env-cm
            - name: TWILIO_AUTH_TOKEN
              valueFrom:
                configMapKeyRef:
                  key: TWILIO_AUTH_TOKEN
                  name: variables-common-env-cm

now delete and apply the following configurations and deployments
- k delete -f cim-solution/kubernetes/cim/ConfigMaps/ef-common-environment.yaml
  k delete -f cim-solution/kubernetes/cim/Deployments/ef-unified-admin-deployment.yaml
  k delete -f cim-solution/kubernetes/cim/Deployments/ef-agent-manager-deployment.yaml
- k apply -f cim-solution/kubernetes/cim/ConfigMaps/ef-common-environment.yaml
  k apply -f cim-solution/kubernetes/cim/Deployments/ef-unified-admin-deployment.yaml
  k apply -f cim-solution/kubernetes/cim/Deployments/ef-agent-manager-deployment.yaml