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

Method	Path
POST	`/rp/device/pendingqr`

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 Passwordless, 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.

Method	Path
PUT	`/rp/versioned/client/qr/create`

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.

Method	Path
POST	`/rp/api/oob/qr/client/authentication/requests`

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

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.