Set Up API Authentication

For security, you should only allow authenticated and authorized consumers to access your APIs. API7 Enterprise provides several plugins to enable authentication and authorization.

This guide walks you through enabling a simple key-based authentication using the key-auth plugin.

Prerequisite(s)

1. Have a published service.

Add a Consumer

A consumer is an entity that consumes your APIs. This example will create a consumer named Alice.

Dashboard

1. Select the gateway group where your service is published.

2. Select Consumers from the side navigation bar.

3. Click Add Consumer.

4. From the Add Consumer dialog box, do the following:

   • In the Name field, enter Alice.

5. Click Add.

6. In the consumer you just created under the Plugins field, search for the key-auth plugin.

7. Click the Plus icon (+).

8. In the dialog box that appeared, add the following configuration to the JSON Editor:

   {
     "key": "secret-key"
   }

9. Click Enable.

ADC

To use ADC to create a consumer, create the following configuration:

adc-consumer.yaml

consumers:
  - username: Alice
    plugins:
      key-auth:
        _meta:
          disable: false
        key: secret-key

Synchronize the configuration to API7 Enterprise:

adc sync -f adc-consumer.yaml

Enable Key Authentication

For a Service

To use key authentication for all routes in a service, enable the key-auth plugin on the service.

note

You cannot enable other authentication plugins on a route if you have enabled the key-auth plugin on the service.

Dashboard

1. Select the service to enable key authentication.
2. Select Plugins from the side navigation bar.
3. Search for the key-auth plugin.
4. Click the Plus icon (+).
5. Click Enable.

ADC

Update the service configuration to use key authentication:

adc-service.yaml

services:
  - name: httpbin Service
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    plugins:
      key-auth:
        _meta:
          disable: false
    routes:
      - uris:
          - /ip
        name: api-security-ip
        methods:
          - GET

Synchronize the configuration to API7 Enterprise:

adc sync -f adc-consumer.yaml -f adc-service.yaml

note

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.

For a Single Route

Dashboard

To use key authentication for a specific route, enable the key-auth plugin on the route instead of the service.

1. Select the service where the route to enable key authentication is published.
2. Select Routes from the side navigation bar and select your target route.
3. Search for the key-auth plugin.
4. Click the Plus icon (+).
5. Click Enable.

ADC

Update the route configuration to use key authentication:

adc-route.yaml

services:
  - name: httpbin Service
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - uris:
          - /ip
        name: api-security-ip
        methods:
          - GET
        plugins:
          key-auth:
            _meta:
              disable: false

Synchronize the configuration to API7 Enterprise:

adc sync -f adc-consumer.yaml -f adc-route.yaml

note

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.

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: secret-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
  • Services
  • Routes
  • Plugins