Skip to main content

Enable ACL

Estimated reading time: 0 min read

API7 Cloud utilizes the Consumer functionality to provide fine-grained API authentication. An API request with valid credentials can be forwarded by the Apache APISIX normally, no matter which Application it accesses. This permissive access control might not be enough when users want to control which Consumers can access which Applications or APIs. So that requests from unauthorized Consumers will be rejected by Apache APISIX, and the API security can be enhanced.

ACL is a way to control the accessible clients of API.

This guide introduces how to configure the ACL policy on API7 Cloud.

important

The ACL policy is not available in the Free plan. Please see the Pricing Page for details.

Prepare the Environment

Deploy Apache APISIX

Please refer to How to Deploy Apache APISIX to learn how to deploy Apache APISIX and connect it to API7 Cloud. In this guide, we'll deploy an Apache APISIX instance on Docker.

Create Application and API

We'll create an Application with the following details in this guide.

  1. The Application name is acl-app.
  2. The path prefix is /v1.
  3. The HTTP Host is acl.httpbin.org.
  4. The upstream URL is https://httpbin.org.
  5. Configuring the Authentication Policy and using the Key Auth as the authentication method.
Why do we need to configure the Authentication Policy?

The objects that the ACL policy controls are Consumers, and API7 Cloud uses the authentication credentials of API requests to identify the Consumer.

The ACL policy won't work if you don't configure the Authentication policy.

Besides, we'll create an API inside the acl-app Application.

  1. The API name is json.
  2. The path is /json (exact match).
  3. Accepted HTTP method is GET.
tip

If you don't know how to configure an Application and API, please refer to the Getting Started guides first

Create Four Consumers

Let's create four Consumers via the guide of How to Create a Consumer. In addition, let's configure the Key Auth credential for each Consumer.

Consumer Cater

We created the Consumer whose name is Cater, the label is team-1, and configured the Key Auth Credential.

Consumer Charles

We created the Consumer named Charles, the label is team-1, and configured the Key Auth Credential.

Consumer Christopher

We created the Consumer named Christopher, the label is team-1, and configured the Key Auth Credential.

Consumer Christopher

We created the Consumer, whose name is Camila, the label is team-2, and configured the Key Auth Credential.

Test ACL Allow Mode

There are two running modes for the ACL: Allow and Deny. When the ACL policy runs under Allow mode, The Consumers you specified are in the allowed list, and only these Consumers can access the Application / API; On the contrary, when ACL policy runs under Deny mode, the Consumers you specified cannot access the Application / API (in the denied list).

In this section, we'll test the ACL Allow mode.

Configuring Consumers Directly

The ACL policy allows you to configure several Consumers by typing their names. This way is convenient when the Consumer account is not huge.

Now let's create the ACL policy on the acl-app Application by running the following steps. Of course, you can configure it on the API level. In such a case, only the API you configured is protected by the ACL policy.

  1. Enter the acl-app Application details page.
  2. Click on the Add Policy button.
  3. Select ACL and fill in the form.

Add ACL Policy

In this case, we allow Camila and Christopher to access this Application.

Now let's send some API requests with four Consumers' API key perspectives.

  • Send a request with the API Key of Cater. The request should fail, and the status code will be 403.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Cater>' -s
  • Send a request with the API Key of Charles. The request should fail, and the status code will be 403.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Charles>' -s
  • Send a request with the API Key Christopher. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Christopher>' -s
  • Send a request with the API Key of, Camila. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Camila>' -s

Configuring Consumers via Labels

It's not convenient to use the ACL policy if the number of Consumers is large. In such a case, you can configure the ACL policy via Consumer labels. In this section, we will show you how to use Consumer labels to configure the ACL allow list.

Let's update the ACL policy on the acl-app Application.

  1. Enter the acl-app Application details page.
  2. Edit the ACL policy.
  3. Update the configuration, and fill out the Allowed Consumer Labels to team-1.

Update ACL Policy 1

As per the configuration, Consumers with the label team-1 (Carter, Charles, and Christopher) can access this Application.

Now let's send some API requests with four Consumers' API key perspectives.

  • Send a request with the API Key of Cater. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Cater>' -s
  • Send a request with the API Key of Charles. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Charles>' -s
  • Send a request with API Key Christopher. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Christopher>' -s
  • Send a request with the API Key of, Camila. The request should fail, and the status code should be 403.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Camila>' -s

Test ACL Deny Mode

You can also configure the denied Consumer list in the ACL policy. In such a case, Consumers not on the list can access the Application usually.

Configuring Consumers Directly

Let's update the ACL policy on the acl-app Application.

  1. Enter the acl-app Application details page.
  2. Edit the ACL policy.
  3. Update the configuration, change the running mode to Deny, and fill out the Denied Consumer field.

Update ACL Policy 2

In this case, requests from Camila and Christopher will be rejected by Apache APISIX.

Now let's send some API requests with four Consumers' API key perspectives.

  • Send a request with the API Key of Cater. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Cater>' -s
  • Send a request with the API Key of Charles. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Charles>' -s
  • Send a request with API Key Christopher. The request should fail, and the status code should be 403.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Christopher>' -s
  • Send a request with the API Key of, Camila. The request should fail, and the status code should be 403.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Camila>' -s

Configuring Consumers via Labels

Similar to the Allow mode, you can also configure denied Consumers via labels.

  1. Enter the acl-app Application details page.
  2. Edit the ACL policy.
  3. Update the configuration, change the running mode to Deny, and fill out the Denied Consumer Labels to team-2.

Update ACL Policy 3

In our case, requests from Camila will be rejected by Apache APISIX.

Now let's send some API requests with four Consumers' API key perspectives.

  • Send a request with the API Key of Cater. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Cater>' -s
  • Send a request with the API Key of Charles. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Charles>' -s
  • Send a request with the API Key Christopher. The request should succeed.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Christopher>' -s
  • Send a request with the API Key Camila. The request should fail, and the status code should be 403.
curl http://127.0.0.1:9080/v1/json -H 'Host: acl.httpbin.org'  -H 'Authorization: <API Key of Camila>' -s

See Also