Authentication Options Service

By calling the Authentication Options Service and requesting a ServerPublicKeyCredentialGetOptionsResponse object from the FIDO2 server. This chapter describes the request and response messages between the FIDO2 Relying Party client and Server when calling the Authentication Options Service.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/fido2/attestation/options

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 Options Service requires from the FIDO2 client side of the Relying Party a JSON payload with a ServerPublicKeyCredentialOptionsRequest object. This object has the following structure:

Attribute	Type	Description	Optional
username	String	Should match conceptually with the username-mapper in the credential-repository. An empty string can be provided as username in the usernameless authentication use-case.	false
userVerification	String	This member describes the Relying Party's requirements regarding user verification for the get() operation.	false

info

For a detailed explanation of the userVerification attribute, visit the official documentation.

Response Headers

The following response headers will be set:

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

Response Body

The Authentication Options Service returns a JSON body with a ServerPublicKeyCredentialGetOptionsResponse object. This 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.
challenge	String	A random base64url encoded challenge, that is minimum 16 bytes long, and maximum 64 bytes long.
timeout	Number	Timeout of the ceremony expressed in milliseconds.
rpId	String	This optional member specifies the Relying Party identifier claimed by the caller. If omitted, its value will be the CredentialsContainer object's relevant settings object's origin's effective domain.
allowCredentials	Array	Describes a selection of credentials that are allowed for the client to use. May be used by the server to enforce an authentication on the client side that belongs to a specific user. An empty array may be provided by the server to request the client to choose a locally stored discoverable credential in the usernameless authentication use-case.
allowCredentials[].type	String	Type of credential. It is an extension point, currently only support public-key.
allowCredentials[].id	String	Contains base64url encoded credential ID of the public key credential that the caller is referring to.
allowCredentials[].transports	Array	Channels listed by the server for authenticators to attest them on (bluetooth, nfc, usb, etc.).
userVerification	String	This member describes the Relying Party's requirements regarding user verification for the get() operation. Allowed values are "required", "preferred" and "discouraged".

info

The nevisFIDO component currently does not support the FIDO2 specification for extensions.

Example Request

POST /nevisfido/fido2/attestation/options HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 70

{
  "username" : "[email protected]",
  "userVerification" : "preferred"
}

For usernameless authentication:

POST /nevisfido/fido2/attestation/options HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 70

{
  "username" : "",
  "userVerification" : "preferred"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/fido2/attestation/options' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "username" : "[email protected]",
  "userVerification" : "preferred"
}'

cURL for usernameless authentication:

$ curl 'https://fido.siven.ch/nevisfido/fido2/attestation/options' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "username" : "",
  "userVerification" : "preferred"
}'

Example Response

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

{
  "status" : "ok",
  "errorMessage" : "",
  "fido2SessionId" : "673c1466-2fb8-43fe-8898-a94a06d1793c",
  "challenge" : "bs1rWtPCQrmEDrBGAfjcKg",
  "timeout" : 300000,
  "rpId" : "siven.ch",
  "allowCredentials" : [ {
    "type" : "public-key",
    "id" : "Y3JlZGVudGlhbElk",
    "transports" : [ "usb", "internal", "ble", "nfc" ]
  } ],
  "userVerification" : "preferred"
}

For usernameless authentication:

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

{
  "status" : "ok",
  "errorMessage" : "",
  "fido2SessionId" : "673c1466-2fb8-43fe-8898-a94a06d1793c",
  "challenge" : "bs1rWtPCQrmEDrBGAfjcKg",
  "timeout" : 300000,
  "rpId" : "siven.ch",
  "allowCredentials" : [],
  "userVerification" : "preferred"
}

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 Options Service:

HTTP Code	Description
200	OK The server processed the request successfully. A ServerPublicKeyCredentialGetOptionsResponse 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-Type header is not properly set to application/json.