QR Fallback Controls

For instances where a HYPR Mobile App device has a broken camera, this feature provides users a fallback mechanism to still register and authenticate without having to scan a QR code using the HYPR Mobile App.

When the server gets the QR Fallback request, it caches the expected payload from the QR image as a .JSON string, then uses it to generate an activation code, which the user then enters to pair the device. In keeping with already existing HYPR precedents in the HYPR Workforce Access Client for offline authentication recovery codes, the code consists of six alphanumeric characters. This random activation code is generated securely via OWASP-recommended methods.

The user experience assumes the following:

• The user's device has either a broken or disabled camera; or perhaps using the camera is not allowed; or the user just does not wish to use it
• HYPR Mobile App is installed on the device
• HYPR Workforce Access Client is installed on the workstation

The entire user flow is described in full detail in QR Fallback.

New Endpoint (Open API)

This new API is OPEN (no API token needed). This is because registration attempts specifically will not have the ability to access API tokens until the registration is complete. This new endpoint is simply an alternative means to link the client and mobile device, mostly centered around a unique 64-digit PIN they need to share during auth/registration flows.

Upon opening the Manual Entry screen, the HYPR Mobile App will communicate with a new Server API.

This Server API, living at /rp/versioned/device/pendingqr has been implemented along side a new cache store. This cache now houses pending QR response payload values, which are the keys to retrieve these payloads: the activation code mentioned above, again displayed by the client to the user. The server will now search its cache and return the appropriate response. The contents of the response from this API match the payload of information that would be stored in the QR image itself. The HYPR Mobile App, receiving a response from server, will continue with the QR flow as it currently exists, using the payload that is provided via the cache lookup.

📘

Endpoints and Payloads

The payload that is cached during the creation of the QR codes will vary based upon the API that is used to generate the QR code.

For example, authentication attempts created via the endpoint /oob/qr/client/authentication/requests will have a completely different .JSON structure than a QR code created via /rp/versioned/client/qr/create being used for registration.

Request

{  
  "activationCode": "acotlc"  
}

Response

Provided below are examples for both responses that can be expected when retrieving fallback payloads from their respective APIs (also labeled above each response).

Example Response 1 (authentication/registration QR code originating via /rp/versioned/client/qr/create):

"qrCode": "{  
            "rpAppId":"controlCenterAdmin",  
            "rpUrl":"<http://localhost:8009/rp">,  
            "pin":"32dabeb155a7b10319c77ce050577ba2f12229a8668755d0277b7614ce172f7e",  
            "traceId":"1cf52d2b7160fe45",  
            "sslPins":\[],  
            "machineAPIVersion":4,  
            "serverMinAPIVersion":3,  
            "serverMaxAPIVersion":4  
            }"

Example Response 2 (authentication QR code originating via /rp/api/oob/qr/client/authentication/requests):

"qrCode": "{  
            "dynamicLink":"<https://hyprapp.page.link?link=https%3A%2F%2Fhypr.com%2Fdynamiclink%3FrpUrl%3Dhttps%3A%2F%2Fhypr73201.int.hypr.com%2Frp%2Foob%2Fdevice%2Fauthentication%2Fretrieval%2Fc05c1e058abe1fd6e764bc32ee204fb4d045abe78526d6aa610b9584331ae91d%26action%3DAUTH&apn=com.hypr.one&amv=1&ibi=com.hypr.one&ius=hypr&isi=1343368858&ofl=https://hypr73201.int.hypr.com/rp/oob/qr/client/landing/c05c1e058abe1fd6e764bc32ee204fb4d045abe78526d6aa610b9584331ae91d?error=MOBILE_BROWSER_REQUIRED&afl=https://hypr73201.int.hypr.com/rp/oob/qr/client/landing/c05c1e058abe1fd6e764bc32ee204fb4d045abe78526d6aa610b9584331ae91d?error=NOT_INSTALLED">,  
            "landingPage":"<https://hypr73201.int.hypr.com/rp/oob/qr/client/landing/c05c1e058abe1fd6e764bc32ee204fb4d045abe78526d6aa610b9584331ae91d">,  
            "sessionId":"c05c1e058abe1fd6e764bc32ee204fb4d045abe78526d6aa610b9584331ae91d"  
            }"

