Manage Consumer Credentials

A consumer is an application or a developer that consumes your API. Enabling authentication on a service allows you to control access, requiring consumers to obtain the credentials before accessing the APIs.

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 tutorial guides you in creating a consumer and configuring authentication.

Prerequisites

1. Install API7 Enterprise.
2. Have a running API on the gateway group.

Key Authentication

Add a Consumer with Key Authentication Credentials

Dashboard

1. Select Consumers of your gateway group from the side navigation bar.
2. Click Add Consumer.
3. From the dialog box, do the following:

• In the Name field, enter Alice.
• Click Add.

4. Under the Credentials tab, click Add Key Authentication Credential.
5. 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.
• Click Add.

6. Try again to add another Key Authentication Credential named backup-key with key alice-backup-key.

ADC

adc-consumer.yaml

consumers:
  - username: Alice
    credentials:
      - name: primary-key
        type: key-auth
        config:
          key: alice-primary-key
      - name: backup-key
        type: key-auth
        config:
          key: alice-backup-key

Synchronize the configuration to API7 Enterprise:

adc sync -f adc-consumer.yaml

Ingress Controller

Coming Soon.

Enable Key Authentication For a Published Service

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

Dashboard

1. Select Published Services of your gateway group from the side navigation bar, then select the service you want to modify, for example, httpbin with version 1.0.0.
2. Select Plugins from the side navigation bar, then click Enable Plugin.
3. Search for the key-auth plugin, then click Enable.
4. In the dialog box do the following:

• Add the following configuration to the JSON Editor:

  {
  }

• Click Enable.

ADC

Update the service configuration to use key authentication:

adc-service.yaml

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

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.

Ingress Controller

ApisixService custom resource is not yet available.

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 an Invalid Key

Send a request with an invalid key in the apikey header:

curl -i "http://127.0.0.1:9080/ip" -H "apikey: invalidkey" 

Since the key does not belong to any consumer credential, 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

All key authentication credentials are treated equally and can be used in your API requests. There is no priority among multiple credentials, and they all have the same effect.

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"
}

curl -i "http://127.0.0.1:9080/ip" -H "apikey: alice-backup-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"
}

Basic Authentication

Add a Consumer with Basic Authentication Credentials

Dashboard

1. Select Consumers of your gateway group from the side navigation bar.
2. Click Add Consumer.
3. From the dialog box, do the following:

• In the Name field, enter Alice.
• Click Add.

4. Under the Credentials tab, click Basic Authentication tab, then click Add Basic Authentication Credential.
5. From the dialog box, do the following:

• In the Name field, enter primary-basic.
• In the Username field, enter Alice.
• In the Password field, choose Manually Input, then enter alice-password.
• Click Add.

6. Try again to add another Basic Authentication Credential named backup-basic with username Alice-backup and password alice-backup-password.

ADC

Coming Soon.

Ingress Controller

Coming Soon.

Enable Basic Authentication For a Published Service

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

Dashboard

1. Select Published Services of your gateway group from the side navigation bar, then select the service you want to modify, for example, httpbin with version 1.0.0.
2. Select Plugins from the side navigation bar, then click Enable Plugin.
3. Search for the basic-auth plugin, then click Enable.
4. In the dialog box do the following:

• Add the following configuration to the JSON Editor:

  {
  }

• Click Enable.

ADC

Coming Soon.

Ingress Controller

ApisixService custom resource is not yet available.

Validate

Follow the steps below to validate the basic authentication.

Send a Request without Basic Authentication Credential

Send a request without a basic authentication credential in the header:

curl -i "http://127.0.0.1:9080/ip"  

Since the credential is not provided, you will receive an HTTP/1.1 401 Unauthorized response with the following request body:

{"message":"Missing authorization in request"}

Send a Request with an Invalid Basic Authentication Credential

Send a request with an invalid basic authentication credential(username and password do not match, or username does not exist) in the header:

curl -i "http://127.0.0.1:9080/ip" -u alice:wrong-password

Since the password does not match any consumer credential, you will receive an HTTP/1.1 401 Unauthorized response with the following request body:

{"message":"Invalid user authorization"}

Send a Request with the Correct Basic Authentication Credential

All basic authentication credentials are treated equally and can be used in your API requests.

curl -i "http://127.0.0.1:9080/ip" -u alice:alice-password 

With the correct credential 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"
}

curl -i "http://127.0.0.1:9080/ip" -u alice-backup:alice-backup-password

With the correct credential 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 Resources

• Key Concepts
  • Services
  • Routes
  • Plugins
  • Consumers
• API Security
  • Set up API authentication
• API Consumption
  • Apply list-based access control
• Plugin Hub
  • Key Authentication
  • Basic Authentication