QR Code Authentication Setup

Purpose

HYPR provides an alternative method to passwordless MFA by supporting the ability to scan a QR code displayed on a computer, coupled with biometric authentication to ensure that the user is physically present to the system requesting access. To make this possible, administrators must first enable QR Code Authentication in Control Center, and then for the affected application.

Instructions

These instructions describe configuration of an Okta single sign-on (SSO) tenant as the relying party.

HYPR Feature Flags are configured via API and require the appropriate permissions. Follow the instructions below to enable the QR Authentication Feature Flags for your tenant.

There is currently no UI available for toggling Feature Flags. QR Code Authentication is controlled via cURL commands. See below for a full description of available parameters.

Obtain an Access Token

You will require both a global and an Application access token to perform the cURL commands necessary for activating QR Code Authentication. Global access tokens are obtained in the same manner, but must be obtained specifically for the controlCenterAdmin Application.

Use existing access tokens for your application or generate new ones. Existing access tokens will have been copied for future use (such as now); if you do not have a stored copy of the access token, you will need to create a new one.

The process for generating a new access token is described in Workforce Access: Access Token.

Update the Relying Party URL for the QR Code

Control Center must be given the RP Application URL (baseURL) to include in the QR Code link. This ensures the scanning device will receive the baseURL from the QR scan.

The following example cURL command is for highlandsbank.com website with an application named highlandsBankWallet. Before running the command, you will need to substitute:

• your server URL for highlandsbank.com
• the access token for the Application for hypap-4212cd0-904d-4ef4-a5b9-4b5547b623e7
• the Application ID (rpAppId) for highlandsBankWallet
• the URL of the application (baseURL)  for https://highlandsbank.com/highlandsBankWallet

curl \
--location \
--request PUT "https://highlandsbank.com/cc/api/appconfig/devicemanager" \
--header "Authorization: Bearer hypap-4212cd0-904d-4ef4-a5b9-4b5547b623e7" \
--header "Content-Type: application/json" \
--data-raw '{
"baseURL": "https://highlandsbank.com/highlandsBankWallet",
"rpAppId": "highlandsBankWallet"
}'

A success response comes in the following format:

{"baseURL":"<url>","rpAppId":"<appId>"}

For our example, this would be the result:

{"baseURL":"https://highlandsbank.com/highlandsBankWallet","rpAppId":"highlandsBankWallet"}

Global QR Code Authentication

QR Code Authentication Feature Flag must be enabled globally before it can be enabled for Applications. The global Feature Flag for QR Code Authentication will display a UI toggle for all web Applications in CC; it will be disabled by default.

Ensure you have a valid, current controlCenterAdmin (global) access token ready to use.

Substitute your URL and the global access token in the code sample below, then run it from a command line:

curl --location --request POST "https://highlandsbank/rp/api/versioned/features/toggle/QR_AUTHENTICATION" --header "Authorization: Bearer 5bf6eb3a-4593-6b70-dc92-b9b22303c41a"

The enabled field shows whether or not QR Code Authentication is working at the global level:

{"version":4,"features":[{"name":"QR_AUTHENTICATION","description":"QR CODE AUTHENTICATION ","enabled":true,"releaseVersion":"6.12.0","deprecatedStatus":false}]}

NOTE: The same cURL command is used to disable the Global QR Code Authentication Feature Flag, and will return "enabled":false in the result when used to do so.

Open any web Application in CC and click Login Settings. The following dialog is now visible:

Toggle this on for the Application(s) you wish to have the option to authenticate users via a QR Code.

Application QR Code Authentication

Ensure you have a valid, current Application access token ready to use, and that the Global QR Code Authentication Feature Flag has been enabled.

Run the following cURL command, substituting your HYPR tenant URL (including the trailing Application ID) and your Application's access token.

curl --location --request POST "https://highlandsbank/rp/api/versioned/features/toggle/QR_AUTHENTICATION/highlandsBankWallet" --header "Authorization: Bearer hypap-12d5fa49-771b-4f54-aa51-f52fc189b1a7"

The "enabled" field verifies whether or not QR Code Authentication is working at the Application level:

{"version":4,"features":[{"name":"QR_AUTHENTICATION","description":"QR CODE AUTHENTICATION ","enabled":true,"releaseVersion":"6.12.0","deprecatedStatus":false}]}

NOTE: The same cURL command is used to disable the Application QR Code Authentication Feature Flag, and will return "enabled":false in the result when used to do so.

KeyCloak Configuration

1. Login to Keycloak and select the realm used to connect to the Application.
2. In the menu at left, click Authentication, then make sure the main pane is on the Flows tab.
   
3. Select HYPR Authenticator (HYPR) (or whatever you have named your Authenticator) from the drop-down menu at the top.
4. Find the Actions menu at the right of the Auth Type entry, and choose Config.
5. A list of toggles and drop-downs displays. Scroll down until you find Use a dynamic link for web login on mobile devices (6.12 HYPR Version Required), and toggle it ON.
   

The user experience now prompts with a QR code upon authentication to affected Applications. Users will still be required to authenticate as defined by policy. See QR Login for a walkthrough of the HYPR QR Code Authentication experience.