Authentication Response Service

The FIDO client calls the Authentication Response Service when it has processed the AuthenticationRequest object coming from the FIDO server. The client invokes the Authentication Response Service by providing an AuthenticationResponse object that must be processed by nevisFIDO. This chapter describes the request and response messages between the FIDO client and Server when calling the Authentication Response Service.

info

The client can send to nevisFIDO the ASM Status Code received by the will contain no assertions, but the rest of its contents must be specification compliant. This is not part of the standard specification and can be used notably in conjunction with the Status Service.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/uaf/1.1/authentication

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/fido+uaf.
Content-Type	Content type header, must be application/fido+uaf;charset=UTF-8.

Request Body

The Authentication Response Service requires a JSON payload with a SendUAFResponse object as defined in the FIDO UAF HTTP Transport Specification . The SendUAFResponse object has the following structure:

Attribute	Type	Description	Optional
context	String	The contextual information must be a stringified JSON object that conforms to the Authentication Response Context dictionary. It contains the status code returned by the ASM (Authenticator Specific Module) in the authenticating device.	true
uafResponse	String	The stringified JSON array with a single element. The element is the authentication response sent by the UAF client.	false

The uafResponse part of the SendUAFResponse object consists of an array with a single The AuthenticationResponse dictionary includes the attributes that define an AuthenticationResponse object. The following table describes the AuthenticationResponse dictionary:

Attribute	Type	Description	Optional
header	Object	See Operation Header Dictionary. The operation header of the uafResponse.	false
fcParams	String	Base64url-encoded final challenge parameters using UTF-8 encoding, see Final Challenge Dictionary.	false
assertions	Array	Array of required authenticator responses related to the authentication.	true. The assertions can be empty if an error occurred and the client provides the ASM status code in the [Context Authentication Response].
assertions[].assertionScheme	String	Name of the assertion scheme used to encode the assertion. The only currently supported mandatory assertion scheme is: UAFV1TLV.	false
assertions[].assertion	String	Base64url-encoded TAG_UAFV1_AUTH_ASSERTION object, contains the assertion signed by the attestation's private key.	false
assertions[].exts	Array	Extensions prepared by the authenticator.	true

info

If an AuthenticationResponse containing an empty assertions array is sent back to the server indicating a client error, the server will respond with UAF status code 1498 (Unacceptable Content). This is intended behaviour because the response is not "valid" according to the specification.

Context

The client can provide the ASM Status Code and the Client Error Code in the context. These codes are exposed by the Status Service and can be used to better identify what was the problem that occurred in the client side while authenticating with the FIDO authenticator.

Attribute	Type	Description	Optional
asmStatusCode	number	The ASM Status Code	true
clientErrorCode	number	The Client Error Code	true

Response Headers

The following response headers will be set:

Name	Description
Content-Type	Content type header, fixed to application/fido+uaf;charset=UTF-8.

Response Body

The Authentication Response Service will return a ServerResponse object as described in FIDO UAF HTTP Transport Specification . The ServerResponse object has the following structure:

Attribute	Type	Description
statusCode	Number	UAF status code for the authentication operation, see UAF Status Codes.
description	String	Detailed message containing a user-friendly description of the authentication result. This is the stringified representation of the JSON described in the [Authentication Server Response].
additionalTokens	Array	New authentication or authorization token(s) for the client that are not natively handled by HTTP transport.
location	String	If present, indicates to the client web application that it should navigate to the URI contained in this field.
postData	String	If present, and in combination with location, indicates the client should POST the contents to the specified location.
newUAFRequest	String	Server may return a new UAF protocol message with this field. This might be used to supply a fresh request to retry an operation in response to a transient failure, to request additional confirmation for a transaction, or to send a deauthentication message in response to a permanent failure.

Attribute	Type	Description	Optional
message	String	A user-friendly description of the result of the authentication operation.	true

info

The following attributes are ignored and not handled:

• additionalTokens
• location
• postData
• newUAFRequest

Example Request

POST /nevisfido/uaf/1.1/authentication HTTP/1.1
Accept: application/fido+uaf
Content-Type: application/fido+uaf;charset=UTF-8
Host: fido.siven.ch
Content-Length: 572

{
  "uafResponse" : "[{\"header\":{\"serverData\":\"serverdata\",\"upv\":{\"major\":1,\"minor\":1},\"op\":\"Auth\",\"appID\":\"appID\"},\"fcParams\":\"eyJjaGFsbGVuZ2UiOiJjaGFsbGVuZ2UiLCJjaGFubmVsQmluZGluZyI6eyJjaWRfcHVia2V5IjoicHVia2V5In0sImFwcElEIjoiYXBwSUQiLCJmYWNldElEIjoiZmFjZXRJRCJ9\",\"assertions\":[{\"assertionScheme\":\"UAFV1TLV\",\"assertion\":\"Aj5pAAQ-WAALLgkAQUJDRCNBQkNEDi4FAAEAAQkADy4SAGF1dGhlbnRpY2F0b3JOb25jZQouBABoYXNoEC4PAHRyYW5zYWN0aW9uSGFzaAkuBQBrZXlJZA0uBAABAAAABi4JAHNpZ25hdHVyZQ\"}]}]",
  "context" : "{\"asmStatusCode\":0,\"clientErrorCode\":0}"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/uaf/1.1/authentication' -i -X POST \
    -H 'Accept: application/fido+uaf' \
    -H 'Content-Type: application/fido+uaf;charset=UTF-8' \
    -d '{
  "uafResponse" : "[{\"header\":{\"serverData\":\"serverdata\",\"upv\":{\"major\":1,\"minor\":1},\"op\":\"Auth\",\"appID\":\"appID\"},\"fcParams\":\"eyJjaGFsbGVuZ2UiOiJjaGFsbGVuZ2UiLCJjaGFubmVsQmluZGluZyI6eyJjaWRfcHVia2V5IjoicHVia2V5In0sImFwcElEIjoiYXBwSUQiLCJmYWNldElEIjoiZmFjZXRJRCJ9\",\"assertions\":[{\"assertionScheme\":\"UAFV1TLV\",\"assertion\":\"Aj5pAAQ-WAALLgkAQUJDRCNBQkNEDi4FAAEAAQkADy4SAGF1dGhlbnRpY2F0b3JOb25jZQouBABoYXNoEC4PAHRyYW5zYWN0aW9uSGFzaAkuBQBrZXlJZA0uBAABAAAABi4JAHNpZ25hdHVyZQ\"}]}]",
  "context" : "{\"asmStatusCode\":0,\"clientErrorCode\":0}"
}'

Example Response

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:30:32 GMT
Content-Type: application/fido+uaf;charset=UTF-8
Transfer-Encoding: chunked
Content-Length: 89

{
  "statusCode" : 1200,
  "description" : "{\"message\":\"OK. Operation completed.\"}"
}

HTTP Status Codes

The following HTTP status codes are returned by the Authentication Response Service:

HTTP Code	Description
200	OK The server processed the request successfully. Check the response body for UAF specific status information.
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/fido+uaf.
415	Unsupported Media Type The Content-Type header is not properly set to application/fido+uaf;charset=UTF-8.