Skip to main content
Version: 7.2405.x.x LTS

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:

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

AttributeTypeDescriptionOptional
typeStringType of credential. It is an extension point, currently only support public-key.false
idStringA probabilistically-unique byte sequence identifying a public key credential source and its authentication assertions.false
responseObjectThis 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.clientDataJSONStringJSON-compatible serialization of JS client data passed to the authenticator by the JS client to generate this assertion.false
response.authenticatorDataStringThe authenticator data returned by the authenticator.false
response.signatureStringThe raw signature returned from the authenticator.false
response.userHandleStringContains 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
userAgentStringUser 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:

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

AttributeTypeDescription
statusStringDescribing the status of the response. Can be set to either "ok" or "failed".
errorMessageStringError message in case the status is failed.
fido2SessionIdStringIdentifier 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 CodeDescription
200OK The server processed the request successfully. A ServerResponse JSON object is returned.
405Method Not Allowed The method of the received request was not POST.
406Not Acceptable The Accept header is not properly set to application/json.
415Unsupported Media Type The Content-Typ header is not properly set to application/json.