End of Sale Notice:
F5 NGINX is announcing the End of Sale (EoS) for NGINX Management Suite API Connectivity Manager Module, effective January 1, 2024.
F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing API Connectivity Manager Module customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.
See our End of Sale announcement for more details.
API Key Authentication
Learn how to use F5 NGINX Management Suite API Connectivity Manager to secure API Gateways by applying an API key authentication policy.
Overview
In API Connectivity Manager, you can apply policies to an API Gateway to further enhance their configuration to meet your requirements.
Policies added at the proxy level are applied to all routes within that proxy.
For an overview of the different policy types and available policies, refer to the consult the Learn about Policies topic.
API Key Authentication
Warning:
API key authentication is recommended for test environments only. For production environments, consider a more robust authentication method.
Authentication & authorization policies allow a user to restrict access to their APIs by determining the caller’s identity and access level. There are several API Gateway authentication/authorization policy types supported by API Connectivity Manager: API key authentication, basic authentication, OAuth2 JWT assertion, and OAuth2 token introspection. This guide focuses specifically on API key authentication.
An API key is usually a long, pseudo-random string included in the request header or request URL. It is a shared secret between the API client and the API gateway. The server allows the client to access data only after the client authenticates the API key.
API Connectivity Manager API owners can restrict access to their APIs with API keys. The API Proxy Policy can be configured to grant access to APIs only after verifying that the API Key is valid.
Before You Begin
Complete the following prerequisites before proceeding with this guide:
- API Connectivity Manager is installed, licensed, and running.
- You have one or more Environments with an API Gateway.
- You have published one or more API Gateways
How to Access the User Interface
This guide provides instructions for completing tasks using the API Connectivity Manager user interface (UI).
To access the UI, go to the FQDN of your NGINX Management Suite host and log in. On the Launchpad menu, select “API Connectivity Manager.”
How to Access the REST API
You can use tools such as curl
or Postman to interact with the API Connectivity Manager REST API. The API URL follows the format https://<NMS_FQDN>/api/acm/<API_VERSION>
and must include authentication information with each call. For more information about authentication options, please refer to the API Overview.
Create an API Key Authentication Policy
Take the steps in this section if you want to restrict access to APIs to clients with a valid API key. You can set up an API key authentication policy using either the web interface or the REST API.
Send a POST request to add the API key authentication policy to the API Proxy.
Method | Endpoint |
---|---|
POST |
/services/workspaces/<SERVICE_WORKSPACE_NAME>/proxies |
Note:
To include sensitive data in ProxyGET
requests, provide the query parameterincludes=sensitivedata
; otherwise, the response will have this data redacted.
{
"policies": {
"apikey-authn": [
{
"action": {
"apiKeyName": "apikey",
"suppliedIn": "header",
"credentialForward": false,
"errorReturnConditions": {
"notSupplied": {
"returnCode": 401
},
"noMatch": {
"returnCode": 403
}
}
},
"data": [
{
"clientID": "clientA",
"apiKey": "5ff229f7d64e4d6"
},
{
"clientID": "clientB"
}
]
}
]
}
}
Field | Type | Possible Values | Description | Required | Default value |
---|---|---|---|---|---|
apiKeyName |
string | Example: clientAPIKey |
The name of the header or query parameter where the API key will be located in the API request. | No | apikey |
suppliedIn |
string | One of ["HEADER","QUERY"] |
How the API key will be supplied by the consumer of the API via HTTP request. | No | HEADER |
credentialForward |
boolean | true/false |
If the API key credential is proxy-forwarded to the backend service in the HTTP header or query parameters. | No | False |
errorReturnConditions .notSupplied .returnCode |
int | In range 400-599 |
The error code that is returned from the API Proxy when an invalid API key is supplied. | No | 401 |
errorReturnConditions .noMatch .returnCode |
int | In range 400-599 |
The error code that is returned from the API Proxy when an API key is not supplied. | No | 403 |
data.clientID |
string | Example: ClientA |
Identifies the client who is holding the API Key. | Yes | N/A |
data.apiKey |
string | Example: 5ff229f7d64e4d6 |
The value of the API Key used to access the API. If an API Key is not provided, a random 32-byte key will be created. | No | N/A |
- In the API Connectivity Manager user interface, go to Services > {your workspace}, where “your workspace” is the workspace that contains the API Proxy.
- Select Edit Proxy from the Actions menu for the desired API Proxy.
- On the Policies tab, select Add Policy from the Actions menu for API Key Authentication.
- Provide the API Key name if different from the default value
apikey
and if the key should be provided in the request Header or as a Query parameter. - Set custom error return code conditions if an API Key is not supplied or does not match a key configured for API access.
- By default, NGINX will strip the API key from the request headers before forwarding the request to the backend service. To preserve the API key header, enable the toggle for Forward credentials to backend service.
- Configure the associated Client ID and API Key for each client that requires API access. If an API Key is not provided, a random 32-byte key will be created. Repeat this process for all clients.
- Select Add to apply the API key authentication policy to the Proxy. Then select Save & Publish to deploy the configuration to the API Proxy.