QR Code Dispatcher

The QR Code dispatcher allow to generate a QR code that is included in the HTTP response. This QR code has the information required by the mobile application (notably the token and the redeem URL) to proceed with the operation ( registration, authentication or deregistration).

This can be used for example as a fallback mechanism when a push message could not be sent to the client. The HTTP client can display the returned QR code to the end user. Then the QR code can be scanned by the end-user using the mobile authenticating device. So this can be used as an "out-of-band" mechanism to transmit the required information to proceed with the operation.

The QR codes are generated in PNG format.

Configuration

Use the png-qr-code dispatcher type in the Dispatchers Configuration to enable PNG QR code dispatching. This is the value that must also be used by the HTTP client in the Dispatch Token Service when specifying the value of the dispatcher attribute, if the QR code dispatcher must be used.

The table below describes the possible configuration options.

Configuration Key	Mandatory	Type	Default value	Description
registration-redeem-url	no	String	[nevisFIDO hostname]/nevisfido/token/redeem/registration	The URL that must be used to redeem the registration tokens.
authentication-redeem-url	no	String	[nevisFIDO hostname]/nevisfido/token/redeem/authentication	The URL that must be used to redeem the authentication tokens.
deregistration-redeem-url	no	String	[nevisFIDO hostname]/nevisfido/token/redeem/deregistration	The URL that must be used to redeem the deregistration tokens.

QR Code Dispatcher Configuration Options

Configuration Example

The next example shows a development environment setup where the PNG QR code dispatcher is enabled:

dispatchers:
  - type: png-qr-code
    registration-redeem-url: http://localhost:9080/nevisfido/token/redeem/registration
    authentication-redeem-url: http://localhost:9080/nevisfido/token/redeem/authentication
    deregistration-redeem-url: http://localhost:9080/nevisfido/token/redeem/deregistration

Encryption

If the client specifies a Dispatch Target Service identifier in the dispatch token request, then the encryption key of the dispatch target will be used to encrypt the contents that will be encoded in the QR code. By using encryption it is guaranteed that only the device associated with the dispatch target can use the generated token. The use of encryption avoids social engineering attacks such as QRLJacking.

The same algorithms described in the FCM dispatcher Encryption section are used with this dispatcher.

Note that to use encryption, dispatch targets must be configured as described in the Dispatch Target Format section.

Dispatch Targets

This dispatcher does not require a target to be provided in the dispatch target and thus the dispatch targetes created for the FCM dispatcher can be used with this dispatcher.

It is recommended to reuse the dispatch targets created for the FCM dispatcher when using this dispatcher (i.e. do not create new dispatch targets for this dispatcher if dispatch targets for the FCM dispatcher are defined). Reusing the same dispatch target simplifies the managing of the dispatch targets on the authenticating (mobile) device.

Dispatch Token Request Format

Use the dispatchInformation attribute of the Dispatch Token Service to specify information for the dispatcher. In case of the QR code dispatcher, the client can provide the additional data in JSON format that will be included in the generated QR code. In addition to this data, the client can provide the size and colors to be used to generate the QR code.

Attribute	Type	Description	Default Value	Optional
data	Object	The additional data that will be encrypted into the nma_data attribute of the QR code. This information will be sent inside the QR code, so its size limitations apply here.	-	true
width	number	The width (in pixels) of the QR code. The maximum allowed width is 512 pixels.	300	true
height	number	The height (in pixels) of the QR code. The maximum allowed height is 512 pixels.	300	true
foregroundColor	String	The color (as RGB String) of the foreground of the QR code.	rgb(0, 0, 0) (Black)	true
backgroundColor	String	The color (as RGB String) of the background of the QR code.	rgb(255, 255, 255) (White)	true

Dispatch Token Request Example with Encryption

{
  "dispatchTargetId" : "0ea3abe9-c26c-4401-b5d5-2c1f4a4fd2eb",
  "dispatcher" : "png-qr-code",
  "dispatchInformation" : {
    "data" : {
      "attributeName" : "some additional data to be included in the QR code"
    },
    "encodingParameters" : {
      "width" : 300,
      "height" : 300,
      "backgroundColor" : "rgb(255, 255, 255)",
      "foregroundColor" : "rgb(0, 0, 0)"
    }
  },
  "getUafRequest" : {
    "context" : "{\"username\":\"jeff\"}",
    "op" : "Auth"
  }
}

In the example above a dispatch target is specified, and thus some contents that will be encoded as a QR code will be encrypted.

Dispatch Token Response Format

The format of the dispatch token is described in Dispatch Token Service. The dispatcher returns the QR code in the dispatcherInformation.response attribute. The QR code is returned as a base64 encoded String. This way the QR code can be easily rendered as an image using the data scheme described in RFC 2397. For example:

<img src="data:image/png;base64, [PNG as base 64]"/>

The String in the generated QR code is JSON encoded as a base64 URL String. The JSON uses UTF-8 encoding. The reason to use base64 URL instead of directly JSON with UTF-8 is to maximize the compatibility with different QR code scanners: may of the scanners assume UTF-8 as the character encoding, but others use other character encodings such as ISO-8859 or JIS8, which are the default character encoding for some QR code standards. Using only ASCII characters avoids having character encoding issues at the scanning level.

Dispatch Token Response Example without Encryption

{
  "token" : "98248c42-c9d5-4332-9b28-c3dc497df311",
  "sessionId" : "51b8e5f3-7575-41df-93af-fb8ac0777880",
  "dispatchResult" : "dispatched",
  "dispatcherInformation" : {
    "name" : "png-qr-code",
    "response" : "<QR Code as PNG encoded using base64 URL>"
  }
}

The data that is encoded in the QR code is a base 64 URL String. The base64 URL String, once decoded as a UTF-8 String, contains the following JSON:

{
  "nma_data" : {
    "token" : "98248c42-c9d5-4332-9b28-c3dc497df311",
    "redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication",
    "attributeName" : "some additional data to be included in the QR code"
  },
  "nma_data_content_type" : "application/json",
  "nma_data_version" : "1"
}

The data structure in the nma_data attribute is the same as the one generated by the FCM dispatcher (but in this example it is not encrypted).

Dispatch Token Response Example with Encryption

{
  "token" : "98248c42-c9d5-4332-9b28-c3dc497df311",
  "sessionId" : "cf34f631-4180-4e85-91dc-a96dcf5aa9b8",
  "dispatchResult" : "dispatched",
  "dispatcherInformation" : {
    "name" : "png-qr-code",
    "response" : "<QR Code as PNG encoded using base64 URL>"
  }
}

The data that is encoded in the QR code is a base 64 URL String. The base64 URL String, once decoded as a UTF-8 String, contains the following JSON:

{
  "nma_data" : "<encrypted data>",
  "nma_data_content_type" : "application/jose",
  "nma_data_version" : "1"
}

The data in the nma_data attribute is encrypted using the standard JWE using compact serialization. The data structure is the same as the one generated by the FCM dispatcher. In this example, the encrypted contents are:

{
  "token" : "98248c42-c9d5-4332-9b28-c3dc497df311",
  "redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication",
  "attributeName" : "some additional data to be included in the QR code"
}

Note that the specified information in the data attribute in the dispatch token request is present in the encrypted payload included in the nma_data attribute.