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

Status Service

This chapter describes the Status Service. The Status Service is not a standard FIDO2 / WebAuthn / Conformance API service but a proprietary nevisFIDO functionality. The service is a public HTTP API that provides information on the the status of a FIDO2 ceremony for a given user. It is for example used by the nevisAuth component to check whether a given user has been registered/authenticated or not.

info

FIDO2 and FIDO UAF sessions are completely independent and share no relation.

Base URL

All URLs referenced in this chapter have the following base:

https://fido.siven.ch/nevisfido/fido2/status

HTTP Methods

POST is 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 Status Service requires a request message containing a JSON payload with the following structure:

AttributeTypeDescriptionOptional
fido2SessionIdStringIdentifier of the FIDO2 session in nevisFIDO. Can be used to query the status from the status service.false

Response Headers

The following response headers will be set:

NameDescription
Content-TypeContent type header, fixed to application/json.

Response Body

The Status Service returns a response message that shows the ceremony status for the provided session ID.

The table further below describes the structure of the response message’s (JSON) body.

  • The status attribute in the response message holds the status information. The attribute can have the following values:

    initialized nevisFIDO has generated the challenge and returned ServerPublicKeyCredentialCreationOptionsResponse or ServerPublicKeyCredentialGetOptionsResponse respective to the ceremony.

    failed The registration or authentication ceremony failed.

    succeeded The user completed the ceremony successfully in nevisFIDO.

    unknown The provided session ID is unknown. This can happen if the session ID does not correspond to any session started with nevisFIDO or if nevisFIDO purged the information regarding the session.

The Status Service returns a JSON response body with the following structure:

AttributeTypeDescription
statusStringDescribing the status of the authentication / registration process stored in the nevisFIDO session. Can be set to "initialized", "succeeded", "failed" or "unknown".
fido2SessionIdStringIdentifier of the FIDO2 session in nevisFIDO. Can be used to query the status from the status service.
timestampStringTimestamp when the session was updated the last time.
usernameStringUsername stored in the session. It is not provided in the usernameless authentication use-case.
userIdStringUser Id stored in the session. In usernameless authentication this field is only populated once the ceremony has been successfully completed.

Example Request (Successful Operation)

POST /nevisfido/fido2/status HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 63

{
"fido2SessionId" : "7fea6065-17fd-47d4-a5b0-85f513687c8d"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/fido2/status' -i -X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"fido2SessionId" : "7fea6065-17fd-47d4-a5b0-85f513687c8d"
}'

Example Response (Successful Operation)

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

{
"status" : "succeeded",
"fido2SessionId" : "7fea6065-17fd-47d4-a5b0-85f513687c8d",
"timestamp" : "2022-07-25T11:31:18.987Z",
"username" : "Jeff ",
"userId" : "[email protected]"
}

For the usernameless authentication use-case:

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

{
"status" : "succeeded",
"fido2SessionId" : "7fea6065-17fd-47d4-a5b0-85f513687c8d",
"timestamp" : "2022-07-25T11:31:18.987Z",
"userId" : "[email protected]"
}

Example Request (Failed Operation)

POST /nevisfido/fido2/status HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 63

{
"fido2SessionId" : "9fea6065-17fd-47d4-a5b0-85f513687c8f"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/fido2/status' -i -X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"fido2SessionId" : "9fea6065-17fd-47d4-a5b0-85f513687c8f"
}'

Example Response (Failed Operation)

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

{
"status" : "failed",
"fido2SessionId" : "9fea6065-17fd-47d4-a5b0-85f513687c8f",
"timestamp" : "2022-07-25T11:31:18.235Z",
"username" : "Jeff ",
"userId" : "[email protected]"
}

HTTP Status Codes

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

HTTP CodeDescription
200OK The server processed the request successfully. Check the response body for the status information.
400Bad Request The provided JSON payload does not match the defined structure in the Request Body section.
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;charset=UTF-8.