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

Dispatch Token Service

This chapter describes the Dispatch Token Service. The Dispatch Token Service is not a standard FIDO service but a proprietary nevisFIDO functionality. It is a public HTTP API with which clients can create and dispatch tokens. These tokens can be redeemed by other trusted parties via the Redeem Token Service.

Depending on the nature of the dispatcher, the client must provide the dispatch target. For instance, in the case of the FCM Dispatcher a dispatch target ID must be provided in the request to be able to send the push message.

The client can specify the dispatcher to be used explicitly in the request or implicitly by providing the dispatch target identifier (a default dispatcher is associated with each dispatch target). So, if you want to use a dispatcher with a dispatch target associated by default with another dispatcher, both the dispatcher and the dispatch target identifier must be provided. Note that some dispatchers (like the FCM Dispatcher) do not require a dispatch target.

If a dispatch target is required by the dispatcher, the dispatch target determines the parameters required for the dispatching to take place. Such targets are managed by the Dispatch Target Service. Make sure to create and query targets before you access this service.

Currently dispatching is always done synchronously. This means that the result of the dispatching is always returned immediately in the HTTP response.

Base URL

https://fido.siven.ch/nevisfido/token/dispatch/<operation>

The <operation> in the base URL can be registration, authentication or deregistration.

Having split endpoints allows you to protect nevisFIDO differently for each operation, by means of nevisProxy and nevisAuth. d nt is necessary to protect the registration and deregistration endpoints. Otherwise, malicious clients could easilyd nnitiate unprotected FIDO operations and plant undesired credentials they can take advantage of. You should also protect the authentication dispatch endpoint, if possible. Allowing any form of unauthorized dispatching may result in malicious parties sending messages directly to target devices and thus to end users.

HTTP Methods

POST is the only supported HTTP method.

Request Headers

The following request headers are mandatory:

NameDescription
AcceptAccept header, must be application/json.
Content-TypeContent type header, must be application/json.

Request Body

The Dispatch Token Service requires from the FIDO client a JSON payload with a GetUAFRequest object as defined in the FIDO UAF HTTP Transport Specification. This GetUAFRequest object is used to initiate the given FIDO operation after the redemption of the token, a ReturnUafRequest will be returned for the redeemer party.

The request body contains the following elements:

AttributeTypeDescriptionOptional
dispatchTargetIdStringThe identifier of the dispatch target. The dispatch target identifier, the dispatcher or both must be provided.true
dispatcherStringThe dispatcher that must be used to do the dispatching. The dispatch target identifier, the dispatcher or both must be provided. Currently firebase-cloud-messaging (for the FCM dispatcher), png-qr-code (for the QR Code dispatcher) and link (for the link dispatcher) are supported.true
dispatchInformationObjectInformation explicitly intended for the specific [Dispatcher] being used. The content of this object depends on the dispatcher implementation. Both JSON and plain text are supported.true
getUafRequestObjectThe GetUafRequest that will be associated with the dispatched token. When the token is redeemed, this request will be used as the base request for which a ReturnUafRequest will be generated.false
AttributeTypeDescriptionOptional
opStringThe operation requested by the GetUafRequest.false
previousRequestStringIf the application is requesting a new UAF request message because the previous one expired, the previous one could be sent to the server.true
contextStringThe contextual information must be a stringified JSON object that conforms to the Authenticatoin Context.false

Response Headers

The following response headers will be set:

NameDescription
Content-TypeContent type header, fixed to application/json.

Response Body

The response body consists of the following elements:

AttributeTypeDescription
dispatchResultStringThe result of the dispatching. Since dispatching is done synchronously, this directly indicates whether a valid dispatcher and dispatch target could be found for the request and whether the token could be transmitted to the dispatcher.
dispatcherInformationObjectInformation about the dispatcher. Only present when the dispatcher was invoked.
dispatcherInformation.nameStringThe [Dispatcher] that was being used for dispatching.
dispatcherInformation.responseVariesFree text that a particular dispatcher returns after it was invoked.
tokenStringThe token generated by nevisFIDO. This is the token that can be used by a client to trigger the UAF operation (registration, authentication or deregistration). Therefore, the token must be sent to the corresponding endpoint ("/nevisfido/token/redeem/registration" for registration, "/nevisfido/token/redeem/authentication" for authentication and "/nevisfido/token/redeem/deregistration" for deregistration), to redeem the token and trigger the FIDO UAF operation with the GetUAFRequest sent in this request. It will be returned only if it could be successfully dispatched.
sessionIdStringThe identifier of the session generated by nevisFIDO. This session identifier can be used by a client to retrieve the status of the authentication. The session ID must be sent to the "/nevisfido/status" endpoint to get the operation status. It will be returned only if it could be successfully dispatched.

The response message only includes a dispatcherInformation object when a dispatcher has been invoked.

The dispatchResult attribute of the response message holds information about the result of the dispatching. The attribute can have the following values:

  • dispatched

    A token has been generated and successfully dispatched to the target.

  • dispatchError

    An error occurred when dispatching the token.

  • dispatchTargetNotFound

    nevisFIDO has not found a dispatch target that corresponds to the ID in the request. Make sure to query targets before trying to dispatch a token.

  • dispatcherNotFound

    The target refers to a dispatcher that has no associated dispatcher implementation. It is also possible that the dispatcher implementation has not been loaded successfully. This may point to a configuration error.

  • userNotFound

    The user requested to dispatch the token to is not found in the credential repository.

  • internalError

    Indicates that an internal problem occurred, for example during the generation of the token.

Example Request Using FCM Dispatcher

info

Refer to Dispatch Token Request Format for additional details.

Example Response Using FCM Dispatcher

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:30:42 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Content-Length: 240

{
"token" : "98248c42-c9d5-4332-9b28-c3dc497df311",
"sessionId" : "1a819145-d2b5-4930-b31f-08003500ab6a",
"dispatchResult" : "dispatched",
"dispatcherInformation" : {
"name" : "firebase-cloud-messaging",
"response" : 0
}
}

Example Request Using QR Code Dispatcher

POST /nevisfido/token/dispatch/authentication HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 484

{
"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"
}
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/token/dispatch/authentication' -i -X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"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"
}
}'

Example Response Using QR Code Dispatcher

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:30:42 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Content-Length: 269

{
"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>"
}
}

HTTP Status Codes

The following HTTP status codes are returned by the Dispatch Token Service endpoint:

HTTP CodeDescription
200OK The server created and successfully dispatched a token.
400Bad Request The provided payload was not properly formatted.
401Unauthorized The request was not authorized. There is an invalid SecToken or unresolved username.
405Method Not Allowed The method of the received request was not POST.
406Not Acceptable The Accept header is not properly set to application/json.
415Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8.
500Internal Server Error The server could not process the request because of an unexpected error.