Skip to main content
Version: 8.2511.x.x RR

Link QR Code Dispatcher

The Link QR Code dispatcher allows generating a QR code that contains a URL inside it. This URL can be used to open a mobile application and has the required information (notably the token and the redeem URL) to proceed with the operation (registration or authentication).

The typical use case is the following: the HTTP client displays the returned QR code to the end user. Then the QR code can be scanned by the end-user using the mobile device's default camera app. 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.

Recommendation

We recommend using this method instead of the QR code dispatcher. The reason for our recommendation is that these QR codes contain links and therefore offer a better user experience: Scanning them with the mobile OS camera app will redirect the user to the Access App.

Configuration​

Use the link-png-qr-code dispatcher type in the Dispatchers Configuration to enable Link 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 Link QR Code dispatcher must be used.

The table below describes the possible configuration options:

Configuration KeyMandatoryTypeDefault valueDescription
link-base-urlyesStringhttps://siven.chThe base URL that must be used to generate the links. See Base URL Configuration for details.
registration-redeem-urlnoString<nevisFIDO hostname>/nevisfido/token/redeem/registrationThe URL that must be used to redeem the registration tokens.
authentication-redeem-urlnoString<nevisFIDO hostname>/nevisfido/token/redeem/authenticationThe URL that must be used to redeem the authentication tokens.
deregistration-redeem-urlnoString<nevisFIDO hostname>/nevisfido/token/redeem/deregistrationThe URL that must be used to redeem the deregistration tokens.

Note that at least one operation URL (registration-redeem-url, authentication-redeem-url or deregistration-redeem-url) must be provided for the configuration to be considered valid.

Base URL Configuration​

The base URL is used to generate the links returned by nevisFIDO. This URL must be the same as the one configured in the mobile application to do the association of the application with a URL.

This URL is composed of a URI scheme (HTTPS or a custom scheme) and a domain. If no query parameters are specified in this URL, the generated payload will be attached to the URL as a query parameter with the ? separator as a standalone query parameter. In case the URL includes query parameters, nevisFIDO will attach the generated payload to the URL with the & separator.

There are two approaches to define this URL:

  1. Use an HTTPS URL (recommended)

    When an HTTPS scheme is used, then the URL must refer to a system exposing data used by both Android and iOS to associate the link with the application and to do additional security verifications.

    If the base URL is https://domain.name, then a JSON file containing data for Android must be accessible in https://domain.name/.well-known/assetlinks.json, and another JSON file containing data for iOS must be accessible in https://domain.name/.well-known/apple-app-site-association ( or https://domain.name/apple-app-site-association).

    See Support Universal Links for details regarding the contents that this 3rd party must expose.

    The main advantages of this approach are:

    • There is no possibility of conflict with other applications.
    • This is considered to be a best practice in both iOS and Android because of the additional security provided by the JSON data verification.

    The main disadvantages are:

    • The number of compatible browsers (Firefox, Safari, Chrome, Edge) is smaller than the one supporting custom scheme.
    • This solution requires configuring a system that exposes the JSON data to be verified, making this approach more difficult to deploy.

  2. Use a Custom Scheme (not recommended)

    Use a custom URI scheme (for example nevisaccessapp) that is unique to the application. The provided domain is not relevant when a custom scheme is used. The main advantages of this approach are:

    • Only nevisFIDO and the mobile application must be configured.
    • It is compatible with most browsers in the market: it has been tested in Android with Edge, Firefox, Opera, Chrome, QQ, Mi Browser (from Xiaomi), Baidu Browser (6.0.2), UC Turbo, Samsung browser and Huawei browser. The only incompatible browsers found in Android are the UC Browser and UC Lite Browser.

    The main disadvantage is that multiple applications can have the same custom scheme, so there is no guarantee that the link will be opened with your application. For instance a rogue application could be opened when clicking on the link instead of your application.

info

Visit the Access App link channel and app link best practices documentation for more in-depth information.

Configuration Example​

The next example shows a development environment setup where the Link QR Code dispatcher is enabled:

fido-uaf:
  dispatchers:
    - type: link-png-qr-code
      link-base-url: https://siven.ch
      registration-redeem-url: https://siven.ch/nevisfido/token/redeem/registration
      authentication-redeem-url: https://siven.ch/nevisfido/token/redeem/authentication
      deregistration-redeem-url: https://siven.ch/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 of the link 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 targets 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 Link 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.

