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

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:

NameDescription
AcceptAccept header, must be application/fido+uaf.
Content-TypeContent 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:

AttributeTypeDescriptionOptional
contextStringThe 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
uafResponseStringThe 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:

AttributeTypeDescriptionOptional
headerObjectSee Operation Header Dictionary. The operation header of the uafResponse.false
fcParamsStringBase64url-encoded final challenge parameters using UTF-8 encoding, see Final Challenge Dictionary.false
assertionsArrayArray 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[].assertionSchemeStringName of the assertion scheme used to encode the assertion. The only currently supported mandatory assertion scheme is: UAFV1TLV.false
assertions[].assertionStringBase64url-encoded TAG_UAFV1_AUTH_ASSERTION object, contains the assertion signed by the attestation's private key.false
assertions[].extsArrayExtensions 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.

AttributeTypeDescriptionOptional
asmStatusCodenumberThe ASM Status Codetrue
clientErrorCodenumberThe Client Error Codetrue

Response Headers

The following response headers will be set:

NameDescription
Content-TypeContent 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:

AttributeTypeDescription
statusCodeNumberUAF status code for the authentication operation, see UAF Status Codes.
descriptionStringDetailed message containing a user-friendly description of the authentication result. This is the stringified representation of the JSON described in the [Authentication Server Response].
additionalTokensArrayNew authentication or authorization token(s) for the client that are not natively handled by HTTP transport.
locationStringIf present, indicates to the client web application that it should navigate to the URI contained in this field.
postDataStringIf present, and in combination with location, indicates the client should POST the contents to the specified location.
newUAFRequestStringServer 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.
AttributeTypeDescriptionOptional
messageStringA 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 CodeDescription
200OK The server processed the request successfully. Check the response body for UAF specific status information.
405Method Not Allowed The method of the received request was not POST.
406Not Acceptable The Accept header is not properly set to application/fido+uaf.
415Unsupported Media Type The Content-Type header is not properly set to application/fido+uaf;charset=UTF-8.