Manage Consumer Credentials

A consumer is an application 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 Enterprise, you need a unique username and at least one credential to set up a consumer.

Consumers can utilize multiple credentials of different types, all of which are treated equally for authentication purposes.

note

Consider if Developers is a better solution before implementing consumer-based credential management.

This tutorial guides you in creating a consumer and configuring authentication credentials.

Prerequisites

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

Configure Key Authentication Credentials

Dashboard

1. Select Consumers of your gateway group from the side navigation bar.
2. Click + Add Consumer.
3. In 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. In the dialog box, do the following:

• In the Name field, enter primary-key.
• In the Key field, enter alice-primary-key.
  • If you want to reference from secret provider, see Reference Secrets in HashiCorp Vault, Reference Secrets in AWS Secrets Manager, or Reference Secrets in Kubernetes Secret
• Click Add.

6. Try again to add another key authentication credential named backup-key with key alice-backup-key. All credentials are valid and can be used interchangeably for API authentication.

Below is an interactive demo that provides a hands-on introduction to configuring key authentication credential using API7 Enterprise.

ADC

Coming soon.

Ingress Controller

Gateway API

Create a Kubernetes manifest file for a consumer alice with one primary key and one backup key for key authentication:

consumer-cred.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: primary-key
      config:
        key: alice-primary-key
    - type: key-auth
      name: backup-key
      config:
        key: alice-backup-key

Alternatively, you can use Kubernetes Secret when configuring credentials:

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  name: key-auth-primary
  namespace: api7
data:
  key: YWxpY2UtcHJpbWFyeS1rZXk=
---
apiVersion: v1
kind: Secret
metadata:
  name: key-auth-backup
  namespace: api7
data:
  key: YWxpY2UtYmFja3VwLWtleQ==
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth-primary
      secretRef:
        name: key-auth-primary
    - type: key-auth
      name: key-auth-backup
      secretRef:
        name: key-auth-backup

❶ Base64 encode the primary key alice-primary-key.

❷ Base64 encode the backup key alice-backup-key.

Apply the configuration to your cluster:

kubectl apply -f consumer-cred.yaml

APISIX CRD

note

ApisixConsumer CRD currently does not support associating multiple credentials of the same type with a single consumer.

Create a Kubernetes manifest file for a consumer alice with one key for key authentication:

consumer-cred.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: alice-primary-key

Alternatively, you can use Kubernetes Secret when configuring credentials:

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  name: key-auth-primary
  namespace: api7
data:
  key: YWxpY2UtcHJpbWFyeS1rZXk=
---
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      secretRef:
        name: key-auth-primary

❶ Base64 encode the primary key alice-primary-key.

Apply the configuration to your cluster:

kubectl apply -f consumer-cred.yaml

Validate

See Enable Key Authentication for APIs for instructions, and enable the Key Auth Plugin on the service level.

Then follow Validate Key Authentication instructions.

Configure Basic Authentication Credentials

Dashboard

1. Select Consumers of your gateway group from the side navigation bar.
2. Click + Add Consumer.
3. In 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. In the dialog box, do the following:

• In the Name field, enter primary-basic.
• In the Username field, enter alice.
• In the Password field, enter alice-password.
  • If you want to reference from secret provider, see Reference Secrets in HashiCorp Vault, Reference Secrets in AWS Secrets Manager, or Reference Secrets in Kubernetes Secret
• Click Add.

6. Try again to add another basic authentication credential named backup-basic with username alice-backup and password alice-backup-password. All credentials are valid and can be used interchangeably for API authentication.

ADC

Coming soon.

Ingress Controller

Gateway API

Create a Kubernetes manifest file for a consumer alice with one primary and one backup credential for basic authentication:

consumer-cred.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: basic-auth
      name: primary-basic
      config:
        username: alice
        password: alice-password
    - type: basic-auth
      name: backup-basic
      config:
        username: alice-backup
        password: alice-backup-password

Alternatively, you can use Kubernetes Secret when configuring credentials:

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  name: basic-auth-primary
  namespace: api7
data:
  username: YWxpY2U=
  password: YWxpY2UtcGFzc3dvcmQ=
---
apiVersion: v1
kind: Secret
metadata:
  name: basic-auth-backup
  namespace: api7
data:
  username: YWxpY2UtYmFja3Vw
  password: YWxpY2UtYmFja3VwLXBhc3N3b3Jk
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: basic-auth
      name: basic-auth-primary
      secretRef:
        name: basic-auth-primary
    - type: basic-auth
      name: basic-auth-backup
      secretRef:
        name: basic-auth-backup

❶ Base64 encode the username alice.

❷ Base64 encode the password alice-password.

❸ Base64 encode the username alice-backup.

❹ Base64 encode the password alice-backup-password.

Apply the configuration to your cluster:

kubectl apply -f consumer-cred.yaml

APISIX CRD

note

ApisixConsumer CRD currently does not support associating multiple credentials of the same type with a single consumer.

Create a Kubernetes manifest file for a consumer alice with one primary credential for basic authentication:

consumer-cred.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    basicAuth:
      value:
        username: alice
        password: alice-password

Alternatively, you can use Kubernetes Secret when configuring credentials:

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  name: basic-auth-primary
  namespace: api7
data:
  username: YWxpY2U=
  password: YWxpY2UtcGFzc3dvcmQ=
---
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    basicAuth:
      secretRef:
        name: basic-auth-primary

❶ Base64 encode the username alice.

❷ Base64 encode the password alice-password.

Apply the configuration to your cluster:

