Skip to main content
Version: 7.2405.x.x LTS

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.

This can be used for example as a fallback mechanism when the device requiring authentication is the same as the authenticating device (usually a mobile phone). In this case using a QR Code Dispatcher is not possible: the device displaying the QR code (device requiring authentication) is the same as the device that must scan the QR code (using the authentication application).

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 KeyMandatoryTypeDefault valueDescription
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.
base-urlyesStringhttps://linkThe 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 a Custom Scheme

    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 the custom scheme must be unique for the application.

  2. Use an HTTPS URL

    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 Verify Android App Links and 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.

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.

AttributeTypeDescriptionDefault ValueOptional
dataObjectThe 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.