Credential

Description

A Credential stores authentication plugin configuration for a Consumer. Each Credential contains at most one enabled authentication plugin, such as basic-auth, hmac-auth, jwt-auth, or key-auth.

A Consumer can have Credentials for different authentication plugins. It can also have multiple Credentials for the same authentication plugin when their identifying values differ. For example, a Consumer can rotate a key by creating a second key-auth Credential, switching clients to the new key, and then deleting the old Credential. Credential details are stored separately and are not included when you retrieve the Consumer resource.

Configuration options

The fields for defining a Credential are defined as below.

Field	Required	Description
desc	False	Description of the Credential.
labels	False	Labels of the Credential.
plugins	False	At most one authentication plugin configuration. For more information, see Plugins.

note

For more information about the Credential object, you can refer to the Admin API Credential resource guide.

Example

Consumer Example describes how to configure the auth plugin for Consumer and how to use it with other plugins. In this example, the Consumer has only one credential of type key-auth. Now suppose the user needs to configure multiple credentials for that Consumer, you can use Credential to support this.

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

1. Create the Consumer without specifying the auth plug-in, but use Credential to configure the auth plugin later.

   curl http://127.0.0.1:9180/apisix/admin/consumers \
   -H "X-API-KEY: $admin_key" -X PUT -d '
   {
       "username": "jack"
   }'

2. Create 2 key-auth Credentials for the Consumer.

   curl http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials/key-auth-one \
   -H "X-API-KEY: $admin_key" -X PUT -d '
   {
       "plugins": {
           "key-auth": {
               "key": "auth-one"
           }
       }
   }'

   curl http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials/key-auth-two \
   -H "X-API-KEY: $admin_key" -X PUT -d '
   {
       "plugins": {
           "key-auth": {
               "key": "auth-two"
           }
       }
   }'

3. Create a route and enable key-auth plugin on it.

   curl http://127.0.0.1:9180/apisix/admin/routes/1 \
   -H "X-API-KEY: $admin_key" -X PUT -d '
   {
       "plugins": {
           "key-auth": {}
       },
       "upstream": {
           "nodes": {
               "127.0.0.1:1980": 1
           },
           "type": "roundrobin"
       },
       "uri": "/hello"
   }'

4. Test.

   Test the request with the auth-one and auth-two keys, and they both respond correctly.

   curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
   curl http://127.0.0.1:9080/hello -H 'apikey: auth-two' -I

   Enable the limit-count plugin for the Consumer.

   curl http://127.0.0.1:9180/apisix/admin/consumers \
   -H "X-API-KEY: $admin_key" -X PUT -d '
   {
       "username": "jack",
       "plugins": {
           "limit-count": {
               "count": 2,
               "time_window": 60,
               "rejected_code": 503,
               "key": "remote_addr"
           }
       }
   }'

   Requesting the route more than 3 times in a row with each of the two keys, the test returns 503 and the request is restricted.