Skip to main content

HTTP APIs and Client Authentication

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​

title="HTTP API client authentication flow"

Mappings​

External URLRequest Content TypenevisFIDO URLDescription
/auth/fidouafapplication/json; charset=UTF-8-This endpoint always redirects to nevisAuth and will result in an AuthenticationRequest sent back to the client.
/auth/authenticationresponseapplication/fido+uaf;charset=UTF-8/nevisfido/uaf/1.1/authenticationThis endpoint is used to send AuthenticationResponse objects from the client back to nevisFIDO.

Steps​

The numbered steps describe the HTTP API client authentication flow. The numbers correspond with the numbers of the steps in the above figure.

  1. The Nevis client initiates the authentication by sending the user-to-be-authenticated to the defined "mobile authentication" endpoint URL.

    Endpoint: /auth/fidouaf

    Payload: application/json; charset=UTF-8 {"username":"<user to authenticate">

    See the required configuration for nevisProxy and nevisAuth.

  2. Nevis answers with 200 "OK".

    Payload: A JSON containing the AuthenticationRequest (for details, see the chapter "Authentication Response Service" of the nevisFIDO Reference Guide).

    danger

    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.

    Endpoint: /auth/authenticationresponse

    Payload: A JSON containing the AuthenticationResponse (for details, see Authentication Response Service - Request Body of the nevisFIDO Reference Guide).

  4. Nevis answers with 200 "OK".

    Payload: A JSON containing the StatusResponse (for details, see Authentication Response Service - Request Body of the nevisFIDO Reference Guide).

    Nevis answers with the StatusResponse.

    danger

    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.

    Endpoint: /auth/fidouaf

    Payload: 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".

    Payload: A JSON containing the StatusResponse (for details, see 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.

    danger

    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.

    Endpoint: /auth/fidouaf

    Payload: 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").

    Payload: application/json; charset=UTF-8 {"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.

info

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 Nevis Component Configuration Examples.

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.