Link Dispatcher

The Link dispatcher allow to generate links that are included in the HTTP response. These links can be opened by a browser running in a mobile device to launch the access application where the user can register credentials or authenticate (depending on the context). The generated links have the information required by the mobile application (notably the token and the redeem URL) to proceed with the operation (registration, authentication or deregistration).

The mobile device client can use the returned links to open the authentication application.

Recommendation

We recommend using this dispatcher over the QR code dispatcher and render the link inside the QR code.

Configuration

Use the link dispatcher type in the Dispatchers Configuration to enable link 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 dispatcher must be used.

The administrator must provide the base URL in the nevisfido.yml file that will be used by nevisFIDO to generate the links.

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.
base-url	yes	String	https://link	The base URL that must be used to generate the links. See Base URL Configuration for details.

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 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 to configure a system exposing the JSON data to be verified. This makes this approach to be 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 Examples

The next example shows a configuration where the link dispatcher is enabled and uses a custom URI scheme:

dispatchers:
  - type: link
    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
    base-url: nevisaccessapp://x-callback-url/authenticate?x-success=https://success.siven.ch&x-error=https://error.siven.ch&x-cancel=https://cancel.siven.ch

The next example shows a configuration where the link dispatcher is enabled and uses HTTPS as scheme:

dispatchers:
  - type: link
    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
    base-url: https://siven.ch

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 included in the link. By using encryption it is guaranteed that only the device associated with the dispatch target can use the generated token.

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 link dispatcher, the client can provide the additional data in JSON format that will be included in the generated link.

Attribute	Type	Description	Default Value	Optional
data		Object	The additional data that will be encrypted into the nma_data attribute of the payload in the link.	true

Dispatch Token Request Example without Encryption

{
  "dispatcher" : "link",
  "dispatchInformation" : {
    "data" : {
      "attributeName" : "some additional data to be included in the link contents"
    }
  },
  "getUafRequest" : {
    "context" : "{\"username\":\"jeff\"}",
    "op" : "Reg"
  }
}

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

{
  "dispatchTargetId" : "0ea3abe9-c26c-4401-b5d5-2c1f4a4fd2eb",
  "dispatcher" : "link",
  "dispatchInformation" : {
    "data" : {
      "attributeName" : "some additional data to be included in the link contents"
    }
  },
  "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.

Dispatch Token Response Format

The format of the dispatch token is described in Dispatch Token Service. The dispatcher returns the link(s) in the dispatcherInformation.response attribute.

Dispatch Token Response Example without Encryption

{
  "token" : "98248c42-c9d5-4332-9b28-c3dc497df311",
  "sessionId" : "78a56656-298d-4e63-abec-1f94153e9e5a",
  "dispatchResult" : "dispatched",
  "dispatcherInformation" : {
    "name" : "link",
    "response" : "https://siven.ch?dispatchTokenResponse=<dispatch contents base64 URL encoded>"
  }
}

The data that is included 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" : "98248c42-c9d5-4332-9b28-c3dc497df311",
    "redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/registration",
    "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

{
  "token" : "98248c42-c9d5-4332-9b28-c3dc497df311",
  "sessionId" : "24140d23-6a2e-467c-bde9-b53602d85772",
  "dispatchResult" : "dispatched",
  "dispatcherInformation" : {
    "name" : "link",
    "response" : "https://siven.ch?dispatchTokenResponse=<dispatch contents base64 URL encoded>"
  }
}

The data that is included 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 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 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.