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:

Name	Description
Accept	Accept header, must be application/json.
Content-Type	Content 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:

Attribute	Type	Description	Optional
dispatchTargetId	String	The identifier of the dispatch target. The dispatch target identifier, the dispatcher or both must be provided.	true
dispatcher	String	The 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
dispatchInformation	Object	Information 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
getUafRequest	Object	The 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

Attribute	Type	Description	Optional
op	String	The operation requested by the GetUafRequest.	false
previousRequest	String	If the application is requesting a new UAF request message because the previous one expired, the previous one could be sent to the server.	true
context	String	The contextual information must be a stringified JSON object that conforms to the Authenticatoin Context.	false

Response Headers

The following response headers will be set:

Name	Description
Content-Type	Content type header, fixed to application/json.

Response Body

The response body consists of the following elements:

Attribute	Type	Description
dispatchResult	String	The 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.
dispatcherInformation	Object	Information about the dispatcher. Only present when the dispatcher was invoked.
dispatcherInformation.name	String	The [Dispatcher] that was being used for dispatching.
dispatcherInformation.response	Varies	Free text that a particular dispatcher returns after it was invoked.
token	String	The 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.
sessionId	String	The 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 Code	Description
200	OK The server created and successfully dispatched a token.
400	Bad Request The provided payload was not properly formatted.
401	Unauthorized The request was not authorized. There is an invalid SecToken or unresolved username.
405	Method Not Allowed The method of the received request was not POST.
406	Not Acceptable The Accept header is not properly set to application/json.
415	Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8.
500	Internal Server Error The server could not process the request because of an unexpected error.