kubectl apply -f consumer-cred.yaml

Validate

See Enable Basic Authentication for APIs for instructions, and enable the Basic Auth Plugin on the service level.

Then follow Validate Basic Authentication instructions.

Configure Varied Authentication Credentials

While consumers can have multiple credentials of different types, each route in a published service should be configured with only one authentication plugin. This allows consumers to access multiple routes using their preferred authentication methods.

Below is an interactive demo that provides a hands-on introduction to configuring various authentication credentials using API7 Enterprise.

Dashboard

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

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

4. Under the Credentials tab, click Add Key Authentication Credential.
5. In the dialog box, do the following:

• In the Name field, enter key-auth.
• In the Key field, enter john-key-auth.
• Click Add.

6. Under the Credentials tab, select Basic Authentication and click Add Basic Authentication Credential.
7. In the dialog box, do the following:

• In the Name field, enter basic-auth.
• In the Username field, enter john.
• In the Password field, enter john-password.
• Click Add.

8. Under the Credentials tab, select JWT and click Add JWT Credential.
9. In the dialog box, do the following:

• In the Name field, enter jwt-auth.
• In the Key field, enter john-jwt-key.
• In the Algorithm field, select RS256.
• In the Public Key field, enter your public key.
• Click Add.

10. Under the Credentials tab, select HMAC Authentication and click Add HMAC Authentication Credential.
11. In the dialog box, do the following:

• In the Name field, enter hmac-auth.
• In the Key ID field, enter john-key.
• In the Secret Key field, enter john-hmac-key.
• Click Add.

ADC

Coming soon.

Ingress Controller

Gateway API

Create a Kubernetes manifest file for a consumer john with credentials for multiple authentication methods:

consumer-cred.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  name: john
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth
      config:
        key: john-key-auth
    - type: basic-auth
      name: basic-auth
      config:
        username: john
        password: john-password
    - type: jwt-auth
      name: jwt-auth
      config:
        key: john-jwt-key
        algorithm: RS256
        public_key: "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
    - type: hmac-auth
      name: hmac-auth
      config:
        key_id: john-key
        secret_key: john-hmac-key

Alternatively, you can use Kubernetes Secret when configuring credentials:

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  name: key-auth-john
  namespace: api7
data:
  key: am9obi1rZXktYXV0aA==
---
apiVersion: v1
kind: Secret
metadata:
  name: basic-auth-john
  namespace: api7
data:
  username: am9obg==
  password: am9obi1wYXNzd29yZA==
---
apiVersion: v1
kind: Secret
metadata:
  name: jwt-auth-john
  namespace: api7
data:
  key: am9obi1qd3Qta2V5
  algorithm: UlMyNTY=
  public_key: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbi4uLlxuLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t
---
apiVersion: v1
kind: Secret
metadata:
  name: hmac-auth-john
  namespace: api7
data:
  key_id: am9obi1rZXk=
  secret_key: am9obi1obWFjLWtleQ==
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  name: john
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth-john
      secretRef:
        name: key-auth-john
    - type: basic-auth
      name: basic-auth-john
      secretRef:
        name: basic-auth-john
    - type: jwt-auth
      name: jwt-auth-john
      secretRef:
        name: jwt-auth-john
    - type: hmac-auth
      name: hmac-auth-john
      secretRef:
        name: hmac-auth-john

APISIX CRD

Create a Kubernetes manifest file for a consumer john with credentials for multiple authentication methods:

consumer-cred.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  name: john
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: john-key-auth
    basicAuth:
      value:
        username: john
        password: john-password
    jwtAuth:
      value:
        key: john-jwt-key
        algorithm: RS256
        public_key: |
          -----BEGIN PUBLIC KEY-----
          ...
          -----END PUBLIC KEY-----

Alternatively, you can use Kubernetes Secret when configuring credentials:

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  name: key-auth-john
  namespace: api7
data:
  key: am9obi1rZXktYXV0aA==
---
apiVersion: v1
kind: Secret
metadata:
  name: basic-auth-john
  namespace: api7
data:
  username: am9obg==
  password: am9obi1wYXNzd29yZA==
---
apiVersion: v1
kind: Secret
metadata:
  name: jwt-auth-john
  namespace: api7
data:
  key: am9obi1qd3Qta2V5
  algorithm: UlMyNTY=
  public_key: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbi4uLlxuLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t
---
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  name: john
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      secretRef:
        name: key-auth-john
    basicAuth:
      secretRef:
        name: basic-auth-john
    jwtAuth:
      secretRef:
        name: jwt-auth-john

note

The APISIX CRD currently does not support hmac-auth due to a breaking change in the latest version of the plugin.

In the configurations, the encoded content are:

• key-auth:
  • key john-key-auth
• basic-auth:
  • username john
  • password john-password
• jwt-auth:
  • key john-jwt-key
  • algorithm RS256
  • public key -----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY----- - you should replace and re-encode with the actual public key
• hmac-auth
  • key ID john-key
  • secret key john-hmac-key

Apply the configuration to your cluster:

kubectl apply -f consumer-cred.yaml

Additional Resources

• Key Concepts
  • Services
  • Routes
  • Plugins
  • Consumers
  • Secrets
• API Security
  • Set up API authentication
  • Reference Secrets in HashiCorp Vault
  • Reference Secrets in AWS Secrets Manager
  • Reference Secrets in Kubernetes Secret
• API Consumption
  • Apply List-Based Access Control
• Plugin Hub
  • Key Authentication
  • Basic Authentication
  • JWT Auth Plugin
  • HMAC Auth Plugin