API access control - how it works in detail
This article gives detailed insights on how API access control based on API keys works in the Airlock Gateway.
The focus of this content is on the usage of API keys. It does not provide details about other access control mechanisms of the Airlock Gateway.
Mapping information
As with any HTTP request sent to the Airlock Gateway, the applicable Mapping is determined based on the virtual host used and the request URI.
All mapping-specific access control mechanisms like filters or API enforcement are applied as usual.
API key-based access control relies on the following settings in the mapping:
- Access restrictions based on API plans
- How to communicate with the API Policy Service (of Airlock IAM)
- How to extract API keys from HTTP requests
Access restrictions based on API plans
To take access decisions, the Airlock Gateway uses the Access restrictions in the mapping's Access tab.
If the restriction list is empty or no restriction matches, access is granted. For example, if a restriction only matches HTTP GET requests, POST or PATCH requests on the same URL must be covered by separate restriction rules. Otherwise, they will be allowed.
Access is granted for a restricted HTTP request if all matching (HTTP method and path) access restrictions are met: The required roles, as well as the required plans, must have been granted for the request to be successfully authorized.
- Roles
Roles are typically used to implement access control for users and are granted on the session or for the request using the Control API. This is independent of API key-based access control and not further elaborated here.
- Plans
Plans are assigned to Tech-Clients in Airlock IAM. The Tech-Client that issued a request is identified using the API key sent with the request. The Airlock Gateway looks up Tech-Client plans (and other attributes) by calling the Airlock IAM API Policy Service.
Plans consist of an identifier and an optional rate limit. Rate limits are counted and enforced by Airlock Gateway.
Rate limit counters on Airlock Gateway
The Airlock Gateway enforces rate limits defined on plans by maintaining counters.
- The relevant plan for each request is determined as described above.
- If multiple plans are relevant for a request:
- The rate counters of all relevant plans for the calling Tech-Client count up.
- The request is forwarded to the protected back-end service until all count limits are used up.
Tech-Client attributes provided by Airlock IAM
The Airlock Gateway sends requests to Airlock IAM's API Policy Service in order to get the following Tech-Client attributes given an API key:
- Tech-Client ID
A unique identifier for the Tech-Client. It is used for reporting and logging and may be sent to the protected service.
- Display name
A typically human-readable name of the Tech-Client. It may be used for reporting purposes.
- Label
The label is a string value attribute of a Tech-Client. It is searchable and may be used to group Tech-Clients (e.g. organization name, stage name, etc.).
- Plans
A list of plans assigned to the Tech-Client. Each plan consist of its identifier (e.g. payments) and an optional rate limit (e.g. 10 requests/second).
- State
Information about the state of the Tech-Client and its API key: A Tech-Client and every API key may be locked, API keys may expire or not yet be valid.
Note that the Airlock Gateway may cache the Tech-Client information to improve performance. The cache timeout is configurable.
If the cache is disabled, a call to the API Policy Service is required for every API request processed by the Airlock Gateway!
Tech-Client attribute retrieval
To retrieve Tech-Client attributes from Airlock IAM, the Airlock Gateway connects to the API Policy Service. It is crucial for security that only trusted IAM instances are contacted by the gateway.
For this reason, a shared secret is used on both sides in addition to the connection security measures (TLS). The shared secret is used to sign requests and involves a timestamp. It is therefore essential that the clocks of all involved components (Airlock Gateway and Airlock IAM) are synchronized.
Note that the Airlock Gateway can connect to multiple IAM instances for different APIs. The API Policy Service to connect to is therefore selected in the Mapping configuration.
API key extraction
The Airlock Gateway extracts API keys from HTTP requests. The extraction mechanism is configured in the Mapping configuration. There are three types:
Type | Description |
|---|---|
Header | The API key is in an HTTP header line. This is the recommended API key extraction type. Example: |
Query parameter | The API key is in a URL query parameter. This type is less secure but may be especially useful in conjunction with HTTP redirects or links sent to the client. Example: Risk URLs are often logged or stored in URL histories. Depending on the application of API keys, this may impose a security risk. |
Cookie value | The API key is transported in an HTTP cookie. This type may be useful in-browser applications and may leverage the cookie security measures built into browsers. Example: |