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:

Name	Description
Accept	Accept header, must be application/json.
Content-Type	Content type header, must be application/json.

Request Body

The Status Service requires a request message containing a JSON payload with the following structure:

Attribute	Type	Description	Optional
fido2SessionId	String	Identifier 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:

Name	Description
Content-Type	Content 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:

Attribute	Type	Description
status	String	Describing the status of the authentication / registration process stored in the nevisFIDO session. Can be set to "initialized", "succeeded", "failed" or "unknown".
fido2SessionId	String	Identifier of the FIDO2 session in nevisFIDO. Can be used to query the status from the status service.
timestamp	String	Timestamp when the session was updated the last time.
username	String	Username stored in the session. It is not provided in the usernameless authentication use-case.
userId	String	User 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 Code	Description
200	OK The server processed the request successfully. Check the response body for the status information.
400	Bad Request The provided JSON payload does not match the defined structure in the Request Body section.
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;charset=UTF-8.