Set Up API Authentication
For security, you should only allow authenticated and authorized consumers to access your APIs. API7 Gateway provides several plugins to enable authentication and authorization.
Authentication plugins enabled on services act as locks on your APIs, while consumer credentials serve as the keys to unlock them. In API7 Gateway, you need a unique username and at least one credential to set up a consumer.
Consumers can utilize multiple credentials of different types, all are treated equally for authentication purposes.
This guide walks you through enabling a simple key-based authentication using the key-auth
plugin and consumer credentials.
Prerequisite(s)
Add a Consumer with Key Authentication
A consumer is an entity that consumes your APIs. This example will create a consumer named Alice
.
- Dashboard
- ADC
- Ingress Controller
- Select Consumers of your gateway group from the side navigation bar.
- Click Add Consumer.
- From the dialog box, do the following:
- In the Name field, enter
Alice
. - Click Add.
- Under the Credentials tab, click Add Key Authentication Credential.
- From the dialog box, do the following:
- In the Name field, enter
primary-key
. - In the Key field, choose Manually Input, then enter
alice-primary-key
. If you have already added secret provider in the gateway group and store secret for key authentication credential, you can choose Reference from Secret Provider, then enter$secret://vault/my-vault/consumer/alice/key
. - Click Add.
consumers:
- username: Alice
credentials:
- name: primary-key
type: key-auth
config:
key: alice-primary-key
Coming soon.
Enable Key Authentication for APIs
For a Service
To use key authentication for all routes in a service, enable the key-auth
plugin on the service.
- Dashboard
- ADC
- Ingress Controller
- Select Published Services of your gateway group from the side navigation bar, then select the service you want to modify, for example,
httpbin
with version1.0.0
. - Select Plugins from the side navigation bar, then click Enable Plugin.
- Search for the
key-auth
plugin, then click Enable. - In the dialog box do the following:
Add the following configuration to the JSON Editor:
{
}Click Enable.
Update the service configuration to use key authentication:
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
plugins:
key-auth:
_meta:
disable: false
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
Synchronize the configuration to API7 Enterprise:
adc sync -f adc-consumer.yaml -f adc-service.yaml
ADC uses the configuration files as the single source of truth. So make sure to pass both the consumer and service configuration files to the adc sync
command for both configurations to take effect.
ApisixService custom resource is not yet available.
For a Single Route
- Dashboard
- ADC
- Ingress Controller
To use key authentication for a specific route, enable the key-auth
plugin on the route instead of the service.
- Select Published Services of your gateway group from the side navigation bar, then select the service you want to modify, for example,
httpbin
with version1.0.0
. - Under the published service, select Routes from the side navigation bar.
- Select your target route, for example,
get-ip
. - In the Plugin field, click Enable Plugin.
- Search for the
key-auth
plugin, then click Enable. - In the dialog box do the following:
Add the following configuration to the JSON Editor:
{
}Click Enable.
Update the route configuration to use key authentication:
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
plugins:
key-auth:
_meta:
disable: false
Synchronize the configuration to API7 Gateway:
adc sync -f adc-consumer.yaml -f adc-route.yaml
ADC uses the configuration files as the single source of truth. So make sure to pass both the consumer and service configuration files to the adc sync
command for both configurations to take effect.
Create a Kubernetes manifest file for a route, where key authentication is enabled:
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: get-ip
# namespace: api7 # replace with your namespace
spec:
http:
- name: httpbin-route
match:
paths:
- /ip
methods:
- GET
backends:
- serviceName: httpbin
servicePort: 80
authentication:
enable: true
type: keyAuth
Apply the configurations to your cluster:
kubectl apply -f httpbin-route.yaml
Validate
Follow the steps below to validate the key authentication.
Send a Request without a Key
Send a request without the apikey
header:
curl -i "http://127.0.0.1:9080/ip"
Since the key is not provided, you will receive an HTTP/1.1 401 Unauthorized
response with the following request body:
{"message":"Missing API key found in request"}
Send a Request with a Wrong Key
Send a request with a wrong key in the apikey
header:
curl -i "http://127.0.0.1:9080/ip" -H "apikey: wrongkey"
Since the key is wrong, you will receive an HTTP/1.1 401 Unauthorized
response with the following request body:
{"message":"Invalid API key in request"}
Send a Request with the Correct Key
Send a request with the correct key in the apikey
header:
curl -i "http://127.0.0.1:9080/ip" -H "apikey: alice-primary-key"
With the correct key in the request, you will receive an HTTP/1.1 200 OK
response with the following request body:
{
"origin": "192.168.0.102, 35.259.159.12"
}
Additional Resource(s)
- Key Concepts
- API Consumption