• The successful response status is 200 accompanied by a .JSON representation of the DeviceAuthenticationQrRequestResponse or QRCodeMetadata object
• The response for a request that is unable to be processed, which indicates that the pending auth/reg does not exist in cache is 400

Adjustments to Existing Endpoints

Create QR

Once initiated from HYPR Device Manager or HYPR Workforce Access Client, QR Fallback sends an additional create QR code request, specifying it as a fallback attempt by appending includeQRFallbackCode: true to the request; this triggers Control Center to cache the respective QR response payload (authentication or registration).

For both authentication and registration, an activation code is paired with only specified QR requests coming into CC.

👍

Cache on Delivery

This call leaves generation of the fallback activation code tied to the initiation of the fallback QR flow, meaning HYPR only caches payloads that the user specifies (wait for the user to click, “show activation code”) instead of caching all payloads from which realistically only a fraction would need to be looked up manually.

Request

{  
    "version":4,  
    "rpAppId":"{{appId}}",  
    "pin":"{{pin}}",  
    "rpUrl":"{{url}}/rp",  
    "includeQRFallbackCode": true // New variable to request fallback code in payload  
}

📘

More Keys

Encoded in QR metadata will now be an additional key pair value for activationCode which will appear client will not receive back along with the usual payload. This key pair value will exist in the new payload as "actionCode": "8E3nf8".

Response

{  
"qrCode":"iVBORw0KGgoAAAANSUhEUgAAAMkAAADJAQAAAAChvSuoAAADsElEQVR4Xu2XvY3kMAyFOVCgbNyAALWhzC15GvCMG7BbUqY2DKgBO1MgmPc49uz9ABcchbvohA129RlLm3p8pIh/t170687X+o9+XH8DHURdpI4r9Wa2Zi88FaK+AfU8936JZiP3wKb1oEcLCmYpfk+1i+tg3UDrraz3NjT3eS9uJD8lszDvzWhJdLfvJNh1IN+KJBuOgntGUDNx7X5K1J8jonvI808/349Sgd7L3QPviJUQFMm5FKVDB5lXT0gCF7pFsyd3S+7RgiwNIS/FEY6ezUH56M2VDSXKU8mc3NC7u5X0PqN7XrFUKNSBaOh5FxkgLTRSXpqQn23GJzwKaN4hAKi0AXHJiIL9w6LS/RaQDXxIA0p+7itZ87Ly2CIS9efL69BB8v8Xxp+gfibDKU8NiJOZxIUyx/pk1LsU0ZUNLdosL6J2fEKGUAdLZ5krEcN81nuA5g32u+RfwXVnLB0qZuuzUIvqdmPIeHg+Y+lQ5NkiA3W0MHPD0aPqT83rEIoIKt2TmSlPCdngzUoJ6BHh0PH56yBuiWxAn/5LGwrEEbZTYUETwz3gujS+zU2NUDu3VEnyjBBQF7qD31oQGiucJ8LZUODwEA9ne7Ugu+LcoaglyjAglY46us5LhQh+y1N0d2JU+mbRDT8NUYfQsKyZg4EDoyEiw3NYxyZk4JO3WEeJhTLPKIErGzrUr9JP4UXIBqqSV/rKhg6RG/v6SAjKG6oSnSKgkekRqgZOiz7ICYJHHWHGWM8Oq0QJJQnfEGcDwkA1hHo5mw7hgMjsvHZoiHhtNAu0ic9raBBsJ5olYkqBF6FH4Ow+Za5CB9W79VNxj4RNehbP6cqGEuGYCFGgAShqfUT0L/6ITYUwR5HM3kgFoZqgKJRSC7KYc1A1dRAH9oeEk7lCjwKSkGdRFJRJGPPGQM8GJN6b5NSgokmcLW/Wn9lQIlhuqYNdRwvTwDjhnvKkHkk2GDu4XuF2gFOjL83rkPzb4EZMehhRoFVGkX6yoUMRGXYy6b2HW455C5eidAjDLZxtSdImOrTFJG9+TXo6RDJHbTI3QvweVrzh6tqAsJYEJz+HqPVR3r+3oQNHz34OeOZ9wewxMOuR3Np6/yIR51LgbHJx+xiRCiGZhc+L2xzw5tK/5jOWDmHIwfBZ6kOyQZgu0HGeZyw1snxOejIDEL0duA0RLxFywr5YB/X1eywFkrs5vAiWW7voBuswPV5i0yGcF72djdG4UZse0+l1oVOh363/6Mf1T9E3CXq8evvX5CQAAAAASUVORK5CYII=",  
  // Securely generated 6 lowercase character code, GET API request & key for cache retrieval  
  "qrFallbackActivationCode": "lpptzh"  
}

