Skip to main content
Skip table of contents

Two Factor Authentication - Installation and Configuration Guide

All details and scenarios outlined in this document apply specifically to standalone users. Standalone users are those whose credentials, details, or information are exclusively stored in Keycloak. Their information is not synchronized from any external source, such as Cisco. For Cisco users, two-factor authentication will not be managed by Keycloak or our connector, it will be solely handled by Cisco.

Do not enable two-factor authentication for the customers who are using CISCO Finesse, as it will not be manged by Keycloak.

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.

Prerequisites

For SMS Channel:

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

For RSA SecurID Channel:

  • All users must be registered for 2FA with RSA SecurID. The customer themselves will handle the 2FA/OTP registration process, while the Keycloak Connector will only manage the OTP validation mechanism.

Two-Factor Authentication Channels

There are 3 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:

  1. Authenticator (Mobile) Apps - Google Authenticator & Microsoft Authenticator

  2. SMS

  3. RSA SecurID

For Authenticator App, the user will simply scan a QR code displayed on the screen, and Keycloak Connector 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 Authenticator App, alleviating the need for configuration in the Keycloak Adapter, configuration file (config.json), or elsewhere. Therefore, for the Authenticator Apps 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. See Information Required from Twilio.

For RSA SecurID, the Keycloak Connector manages the OTP validation mechanism. The user must already be registered for 2FA with RSA SecurID. The user will need to enter a 14-character passcode (PIN + Token). The Connector will fetch this passcode and validate it against the RSA Server. To ensure seamless communication between the Keycloak Connector and the RSA Server, a few configurational values must be provided in the config (config.json) file. See Information Required from RSA Server.

Limitations & Important Notes for RSA SecurID Channel:

  1. Unlike other methods, Keycloak will not manage the 2FA registration for SecurID. Only OTP validation will be handled by Keycloak.

  2. 2FA registration on SecurID will be handled by the customer.

  3. All users (including admins) created in Keycloak must be registered for 2FA with SecurID beforehand.

  4. All users must have the same username in both Keycloak and SecurID.

Limitation for All Three Channels:

  • There is no option to exclude any user from 2FA. If 2FA is enabled on the solution, it must be used by all users.

Information Required from Twilio

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

  1. Twilio Account SID

  2. Twilio Auth Token

  3. 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:

  1. 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.

  2. 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.

  3. Next, click on ‘Verify’ below ‘Phone Numbers’ in the navigation menu on the left side.

  4. Click on ‘Services’ in the submenu.

  1. 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.

  1. 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’.

  1. A new form/box will be displayed. Don’t make any changes and click ‘Continue’.

  1. After your service is created, you will see following screen:

  2. Copy ‘Service SID’, visible under Friendly name, and save it along with Account SID and Auth Token.

  3. No changes are required on this page but if you make any, make sure to click ‘Save’ button.

  4. You’re done from Twilio’s end.

Information Required from RSA Server

Following is the information required from RSA Server to enable two-factor authentication via RSA (SecurID) Authenticator App:

  1. RSA Server URL

This will be the URL of the RSA Server that the Keycloak Connector will communicate with to validate OTPs. For example, https://<rsa-server-domain-name>:<port>/. Don’t forget to add slash / at the end of the URL.

  1. RSA Client Key

This will be the access key required to communicate with RSA Server. RSA also refers to this as Access Key. For example, en7ujo7001g32e3ues48sguo69fetkmdd85hsele82d6641d496zitr56n1b9e6l.

  1. RSA Client ID

This will be the name or ID of the authentication agent responsible for validating the OTPs. For example, authenticator.

All this information can be fetched from RSA Authentication Manager.

Steps to Add Configurations

  1. Add below configurations for common variables in the kubernetes/helm-values/ef-cx-custom-values.yaml:

CODE 
  efCommonVars_IS_ENABLED_2FA: "true"
  efCommonVars_CHANNEL_2FA: "app/sms/rsa"
  efCommonVars_TWILIO_SID: ""
  efCommonVars_TWILIO_VERIFY_SID: ""
  efCommonVars_TWILIO_AUTH_TOKEN: ""
  efCommonVars_RSA_SERVER_URL: ""
  efCommonVars_RSA_CLIENT_KEY: ""
  efCommonVars_RSA_CLIENT_ID: ""

The values fetched from Twilio OR RSA will go against respective fields in the above mentioned file.

  • efCommonVars_CHANNEL_2FA can have following 3 values:

    • app: If 2FA channel is Google/Microsoft Authenticator apps.

    • sms: If 2FA channels is SMS.

    • rsa: If 2FA channel is RSA SecurID.

  1. Add the following environment variables in agent-manager and unified-admin components with their custom values:

CODE 
        - name: IS_ENABLED_2FA
          value: '{{ .Values.global.efCommonVars_IS_ENABLED_2FA }}'
        - name: CHANNEL_2FA
          value: '{{ .Values.global.efCommonVars_CHANNEL_2FA }}'
        - name: TWILIO_SID
          value: '{{ .Values.global.efCommonVars_TWILIO_SID }}'
        - name: TWILIO_VERIFY_SID
          value: '{{ .Values.global.efCommonVars_TWILIO_VERIFY_SID }}'
        - name: TWILIO_AUTH_TOKEN
          value: '{{ .Values.global.efCommonVars_TWILIO_AUTH_TOKEN }}'
        - name: RSA_SERVER_URL
          value: '{{ .Values.global.efCommonVars_RSA_SERVER_URL }}'
        - name: RSA_CLIENT_KEY
          value: '{{ .Values.global.efCommonVars_RSA_CLIENT_KEY }}'
        - name: RSA_CLIENT_ID
          value: '{{ .Values.global.efCommonVars_RSA_CLIENT_ID }}'

  1. Deploy the CX Core using default values.

CODE 
helm upgrade --install --namespace expertflow --create-namespace   ef-cx  --debug --values helm-values/ef-cx-custom-values.yaml expertflow/cx --version 4.9.3

Disable Two-Factor Authentication

  1. Update below configurations for common variables in kubernetes/helm-values/ef-cx-custom-values.yaml:

CODE 
efCommonVars_IS_ENABLED_2FA: "false"

  1. Deploy the CX Core using default values.

CODE 
helm upgrade --install --namespace expertflow --create-namespace   ef-cx  --debug --values helm-values/ef-cx-custom-values.yaml expertflow/cx --version 4.9.3
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close