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.
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:
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. |
The Airlock Gateway enforces rate limits defined on plans by maintaining counters.
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!
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.
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: 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: |