• The successful response status is 200 accompanied by an encoded QR string
  • Add "includeQRFallbackCode": true to the request and the response body will also include "qrFallbackActivationCode": {{CodeForGETAPIRetrival}}
• The response for a request body unable to be processed is 400

Java SDK- and Keycloak-specific Endpoint Adjustments

The API below is specifically used by Keycloak to authenticate users with QR codes, it contains a different payload and response than the authentication attempts above. The main consumer of this endpoint is HYPR’s Java SDK, which uses Keycloak for access.

To specify fallback caching is needed for this authentication request, which is false by default, a new value must be added to the request body. This follows the same appended value to the request body for the /qr/create endpoint.

• The successful response status is 200 accompanied by an encoded QR string, which alone has been the existing body
  • Add "includeQRFallbackCode": true to the request and the response body will also include "activationCode": {{$CodeForGETAPIRetrival}}, the code uses for authentication
• The response for a request body unable to be processed is 400

Feature Flag and the Control Center UI Toggle (for CC+SDK entries)

The workings of the API and all the subsequent consumers (HYPR Mobile App, HYPR Workforce Access Clients) are all placed behind the toggle of the same feature flag: ENABLE_QR_FALLBACK.

There are two types of flag toggles that can affect the functionality of this feature, both on a global level as well as an RP Application-specific level. Both have different intended purposes.

Global Activation

The GLOBAL feature flag controls access to this feature's endpoints and use of the entire feature:

• Enabled:
  • All endpoints can be accessed
  • No block on server to any functionality
  • The toggle becomes available in Application Login Settings
• Disabled:
  • Requests coming into the new cache lookup API will be denied
  • Activation code generation requests will be ignored
  • Toggle is not visible in Application Login Settings

Application-level Activation

On an RP application level, this flag will act as a toggle, turning the feature on and off just as the toggle would on the [Login Settings] UI page. The UI availability on the HYPR Workforce Access Client and HYPR Mobile App is governed by this flag.

• Enabled:
  • An option to Login Manually is presented in HYPR Workforce Access Client and HYPR Mobile App QR Login interactions
• Disabled:
  • CC will give the same response as if the global flag was disabled, but only for the specified Application
  • All access to APIs will throw an error indicating qrFallbackEnabled should be set to true for the Application's push configuration settings
  • No calls will be made to the server
  • HYPR Workforce Access Client and HYPR Mobile App UI elements related to QR Fallback are disabled

Audit Trail Event

A new audit event, QR_FALLBACK_PAYLOAD_RETRIEVED, has been added to server to indicate when a QR fallback cache request is made, regardless of whether the attempt was successful or not. This is handled entirely by Control Center and occurs when the new endpoint /rp/device/pendingqr receives a request.

See Event Descriptions for the entire list of HYPR Events.

👍

Privacy Please

Payloads of fallback requests DO NOT contain any information that can label a user accurately in an Audit Trail Event.

Currently no Audit Trail Events cover creation of registration or authentication QR images.

📘

Application-specific

Events will be visible in the Audit Trail of the RP Application on which they’re specifically occurring.