HTTP APIs and Client Authentication

Description

This section describes a generic process of using FIDO authentication for protection and to authenticate against HTTP APIs. This process relies heavily on the nevisProxy and nevisAuth configuration, which must fit exactly or the outlined process will not work as described. The aim of the process is to simplify HTTP API authentication for HTTP clients having to interact with Nevis.

The setup described in this chapter allows you to:

1. Provide a single endpoint URL for HTTP clients to authenticate against.
2. Protect HTTP APIs that require authorisation with FIDO UAF authentication.
3. Respond with HTTP status code 401 to all endpoint calls without authorisation credentials provided by the HTTP client.
4. Allow certain HTTP methods to bypass the authorisation. For example, the HTTP PATCH method does not require authentication, whereas the HTTP DELETE method does.

Flow

Mappings

External URL	Request Content Type	nevisFIDO URL	Notes
/auth/fidouaf	application/json; charset=UTF-8	-	This endpoint always redirects to nevisAuth and will result in an AuthenticationRequest sent back to the client.
/auth/authenticationresponse	application/fido+uaf;charset=UTF-8	/nevisfido/uaf/1.1/authentication	This endpoint is used to send AuthenticationResponse objects from the client back to nevisFIDO.

Steps

The following table describes the steps of the HTTP API client authentication flow. The numbers in the table correspond with the numbers of the steps in the above figure Mappings of external URLs to nevisFIDO URLs.

Step nr.	Description	Endpoint	Payload	Notes
1	The Nevis client initiates the authentication by sending the user-to-be-authenticated to the defined "mobile authentication" endpoint URL.	/auth/fidouaf	application/json; charset=UTF-8 {"username":"<user to authenticate">	See the required configuration for nevisProxy and nevisAuth.
2	Nevis answers with 200 "OK".	-	A JSON containing the AuthenticationRequest (for details, see the chapter "Authentication Response Service" of the nevisFIDO Reference Guide).	The client must extract the fidoUafSessionId from the session ID extension sent in the AuthenticationRequest. This ID is needed for subsequent requests.
3	The client sends the AuthenticationResponse via HTTP POST.	/auth/authenticationresponse	A JSON containing the AuthenticationResponse (for details, see chapter "Authentication Response Service - Request Body" of the nevisFIDO Reference Guide).
4	Nevis answers with 200 "OK".	-	A JSON containing the StatusResponse (for details, see chapter "Authentication Response Service - Response Body" of the nevisFIDO Reference Guide).	Nevis answers with the StatusResponse.The client must evaluate the response to ensure that the statusCode indicates a successful FIDO UAF operation (1200 "OK").
5	The client sends the fidoUafSessionId via HTTP POST.	/auth/fidouaf	application/json; charset=UTF-8 {"fidoUafSessionId":"<sessionId>"}	The client sends the previously obtained session ID to Nevis to continue the authentication process.
6	Nevis answers with 200 "OK".	-	A JSON containing the StatusResponse (for details, see chapter "Status Service - Response Body"of the nevisFIDO Reference Guide)	Nevis answers with the current authentication status as described in the nevisFIDO Reference Guide.The client must evaluate the response to ensure that the status attribute indicates a non-failure.If the value of the status attribute is not "succeeded", the client needs to re-send the request after a client-defined period.
7	The client sends the fidoUafSessionId via HTTP POST.	/auth/fidouaf	application/json; charset=UTF-8 {"fidoUafSessionId":"<sessionId>"}	If the last call returned "succeeded", the client needs to send a final request to establish the authenticated session.
8	Nevis answers with 200 "OK" or 401 ("unauthorized").	-	application/json; charset=UTF-8, Cookie {"status":"completed"}	Nevis answers with a final response and the cookie.For the response payload, see the required configuration for the nevisAuth "AuthDone" state.The Nevis Authentication Cloud will answer with a JWT token instead of a cookie.

The current flow results in a returned cookie, which is bound to an authenticated user session. This is the expected behavior for the on-premise product. The Nevis Authentication Cloud uses JWT tokens.

Implementation

For implementation details such as Nevis component configuration snippets, refer to Use Cases and Best Practices.

info

When returning an HTTP 401 status response, the client does not need any additional headers. This is because the FIDO authentication is the only kind of authentication currently supported by the client.

Use the DirectResponseAuthState for the implementation of this feature. For more information, see the example snippets for In-Band Authentication.