Version: 2.4.x.x Java 8 ELS

Status Service

This chapter describes the Status Service. The Status Service is not a standard FIDO service but a proprietary nevisFIDO functionality. The service is a public HTTP API that you can call to find out the status of an operation (registration or authentication) for a given user in nevisFIDO. It allows nevisAuth to check whether a given user has been registered/authenticated or not.

Base URL

All URLs referenced in this chapter have the following base:

https://fido.siven.ch/nevisfido/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
`sessionId`	`String`	The session ID identifying the authentication session established in nevisFIDO.	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 operation 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:
tokenCreated
nevisFIDO has generated a token through the Dispatch Token Service, but the token has not been redeemed yet. If the initial request included a dispatching of the token, being in this state implies that nevisFIDO successfully transmitted the token to the dispatching service. However, the final recipient may not have received the token yet.
clientRegistering
nevisFIDO has sent a RegistrationRequest to the client, but the FIDO client has not sent a response yet. That is, nevisFIDO is waiting for the user to interact with the FIDO UAF authenticator, and for the client to send a RegistrationResponse. nevisFIDO generated the registration request after either redeeming a token in the Redeem Token Service, or receiving a GetUAFRequest via the FIDO UAF Registration Request Service.
clientAuthenticating
nevisFIDO has sent an AuthenticationRequest to the client, but the FIDO client has not sent a response yet. That is, nevisFIDO is waiting for the user to interact with the FIDO UAF authenticator, and for the client to send a AuthenticationResponse. nevisFIDO generated the authentication request after either redeeming a token in the Redeem Token Service, or receiving a GetUAFRequest via the FIDO UAF Authentication Request Service.
failed
The registration or authentication operation failed.
succeeded
The user completed the operation 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 uafStatusCode attribute in the response message provides the UAF status code returned by nevisFIDO when the operation is completed.

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

Attribute	Type	Description
`status`	`String`	The operation status for the provided session ID.
`timestamp`	`String`	ISO-8601 timestamp in UTC when the status was last updated, for example, "`2018-04-19T14:48:24.429Z`". Absent when the status is unknown.
`uafStatusCode`	`Number`	The UAF status code for the operation, see UAF Status Codes. Absent if the operation is not completed.
`asmStatusCode`	`Number`	The ASM status code sent by the FIDO client when sending a [Registration] or an [Authentication] response. The possible values are defined in [ASM Status Codes]. Absent if the operation is not completed or if the client did not send it.
`clientErrorCode`	`Number`	The client error code sent by the FIDO client when sending a [Registration] or an [Authentication] response. The possible values are defined in [Client Error Codes]. Absent if the operation is not completed or if the client did not send it.
`userId`	`String`	The technical identifier of the user who successfully completed the operation. The nature of this attribute depends on the type of credential repository used and in general is not the same as the username provided by the FIDO clientin the context of the `GetUAFRequest`. This value is only present if the operation is completed successfully.
`tokenInformation`	`Object`	The object describing the token managing status. This object is available when the [Dispatch Token> was used and the token could be successfully created and dispatched.
`tokenInformation.dispatcherInformation.name`	`String`	The [Dispatcher] used to dispatch the token. It is present if the client asked to dispatch the token.
`tokenInformation.dispatcherInformation.response`	`String`	The information provided by the dispatcher after dispatching the token. If there was an unexpected error, this is also reported here.
`tokenInformation.tokenResult`	`String`	The result of the token management. This is only available when the server finished processing the token. It can contain the following values: `tokenRedeemed`: if the token was successfully redeemed; `tokenTimedOut`: if the token was not redeemed and has timed-out (i.e. it cannot be redeemed anymore).
`authenticators`	`Array`	See Authenticators. In the case of a successfully completed registration or authentication, this field contains information regarding the authenticators used to generate the validated assertions. In the case of deregistration, information regarding the deregistered authenticators.
`authenticators[].aaid`	`String`	The AAID of the authenticator.

Example Request (Successful Operation)

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

{
  "sessionId" : "5d396adc-67fa-444c-bf27-77a5516a9425"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/status' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "sessionId" : "5d396adc-67fa-444c-bf27-77a5516a9425"
}'

Example Response (Successful Operation)

Note that the tokenInformation attribute is present, which indicates that the operation was triggered using the Dispatch Token Service.

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:30:48 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Content-Length: 415

{
  "status" : "succeeded",
  "timestamp" : "2022-07-25T11:30:47.439Z",
  "tokenInformation" : {
    "tokenResult" : "tokenRedeemed",
    "dispatcherInformation" : {
      "name" : "firebase-cloud-messaging",
      "response" : "successful dispatch"
    }
  },
  "uafStatusCode" : 1200,
  "asmStatusCode" : 0,
  "clientErrorCode" : 0,
  "userId" : "userId",
  "authenticators" : [ {
    "aaid" : "ABBA#0001"
  } ]
}

Example Request (Failed Operation)

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

{
  "sessionId" : "ac4cfff8-b37e-48da-951d-57890abb779b"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/status' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
  "sessionId" : "ac4cfff8-b37e-48da-951d-57890abb779b"
}'

Example Response (Failed Operation)

Note that the tokenInformation attribute is not present, which indicates that the operation was not triggered using the Dispatch Token Service.

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:30:49 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Content-Length: 145

{
  "status" : "failed",
  "timestamp" : "2022-07-25T11:30:49.553Z",
  "uafStatusCode" : 1498,
  "asmStatusCode" : 11,
  "clientErrorCode" : 12
}

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`.

Status Service

Base URL​

HTTP Methods​

Request Headers​

Request Body​

Response Headers​

Response Body​

Example Request (Successful Operation)​

Example Response (Successful Operation)​

Example Request (Failed Operation)​

Example Response (Failed Operation)​

HTTP Status Codes​