Redeem Token Service

The FIDO client uses the Redeem Token Service to trigger a FIDO UAF registration, authentication or deregistration. Therefore, the client must provide the token it previously obtained.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/token/redeem/<operation>

The <operation> in the base URL can be registration, authentication or deregistration.

Having split endpoints allows you to protect nevisFIDO differently for each operation, by means of nevisProxy and nevisAuth. d nf you cannot guarantee a secure transmission of the token to the targeted user, you better protect the registrad deregistration endpoints. Otherwise, malicious clients might use stolen tokens to register new credentials and to deregister existing ones.

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/fido+uaf.
Content-Type	Content type header, must be application/json.

Request Body

To trigger the registration, authentication or deregistration process, the Redeem Token Service requires a request body with a JSON payload containing a token (in the token attribute). The next table shows the elements of the request body (JSON payload).

Attribute	Type	Description	Optional
token	String	The token previously obtained using the token creation endpoint in "/nevisfido/token/create/authentication".	false

Response Headers

The following response headers will be set:

Name	Description
Content-Type	Content type header, fixed to application/fido+uaf;charset=UTF-8.

Response Body

The ReturnUAFRequest object has the following structure:

Attribute	Type	Description
statusCode	Number	UAF status code for the operation.
uafRequest	String	The new UAF request message if the server decides to issue one.
op	String	Hint to the client regarding the operation type of the message, must be set to either one of Reg, Auth, or Dereg.
lifetimeMillis	Number	Hint informing the client application of the lifetime of the message in milliseconds. Absent if the operation was not successful.

The FIDO client either wants to trigger a FIDO registration, authentication or deregistration operation. Depending on the requested operation, the uafRequest part of the returned ReturnUAFRequest object will look different. If the FIDO client requested a registration operation, the uafRequest part will contain a RegistrationRequest object (see the Registration Request Service for details). In case of an authentication operation, the uafRequest part contains an AuthenticationRequest object (see the Authentication Request Service for details).

Example Request

POST /nevisfido/token/redeem/authentication HTTP/1.1
Accept: application/fido+uaf
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 54

{
  "token" : "f5afe3d8-11ef-43fb-ac67-0a72f75e4dbd"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/token/redeem/authentication' -i -X POST \
    -H 'Accept: application/fido+uaf' \
    -H 'Content-Type: application/json' \
    -d '{
  "token" : "f5afe3d8-11ef-43fb-ac67-0a72f75e4dbd"
}'

Example Response (1)

If the token provided in the token attribute of the request was created by nevisFIDO and not previously redeemed, the response will look like this:

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:30:12 GMT
Content-Type: application/fido+uaf;charset=UTF-8
Transfer-Encoding: chunked
Content-Length: 659

{
  "lifetimeMillis" : 120000,
  "uafRequest" : "[{\"header\":{\"serverData\":\"34FkwD4a8z8giOjU8Omv7TtxCq3yAZfyUXZRsU8GzQkCVg0A-gWY0hi79zkph53QMxm5SWvQxhI-H8arDnzCGA\",\"upv\":{\"major\":1,\"minor\":1},\"op\":\"Auth\",\"appID\":\"https://www.siven.ch/appID\",\"exts\":[{\"id\":\"ch.nevis.auth.fido.uaf.sessionid\",\"data\":\"sessionId\",\"fail_if_unknown\":false}]},\"challenge\":\"-ghSw7i-ShbLaHSDU7XZd1idOO_dOVenL4Pa67jWUaLiyXixwPE9H3L-89bZtyuXF1Ofmnfasl0Ql7aqSSel6A\",\"policy\":{\"accepted\":[[{\"userVerification\":1023,\"authenticationAlgorithms\":[1,2,3,4,5,6,7,8,9],\"assertionSchemes\":[\"UAFV1TLV\"]}]]}}]",
  "statusCode" : 1200,
  "op" : "Auth"
}

Note that in the above sample a ReturnUAFRequest object with operation type "Auth" is returned (op = "Auth"). This indicates that the initial GetUAFRequest object coming from the FIDO client/nevisAuth requested for an authentication operation. This also means that in the above sample, the uafRequest part of the ReturnUAFRequestn abject contains an AuthenticationRequest. Furthermore, the returned UAF status code is "1200", which indicates thatn ahe operation was successful (statusCode = "1200"). For a complete list of all possible UAF status codes that can be returned by the FIDO server, see UAF Status Codes.

Example Response (2)

If the token provided in the request was not created by nevisFIDO or it had been previously redeemed, the response will look like this:

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:30:11 GMT
Content-Type: application/fido+uaf;charset=UTF-8
Transfer-Encoding: chunked
Content-Length: 25

{
  "statusCode" : 1491
}

Note that in this case, the returned UAF status code is "1491". This means that the FIDO server considers the request as invalid. In such a case, the ReturnUAFRequest object does not contain a UAF request (uafRequest part), as you can see in the sample above.

HTTP Status Codes

The following HTTP status codes are returned by the Redeem Token Service:

HTTP Code	Description
200	OK The server processed the request successfully. It returns a ReturnUAFRequest JSON object containing a RegistrationRequest or an AuthenticationRequest (depending on the operation specified in the initial GetUAFRequest).
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/fido+uaf.
415	Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8.