Breadcrumbs

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.

    vgYmcgCZBauzv62q9OsE0YX948013APz8Cjq6Yy3n-2X8OML64oAQ4UKSAwzG-QPawr1FmYJa-tkd9kv_l1w_tAtN_gObmtJISQdQJL06pd1XsCegWRDqvgBxoK4c_inzrAU6OcEAuSuH1zzPBXIqOM

    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.

    rJh4ERaWWUlniy-pqZxvvdon3ZTPwL8LhfDp_YDyQiqTClQN5WwAv2-UwgOHyRfTeCwU5pPd7-vJph9eRZgZB9VMPby7B8MLcOUKFv4S-yBo-7Du-fp3o6i9q88hm4OZvUQfIqpY-uSe1UH8iy2YGjU


  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.

    4XWsl-D4W5-VXdMRyqy6EXT6NOlD1RT7caZN_EJL68Ua4BuZEqtNXnK7oy1BYJBVU0R6kzg_RLAO9L78WguuA2KZvG9KfhoujXPOEqecQ4Y5mJBFhs5sB91Qg5IiLmcN7NfaGv3_cKUC4vnb-YscKRs


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

    Z9pLU9O6eU8iUi5-IaIx379gdsJgv24FjlWIDTbjx9kQVQ2ugcHOlFVsp3T9JEkpeSOr3VhUxCDKq2oxcpBRuNZBSGHEAKXnP4BWDLiwXHtVTLedwoNsV94I_6_4th3_5n_iY7L74Y2Tw7MN_i8zRRw


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

    ttKy5xlV2gUWOBatH3xV1tK_mgVT3Ba4fx9ryP40Npq8Y-kCMUWftUxd3STKvrXWYpcUrGDsaJ1kMnoFMZlexNR9qA8uQYv-VoTlqVHViOis8lRKSzg2GxI81KRQV7Mi041UQzrk1xIYvKkOAwwDGYY


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

    UNGQTzYd9jKe19I53nx_Rss4076BjWJQWHSNqrkQnLG1LDdayyM1RV3bZbm5RjuMJzz3GTpGel1U4SVH-kWxAULr_bp6nn8GilRKGLBU2X1u-6DK_lXHepo9tzMa-69-iA-ilBrcz8DkL6TSsMuG8Ck


  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.

Enable Two-Factor Authentication

Add below configuration for common variables under global section in the kubernetes/helm-values/ef-cx-custom-values.yaml:

YAML
  efCommonVars_IS_ENABLED_2FA: "true"
  efCommonVars_CHANNEL_2FA: "app"  # app | rsa | sms

efCommonVars_CHANNEL_2FA can have following values:

  1. app: If 2FA channel is Google/Microsoft Authenticator apps, then the following configurations is required..

    YAML
      efCommonVars_IS_ENABLED_2FA: "true"
  efCommonVars_CHANNEL_2FA: "app"

  2. sms: If 2FA channels is SMS, then the following configurations is required.

    YAML
      efCommonVars_IS_ENABLED_2FA: "true"
  efCommonVars_CHANNEL_2FA: "sms" 
  efCommonVars_TWILIO_SID: ""
  efCommonVars_TWILIO_VERIFY_SID: ""
  efCommonVars_TWILIO_AUTH_TOKEN: ""

  3. rsa: If 2FA channel is RSA SecurID, then the following configurations is required..

    YAML
      efCommonVars_IS_ENABLED_2FA: "true"
  efCommonVars_CHANNEL_2FA: "rsa"
  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 variables.

Deploy the CX Core using default values.

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

Disable Two-Factor Authentication

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

YAML
efCommonVars_IS_ENABLED_2FA: "false"

  1. Deploy the CX Core using default values.

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