Authorization

To consume a subscribed API service, certain authentication and authorization is always necessary. The exact implementation depends on the service provider.

apinity offers two options to providers to manage authorization: either by implementing seamless Access Control between the gateway and the API server, or by requiring pass-through authorization directly from the subscribers.

Irrespective of the providers' choice, subscribers will always have to authenticate to the gateway itself using a valid Consumer Client.

This article describes each part of the authorization chain.

1. Consumer Client

For each subscription, at least one Consumer Client must be assigned. Each subscription also has a unique Base URL through which the API service can be consumed.

A successful login call with the Consumer Client to an assigned service (baseURL), with a valid subscription, will return a JWT token.

This token must be included in all subsequent requests in the x-apx-authorization header. Without the token, the gateway will return a 401 Unathorized response instead. If the header is present, but the token is incorrect, the gateway response is 403 Forbidden. In both cases, the gateway will not forward the request to the provider, acting as the first line of security check.

(The consumer token can also be sent in the Authorization header instead of x-apx-authorization, if that header is not needed for pass-through authorization (2b). In this case, the gateway consumes the Authorization header and replaces it with the access control (2a), or deletes it altogether before forwarding the request to the provider.)

2a. Access Control

With an Access Control, providers can set up a persistent authorization between the apinity gateway and their API server. This setup will handle a pre-defined authentication loop seamlessly for every request coming from subscribers, and inject (and replace!) the Authorization header when the request leaves the gateway.

If an Access Control is used, subscribers generally don't have to submit any further authorization directly to the provider. The gateway adds special headers that uniquely identify the subscriber. This allows providers to set up individual processing logic and data separation per customer, without having to rely on individual authentication. The need for a successful consumer client authentication (see step 1.) ensures that only valid requests will be forwarded.

Pros: - Consumers have to use less authorization credentials in API requests. - Providers don't have to manage individual credentials directly with consumers. - Supports the safest standard methods, e.g. OAuth2.

Cons: - Pre-defined choice of authentication methods. - Little support for custom parameters.

2b. Pass-through authorization

If persistent Access Control is not desired by a service provider, or the API service uses a non-standard method of authorization (e.g. query parameter, custom value in the request body, custom fields in OAuth login), consumers can use individual authorization agains the API server.

In this case, providers will hand out the necessary credentials and inform the subscribers individually how to submit credentials in their API requests. Assuming that the request carries a valid consumer client (see step 1.), the gateway forwards the request to the API server unmodified, including any kind of authorization data.

Pros: - Allows any custom authorization method. - Allows providers stricter individual credential management.

Cons: - Providers and subscribers have increased overhead to manage credentials. - Each API request must carry two pieces of authorization (consumer client + provider auth).