Authentication Service

This chapter describes the request and response messages between the FIDO2 Relying Party client and Server when calling the Authentication Service.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/fido2/assertion/result

HTTP Methods

POST and OPTIONS are 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 Authentication Service requires from the FIDO2 Relying Party client a JSON payload with a PublicKeyCredential object as defined in the WebAuthn specification. Also mentioned as ServerPublicKeyCredential in the Conformance test API. The payload object has the following structure:

Attribute	Type	Description	Optional
type	String	Type of credential. It is an extension point, currently only support public-key.	false
id	String	A probabilistically-unique byte sequence identifying a public key credential source and its authentication assertions.	false
response	Object	This response contains a cryptographic signature proving possession of the credential private key, and optionally evidence of user consent to a specific transaction. Also referred as ServerAuthenticatorAssertionResponse in the Conformance API.	false
response.clientDataJSON	String	JSON-compatible serialization of JS client data passed to the authenticator by the JS client to generate this assertion.	false
response.authenticatorData	String	The authenticator data returned by the authenticator.	false
response.signature	String	The raw signature returned from the authenticator.	false
response.userHandle	String	Contains the user handle returned from the authenticator, or null if the authenticator did not return a user handle. In the usernameless authentication use-case this field must be provided, otherwise the ceremony will be aborted by the server.	false
userAgent	String	User agent used to initiate the current request. (Proprietary)	true

info

Note that nevisFIDO includes proprietary extensions on the top of what is defined by the Conformance Test API:

• userAgent

Response Headers

The following response headers will be set:

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

Response Body

The Authentication Service returns a JSON body with a ServerResponse object which is defined by the Conformance testing API and has been extended with a Nevis-proprietary session ID. The ServerResponse object has the following structure:

Attribute	Type	Description
status	String	Describing the status of the response. Can be set to either "ok" or "failed".
errorMessage	String	Error message in case the status is failed.
fido2SessionId	String	Identifier of the FIDO2 session in nevisFIDO. Can be used to query the status from the status service.

Example Request

POST /nevisfido/fido2/assertion/result HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 470

{
  "type" : "public-key",
  "id" : "Y3JlZElk",
  "response" : {
    "clientDataJSON" : "Y2xpZW50RGF0YUpTT05jbGllbnREYXRhSlNPTmNsaWVudERhdGFKU09OY2xpZW50RGF0YUpTT04",
    "authenticatorData" : "YXV0aGVudGljYXRvckRhdGFhdXRoZW50aWNhdG9yRGF0YWF1dGhlbnRpY2F0b3JEYXRh",
    "signature" : "c2lnbmF0dXJlc2lnbmF0dXJlc2lnbmF0dXJlc2lnbmF0dXJlc2lnbmF0dXJl",
    "userHandle" : "SmVmZg"
  },
  "userAgent" : "Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Firefox/102.0"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/fido2/assertion/result' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "type" : "public-key",
  "id" : "Y3JlZElk",
  "response" : {
    "clientDataJSON" : "Y2xpZW50RGF0YUpTT05jbGllbnREYXRhSlNPTmNsaWVudERhdGFKU09OY2xpZW50RGF0YUpTT04",
    "authenticatorData" : "YXV0aGVudGljYXRvckRhdGFhdXRoZW50aWNhdG9yRGF0YWF1dGhlbnRpY2F0b3JEYXRh",
    "signature" : "c2lnbmF0dXJlc2lnbmF0dXJlc2lnbmF0dXJlc2lnbmF0dXJlc2lnbmF0dXJl",
    "userHandle" : "SmVmZg"
  },
  "userAgent" : "Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Firefox/102.0"
}'

Example Response

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

{
  "status" : "ok",
  "errorMessage" : "",
  "fido2SessionId" : "7fea6065-17fd-47d4-a5b0-85f513687c8d"
}

info

Note that nevisFIDO includes proprietary extensions on the top of what is defined by the Conformance Test API:

• fido2SessionId

HTTP Status Codes

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

HTTP Code	Description
200	OK The server processed the request successfully. A ServerResponse JSON object 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/json.
415	Unsupported Media Type The Content-Typ header is not properly set to application/json.