Authentication Request Service

By calling the Authentication Request Service and requesting an AuthenticationRequest object from the FIDO server, the user/FIDO client initiates the FIDO authentication process. The Authentication Request Service is also used for transaction confirmation (see the context part of the request message body. For more information, see Context and Transaction Confirmation. This chapter describes the request and response messages between the FIDO client and Server when calling the Authentication Request Service.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/uaf/1.1/request/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 Request Service requires from the FIDO client a JSON payload with a has the following structure:

Attribute	Type	Description	Optional
op	String	The request operation, must be set to Auth.	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 Authentication Context.	false

info

The previousRequest parameter is ignored and not handled by nevisFIDO.

Context

As part of the authentication operation, the client can provide the username of the user to be authenticated to the Authentication Request Service. One possibility is to provide the username inside the context part of the GetUAFRequest object.

When the username is provided, nevisFIDO will assume that the authentication is a step-up authentication. This has certain implications in the way nevisFIDO handles the request:

1. If the username is not known (i.e. no credential was registered for the provided username), nevisFIDO will return an error response.
2. If the username is known (i.e. at least one credential was registered for the provided username), nevisFIDO will return a policy that only contains the AAID and KeyIDs registered for the user that match the policy configured. See the "Configuration" section of the Reference Guide describing the policy for more information.

The client can also include transaction information in the context part of the GetUAFRequest object, in the form of a TransactionContent object. See Transaction Confirmation for more information.

The Context dictionary below lists all attributes that can be included in the context part of the GetUAFRequest object.

Attribute	Type	Description	Optional
username	String	Identity information regarding the user on whose behalf the FIDO client is operating. In the case of the idm credential repository, the accepted type of username (loginId, email, etc.) depends on how the username mapper of the credential repository is configured.	true
transaction	TransactionContent[] (see Transaction Content dictionary)	The transaction information sent from the client to the FIDO Server. See Transaction Confirmation for more information.	true
policy	String	The name of the policy to be use to authenticate. If not specified, the default policy will be used.	true

Transaction Confirmation

In the context of transaction confirmation, nevisFIDO expects the client to provide the transaction content in the context part of the GetUAFRequest, in the form of a TransactionContent object. The Transaction Content dictionary below describes the attributes that define the TransactionContent object.

info

The Transaction Content dictionary is part of the Authentication Request Service, but not of the official FIDO UAF 1.1 Specification.

Attribute	Type	Description	Optional
contentType	String	Contains the MIME content type supported by the authenticator according to its metadata statement. Note that nevisFIDO only supports the values "text/plain" or "image/png".	false
content	String	Contains the (base64url-encoded) transaction content according to the setting of the contentType attribute.	false

nevisFIDO uses the transaction content information in the TransactionContent objects as input for the generation of transaction objects, which are included in the AuthenticationRequests sent from the FIDO server to the FIDO UAF client. However, before nevisFIDO sends back the transaction objects, it validates the information coming from the FIDO client, with the following outcome:

If no username was provided in the initial GetUafRequest:

• nevisFIDO only supports plain/text content type and will return the content as provided in the Transaction Content .

If a username was provided in the initial GetUafRequest (i.e. step-up authentication):

• If a TransactionContent object contains a content type that is not supported by any of the registered credentials for the user, no transaction will be included in the AuthenticationRequest. nevisFIDO uses the metadata statements associated with the registered credentials to determine if the content type is supported.
• If a TransactionContent object contains the content type image/png, nevisFIDO will look for the DisplayPngCharacteristicsDescriptor provided during registration (if any). If the descriptor was not provided during registration, nevisFIDO will look for descriptors in the metadata, and add the retrieved descriptors to the returned transaction in the AuthenticationRequest. If no display PNG descriptor is found, the transaction will be discarded. Note that if several display PNG descriptors are found, nevisFIDO will generate several transaction objects.

Below, see the Transaction dictionary as described in the {uaf-transaction-confirmation-dictionary-spec}. The Transaction dictionary includes the attributes that define a transaction object. For more information about the AuthenticationRequest object, see Response Body further on.

Attribute	Type	Description	Optional
contentType	String	Contains the MIME content type supported by the authenticator according to its metadata statement. Note that this version of nevisFIDO only supports the values "text/plain" or "image/png".	false
content	String	Contains the (base64url-encoded) transaction content according to the setting of the contentType attribute.	false
tcDisplayPNGCharacteristics	DisplayPNGCharacteristicsDescriptor	Defines the PNG characteristics of the transaction content and sets the attributes of the DisplayPNGCharacteristicsDescriptor (such as width, height or colorType). Click here for a description of the DisplayPNGCharacteristicsDescriptor dictionary.	false (if contentType is "image/png")

Example

The following GetUAFRequest contains a PNG image transaction:

{
  "context" : "{\"username\":\"jeff\",\"transaction\":[{\"contentType\":\"image/png\",\"content\":\"dGhpcyBpcyBzdXBwb3NlZCB0byBiZSBhIHBuZyBpbWFnZQ\"}]}",
  "op" : "Auth"
}

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 Request Service returns a JSON body with a ReturnUAFRequest object as defined in the FIDO UAF HTTP Transport Specification . The ReturnUAFRequest object has the following structure:

Attribute	Type	Description
statusCode	Number	UAF status code for the operation.
uafRequest	String	The new UAF request message if the server decides to issue one.
op	String	Hint to the client regarding the operation type of the message, must be set to Auth.
lifetimeMillis	Number	Hint informing the client application of the lifetime of the message in milliseconds. Absent if the operation was not successful.

The uafRequest part of the ReturnUAFRequest object contains the AuthenticationRequest object. The AuthenticationRequest dictionary includes the attributes that define a AuthenticationRequest object. The following table describes the AuthenticationRequest dictionary:

Attribute	Type	Description	Optional
header	OperationHeader	The header defines the operation header of the UAF messages coming from the Authentication Request Service. Within the header, the operation header attributes are specified. For a description of these attributes, see operation-header-dictionary. Note that the attribute header.op must be set to "Auth".	false
challenge	ServerChallenge	Server-provided challenge value.	false
transaction	Transaction[]	Transaction data to be explicitly confirmed by the user. This data is contained in transaction objects. For more information about the structure of transaction objects, see the [Transaction dictionary].	true
policy	Policy	Describes which types of authenticators are acceptable for this authentication operation.	false

Example Request

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

{
  "context" : "{\"username\":\"jeff\",\"transaction\":[{\"contentType\":\"text/plain\",\"content\":\"Q29uZmlybSB5b3VyIHB1cmNoYXNlIGZvciBhIHZhbHVlIG9mIENIRjIwMC4\"}]}",
  "op" : "Auth"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/uaf/1.1/request/authentication' -i -X POST \
    -H 'Accept: application/fido+uaf' \
    -H 'Content-Type: application/fido+uaf;charset=UTF-8' \
    -d '{
  "context" : "{\"username\":\"jeff\",\"transaction\":[{\"contentType\":\"text/plain\",\"content\":\"Q29uZmlybSB5b3VyIHB1cmNoYXNlIGZvciBhIHZhbHVlIG9mIENIRjIwMC4\"}]}",
  "op" : "Auth"
}'

Example Response

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

{
  "lifetimeMillis" : 120000,
  "uafRequest" : "[{\"header\":{\"serverData\":\"ervVRaEsmebKoT53bZhWBsOOcq_HhYunZj-3mJExXVBwa1vNhJSvzaVQB7AxvFJk7YcoXw5l6t2Dr-kv7gpvug\",\"upv\":{\"major\":1,\"minor\":1},\"op\":\"Auth\",\"appID\":\"https://www.siven.ch/appID\",\"exts\":[{\"id\":\"ch.nevis.auth.fido.uaf.sessionid\",\"data\":\"0eb8b439-1092-428b-a595-21ea96fe30a0\",\"fail_if_unknown\":false}]},\"challenge\":\"2B7oYIQIh49QDR2P0WCBydh_l_bACgDvfU-jmnXdPn6mWIrseNJOTDEvfy5k5MtsrVu1hrX7o35Rt0y-TMHsWA\",\"policy\":{\"accepted\":[[{\"userVerification\":1023,\"authenticationAlgorithms\":[1,2,3,4,5,6,7,8,9],\"assertionSchemes\":[\"UAFV1TLV\"]}]]},\"transaction\":[{\"contentType\":\"text/plain\",\"content\":\"Q29uZmlybSB5b3VyIHB1cmNoYXNlIGZvciBhIHZhbHVlIG9mIENIRjIwMC4\"}]}]",
  "statusCode" : 1200,
  "op" : "Auth"
}

info

nevisFIDO includes a proprietary extension in the header part of the AuthenticationRequest object. This extension provides the session ID that can be used to retrieve the authentication status. The following JSON snippet represents the session ID extension. Refer to Extensions and Proprietary Extensions for details.

{
  "id" : "ch.nevis.auth.fido.uaf.sessionid",
  "data" : "d61e461e-c597-4ed3-9d71-12d1c0e3556c",
  "fail_if_unknown" : false
}

HTTP Status Codes

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

HTTP Code	Description
200	OK The server processed the request successfully. A ReturnUAFRequest JSON object containing an AuthenticationRequest is returned.
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.