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

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:

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

AttributeTypeDescriptionOptional
usernameStringShould 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
userVerificationStringThis 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:

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

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.
challengeStringA random base64url encoded challenge, that is minimum 16 bytes long, and maximum 64 bytes long.
timeoutNumberTimeout of the ceremony expressed in milliseconds.
rpIdStringThis 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.
allowCredentialsArrayDescribes 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[].typeStringType of credential. It is an extension point, currently only support public-key.
allowCredentials[].idStringContains base64url encoded credential ID of the public key credential that the caller is referring to.
allowCredentials[].transportsArrayChannels listed by the server for authenticators to attest them on (bluetooth, nfc, usb, etc.).
userVerificationStringThis 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 CodeDescription
200OK The server processed the request successfully. A ServerPublicKeyCredentialGetOptionsResponse 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-Type header is not properly set to application/json.