Set Up API Authentication

For security reasons, API7 Enterprise Edition should authenticate and authorize consumers before access to internal resources. A flexible plugin extension system and a number of existing plugins for user authentication and authorization are provided. For example:

• Key Authentication
• Basic Authentication
• JSON Web Token (JWT) Authentication
• Keycloak
• Casdoor
• Wolf RBAC
• OpenID Connect
• Central Authentication Service (CAS)
• HMAC
• Casbin
• LDAP
• Open Policy Agent (OPA)
• Forward Authentication

Each route can use one authentication mechanism selected from the available options. Different routes may use different authentication. However, enabling multiple authentication plugins on a single route is prohibited. Enabling authentication plugins as global rules is also prohibited to prevent conflicts.

Prerequisites

1. Obtain a User Account with Super Admin or API Provider Role.
2. Complete Add Service from API Definition.

Set Up Key Authentication for a Single Service

If you want to enable key authentication for all existing and future routes of a single service, try enable the key-auth plugin at the service level. This prevents enabling additional authentication plugins at the route level.

1. Select Services > your target service. In this tutorial, the Swagger Petstore service (See Add Service from API Definition) will be used as an example.
2. On the Plugins table of the service, click Add Plugin.
3. Choose key-auth as the plugin, then click Add.
4. Click Configure for key-auth plugin to see the plugin configuration details.

Set Up Key Authentication for a Single Route

If you want to enable key authentication for a single route, try enable the key-auth plugin at the route level. This prevents enabling plugins at the service level.

1. Select Services > your target service. In this tutorial, the Swagger Petstore service (See Add Service from API Definition) will be used as an example.
2. Select Routes > your target route. In this tutorial, the getPetById route will be used as an example.
3. On the Plugins table of the route, click Add Plugin.
4. Choose key-auth as the plugin, then click Add.
5. Click Configure for key-auth plugin to see the plugin configuration details.

Validate

Create a Test Consumer

1. Select API Consumers , then click Add Consumer.
2. Enter test as the Name, then click Add.

Enable Key Authentication on the Test Consumer

1. Select Consumers > test.
2. On the Plugins table of the consumer, click Add Plugin.
3. Choose key-auth as the plugin.
4. Apply the following configuration to the JSON Editor:

{
  "key": "secret-key"
 }

5. Click Add.

Send a request without any key:

curl -i http://127.0.0.1:9080/pet/1 

Since the key is not provided, you will receive an unauthorized HTTP/1.1 401 Unauthorized response.

HTTP/1.1 401 Unauthorized
Date: Fri, 01 Sep 2023 03:06:51 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/dev

{"message":"Missing API key found in request"}

Send a request with a wrong key:

curl -i 127.0.0.1:9080/pet/1 -H "apikey: wrongkey"

HTTP/1.1 401 Unauthorized
Date: Fri, 01 Sep 2023 03:08:00 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/dev

{"message":"Invalid API key in request"}

Send a request with the correct key:

curl -i 127.0.0.1:9080/pet/1 -H "apikey: secret-key"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 323
Connection: keep-alive
Date: Fri, 01 Sep 2023 03:09:22 GMT
x-srv-trace: v=1;t=ada7cefb43c4848d
x-srv-span: v=1;s=4221c976c3e1b0fe
Access-Control-Allow-Origin: *
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1693537822
ETag: W/"143-JIrwO+Sx1/7FTTpJ2ljwAfgaRCY"
Vary: Accept-Encoding
Server: APISIX/dev

{
  "name": "Dog",
  "photoUrls": [
    "https://example.com/dog-1.jpg",
    "https://example.com/dog-2.jpg"
  ],
  "id": 1,
  "category": {
    "id": 1,
    "name": "pets"
  },
  "tags": [
    {
      "id": 1,
      "name": "friendly"
    },
    {
      "id": 2,
      "name": "smart"
    }
  ],
  "status": "available"
}