AttributeTypeDescriptionDefault ValueOptional
dataObjectThe 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
widthnumberThe desired width (in pixels) of the QR code. The maximum allowed width is 512 pixels. (If the content won't fit, the QR code will be larger.)300true
heightnumberThe desired height (in pixels) of the QR code. The maximum allowed height is 512 pixels. (If the content won't fit, the QR code will be larger.)300true
foregroundColorStringThe color (as RGB String) of the foreground of the QR code.rgb(0, 0, 0) (Black)true
backgroundColorStringThe color (as RGB String) of the background of the QR code.rgb(255, 255, 255) (White)true

Dispatch Token Request Example without Encryption​

{
  "dispatchInformation" : {
    "data" : {
      "attributeName" : "some additional data to be included in the link contents"
    },
    "encodingParameters" : {
      "backgroundColor" : "rgb(255, 255, 255)",
      "foregroundColor" : "rgb(0, 0, 0)",
      "height" : 300,
      "width" : 300
    }
  },
  "dispatcher" : "link-png-qr-code",
  "getUafRequest" : {
    "context" : "{\"username\":\"jeff\"}",
    "op" : "Auth"
  }
}

In the example above a dispatch target is not specified, and thus the contents in the link will not be encrypted.

Dispatch Token Request Example with Encryption​

{
  "dispatchInformation" : {
    "data" : {
      "attributeName" : "some additional data to be included in the link contents"
    },
    "encodingParameters" : {
      "backgroundColor" : "rgb(255, 255, 255)",
      "foregroundColor" : "rgb(0, 0, 0)",
      "height" : 300,
      "width" : 300
    }
  },
  "dispatchTargetId" : "cef38e47-31d8-4324-be00-592599142450",
  "dispatcher" : "link-png-qr-code",
  "getUafRequest" : {
    "context" : "{\"username\":\"jeff\"}",
    "op" : "Auth"
  }
}

In the example above a dispatch target is specified, and thus some of the contents that will be encoded in the link will be encrypted, see below for details.

Dispatch Token Response Format​

The format of the dispatch token is described in Dispatch Token Service. The dispatcher returns a JSON object in the dispatcherInformation.response attribute. The JSON object contains the following attributes:

AttributeTypeDescription
linkQrCodeStringThe QR code as a base64 String containing the link.
linkStringThe link. This is provided for convenience, in the case the HTTP client triggering the dispatching is running in the mobile device.

The QR code is returned as a base64 encoded String, so that 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 link inside the generated QR code is a URL encoded using UTF-8.

Dispatch Token Response Example without Encryption​

{
  "dispatchResult" : "dispatched",
  "dispatcherInformation" : {
    "name" : "link-png-qr-code",
    "response" : {
      "link" : "https://siven.ch?dispatchTokenResponse=<dispatch contents base64 URL encoded>",
      "linkQrCode" : "<QR Code as PNG encoded using base64. It contains the link>"
    }
  },
  "sessionId" : "a9a1fc38-9528-4f18-8993-0d0d66856327",
  "token" : "b7f8e104-057f-4ec6-b2d1-ede17f12ed51"
}

The data in the QR code returned by the linkQrCode attribute is the same as the value of the link attribute. The value of the dispatchTokenResponse query parameter in the link is a base 64 URL String. The base64 URL String, once decoded as a UTF-8 String, contains the following JSON:

{
  "nma_data" : {
    "token" : "b7f8e104-057f-4ec6-b2d1-ede17f12ed51",
    "redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication",
    "attributeName" : "some additional data to be included in the link contents"
  },
  "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​

{
  "dispatchResult" : "dispatched",
  "dispatcherInformation" : {
    "name" : "link-png-qr-code",
    "response" : {
      "link" : "https://siven.ch?dispatchTokenResponse=<dispatch contents base64 URL encoded>",
      "linkQrCode" : "<QR Code as PNG encoded using base64. It contains the link>"
    }
  },
  "sessionId" : "36fdfcb9-9f5a-4909-ade6-795fcdcf3154",
  "token" : "b7f8e104-057f-4ec6-b2d1-ede17f12ed51"
}

The data in the QR code returned by the linkQrCode attribute is the same as the value of the link attribute. The value of the dispatchTokenResponse query parameter in the link 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 structure is the same as the one generated by the FCM dispatcher. The contents of the nma_data attribute are encrypted. An example of encrypted contents is:

{
  "token" : "b7f8e104-057f-4ec6-b2d1-ede17f12ed51",
  "redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication",
  "attributeName" : "some additional data to be included in the link contents"
}

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.