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

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
sessionIdStringThe session ID identifying the authentication session established in nevisFIDO.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 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:

AttributeTypeDescription
statusStringThe operation status for the provided session ID.
timestampStringISO-8601 timestamp in UTC when the status was last updated, for example, "2018-04-19T14:48:24.429Z". Absent when the status is unknown.
uafStatusCodeNumberThe UAF status code for the operation, see UAF Status Codes. Absent if the operation is not completed.
asmStatusCodeNumberThe 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.
clientErrorCodeNumberThe 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.
userIdStringThe 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.
tokenInformationObjectThe 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.nameStringThe [Dispatcher] used to dispatch the token. It is present if the client asked to dispatch the token.
tokenInformation.dispatcherInformation.responseStringThe information provided by the dispatcher after dispatching the token. If there was an unexpected error, this is also reported here.
tokenInformation.tokenResultStringThe 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).
authenticatorsArraySee 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[].aaidStringThe 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 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.