Dispatcher Overview

info

Dispatchers are only used with Nevis Mobile Authentication, not FIDO2.

A dispatcher sends a token generated by nevisFIDO to a mobile device or client application so that it can redeem the token and proceed with a FIDO UAF operation. This enables out-of-band scenarios where the device triggering the operation (for example, a browser on a desktop computer) is different from the device that authenticates (the mobile device).

For concept information regarding out-of-band scenarios, see the Concept and Integration Guide.

Dispatchers are configured as part of the FIDO UAF configuration of the nevisFIDO instance and are implemented using Plugins.

Available Dispatchers

When calling the Dispatch Token Service, you choose a dispatcher by setting the dispatcher field in the request to the API value of the dispatcher. The table below shows all four built-in dispatchers:

Dispatcher	Config type (nevisfido.yml)	API dispatcher value	Dispatch target	Supports encryption	Typical use case
FCM Dispatcher	firebase-cloud-messaging	firebase-cloud-messaging	Required	Yes (mandatory)	Push notification to mobile device
Link QR Code Dispatcher	link-png-qr-code	link-png-qr-code	Optional (recommended)	Yes (recommended)	Scannable QR code containing a deep link
QR Code Dispatcher (not recommended)	png-qr-code	png-qr-code	Optional (recommended)	Yes (recommended)	Scannable QR code (raw payload)
Link Dispatcher	link	link	Optional (recommended)	Yes (recommended)	Deep link returned in the HTTP response

Link QR Code vs QR Code Dispatcher

Use the Link QR Code Dispatcher instead of the QR Code Dispatcher for better user experience: the QR code generated by the Link QR Code Dispatcher contains a URL, so scanning it with the built-in camera app on the device opens the Access App directly. The QR Code Dispatcher generates a raw-payload QR code that can only be processed inside the Access App itself.

Choosing a Dispatcher

• FCM Dispatcher: Use when the mobile device has a registered dispatch target with an FCM push token, and you want to trigger an operation (authentication, deregistration) via push notification.
• Link QR Code Dispatcher: Use for cross-device scenarios where the user must scan a QR code with their mobile device camera to launch the Access App. The QR code contains a link, so no special app is needed to scan it.
• QR Code Dispatcher: Older alternative to the Link QR Code Dispatcher. The QR code contains a raw payload that can only be processed inside the Access App.
• Link Dispatcher: Use when the HTTP client triggering the dispatch is already running on the mobile device and can open a deep link directly, without needing a QR code.

Dispatch Targets

A dispatch target is a registered record in nevisFIDO that represents a specific mobile device (or other recipient).

For the FCM Dispatcher, a dispatch target must contain both:

• The FCM push token (the target field) used to address the mobile device via push notification.
• An encryption key used to encrypt the dispatched payload so only that device can read it.

For QR code and link dispatchers, only the encryption key is relevant — the target field is not used and can be omitted.

Dispatch targets are managed via the Dispatch Target Service.

The FCM Dispatcher requires a dispatchTargetId containing both a push token and an encryption key. Encryption is mandatory. For the Link QR Code, QR Code, and Link dispatchers a dispatch target is technically optional, but you should always supply one with an encryption key to prevent QRLJacking (a social engineering attack where a malicious QR code is substituted for a legitimate one) and man-in-the-middle attacks (see Encryption below). A dispatch target can be omitted in two cases: usernameless authentication, where the identity of the user is not yet known at dispatch time, and the initial out-of-band registration, where the dispatch target does not yet exist on the device.

Encryption

When a dispatch target that has an encryptionKey is referenced in the request, nevisFIDO encrypts the out-of-band payload inside the dispatched message. Encryption guarantees that only the device that owns the encryption key can consume the token. For QR code and link dispatchers, encryption also prevents QRLJacking and other man-in-the-middle attacks.

Recommendation

Always supply a dispatch target with an encryption key for QR code and link dispatchers to prevent QRLJacking attacks. A dispatch target can be omitted in two cases: usernameless authentication, where the identity of the user is not yet known at dispatch time, and the initial out-of-band registration, where the dispatch target does not yet exist on the device. For FCM, encryption is mandatory.

The following encryption algorithms are supported:

• RSA: RSA-OAEP-256 with encryption method A256CBC_HS512
• EC: ECDH-ES+A256KW with encryption method A256CBC_HS512

These algorithms are the same for all dispatchers. Full algorithm specifications are in the FCM Dispatcher: Encryption section.

Dispatch Target Format

Dispatch targets are registered via the Dispatch Target Service. The format is the same for all dispatchers:

• The dispatch target must contain an encryptionKey.
• For the FCM Dispatcher, the dispatch target must also include the target field set to the FCM registration token of the mobile device. For all other dispatchers (Link QR Code, QR Code, Link), the target field is not required.

For the full format specification and an example, see FCM Dispatcher: Dispatch Target Format.

Dispatch Token Request: dispatchInformation per Dispatcher

When calling the Dispatch Token Service, the optional dispatchInformation field of the request body carries dispatcher-specific parameters. The content varies depending on which dispatcher is used:

Dispatcher	dispatchInformation attributes	Details
FCM	notification (object, recommended), data (object, optional), alternativeDispatchers (array, optional)	FCM Dispatcher: Dispatch Token Request Format
Link QR Code	data (object, optional), width (number, optional), height (number, optional), foregroundColor (string, optional), backgroundColor (string, optional)	Link QR Code Dispatcher: Dispatch Token Request Format
QR Code	data (object, optional), width (number, optional), height (number, optional), foregroundColor (string, optional), backgroundColor (string, optional)	QR Code Dispatcher: Dispatch Token Request Format
Link	data (object, optional)	Link Dispatcher: Dispatch Token Request Format

Dispatch Token Response: dispatcherInformation.response per Dispatcher

When the dispatch is successful, the dispatcherInformation.response field in the Dispatch Token Service response contains a dispatcher-specific value:

Dispatcher	dispatcherInformation.response	Details
FCM	By default (backwards-compatible-response: true), returns the FCM message ID as a plain string. When backwards-compatible-response: false, returns a JSON object containing fcmDispatchResult, fcmMessageId, and alternativeDispatchers (if requested).	FCM Dispatcher: Dispatch Token Response Format
Link QR Code	JSON object: link (URL string), linkQrCode (base64-encoded PNG string)	Link QR Code Dispatcher: Dispatch Token Response Format
QR Code	Plain string: base64-encoded PNG QR code	QR Code Dispatcher: Dispatch Token Response Format
Link	Plain string: the generated URL	Link Dispatcher: Dispatch Token Response Format

Alternative Dispatchers (FCM + Fallback)

When using the FCM Dispatcher, you can request that nevisFIDO also invoke one or more additional dispatchers (such as the Link QR Code Dispatcher) alongside the push notification. The results of all invoked dispatchers are returned together in the HTTP response. This is useful when the push notification may not reach the device in time and you want to offer a fallback channel (for example, also display a QR code on-screen).

To use this feature, configure allowed-alternative-dispatchers on the FCM dispatcher in nevisfido.yml, and also configure the alternative dispatcher itself. See FCM Dispatcher: Dispatch Token Request Format and FCM Dispatcher: Configuration for details.