Accessing Protected HTTP APIs

Overview

The application using this SDK is able to access protected HTTP API endpoints.

To access these protected endpoints, an AuthorizationProvider must be provided. This is the case for the following operations: In-band registration, deregistration, and delete dispatch target.

Currently, the SDK supports HTTP Cookie and JWT token based authentication.

Retrieve Authorization Provider

To be able to access a nevisFIDO protected endpoint an AuthorizationProvider has to be provided when starting such an operation. Therefore, first the AuthorizationProvider has to be retrieved as a result of an nevisFIDO authentication as described by the following flow:

  1. Execute HTTP request to a nevisFIDO protected HTTP API endpoint
  2. Backend responds with HTTP 401 UNAUTHORIZED

    func needsAuthentication(_ response: HTTPURLResponse?) -> Bool {
       response?.statusCode == 401
    }
    
  3. The app must intercept such HTTP responses

    let userInteractionDelegate: UserInteractionDelegate = ...
    let task = session.dataTask(with: request) { data, response, error in
       if let error = error {
           // Handle error
       }
    
       guard let httpResponse = response as? HTTPURLResponse else {
           // Handle error
       }
    
       if self.needsAuthentication(httpResponse) {
           nevisSession.authenticate(userInteractionDelegate: userInteractionDelegate) { result in
               switch result {
               case .success:
                   // Retry original request by using the new credentials
               case let .failure(error):
                   // Handle error
               }
           }
           return
       }
       // Request is authorized, handle contents
    }
    task.resume()
    
  4. Call authentication in the SDK. See In-Band Authentication.

  5. SDK returns an AuthorizationProvider object, containing either an array of HTTP Cookies (within an instance of a CookieAuthorizationProvider) or a JWT Bearer Token (within an instance of a JwtAuthorizationProvider) for the app.

  6. App stores the content of the provider and sets it in all following HTTP requests (either in Cookie or in Authorization request header).

    Note Even if the App uses URLSessionConfiguration.default for its HTTP requests, the SDK provided authorization must also be set for the current URLSession or URLRequest the App uses.

  7. App retries the first failed HTTP request with the obtained authorization elements configured for the next requests.

  8. Backend considers the app to be authenticated, and returns the requested data

Note
In case the session is expired on the backend, the HTTP request to the protected endpoint will fail once again, and a new authentication has to be executed. With each authentication, the authorization elements stored in the app has to be updated.

Supported Authorization Providers

In case the backend endpoint is configured to be protected by using session cookies, the nevisFIDO authentication will return a CookieAuthorizationProvider.

This provider contains a set of session cookies are necessary for authorization.

JWT based

In case the backend endpoint is configured to be protected by using JWT token, the nevisFIDO authentication will return a JwtAuthorizationProvider.

This provider contains a JWT token which is necessary for authorization.