You are browsing documentation for an outdated plugin version.
Looking for the plugin's configuration parameters? You can find them in the Basic Authentication configuration reference doc.
Add Basic Authentication to a service or a route with username and password protection.
The plugin checks for valid credentials in the Proxy-Authorization
and Authorization
headers (in that order).
Usage
To use the plugin, you first need to create a Consumer to associate one or more credentials to. The Consumer represents a developer or an application consuming the upstream service.
Create a Consumer
You need to associate a credential to an existing Consumer object. A Consumer can have many credentials.
Consumer parameters:
Parameter | Description |
---|---|
username semi-optional |
The username of the consumer. Either this field or custom_id must be specified. |
custom_id semi-optional |
A custom identifier used to map the consumer to another database. Either this field or username must be specified. |
If you are also using the ACL plugin and allow lists with this service, you must add the new consumer to the allowed group. See ACL: Associating Consumers for details.
Create a Credential
Consumer credential parameters:
field/parameter | description |
---|---|
consumer |
The id or username property of the Consumer entity to associate the credentials to. |
username |
The username to use in the basic authentication credential. |
password |
The password to use in the basic authentication credential. |
Using the Credential
The authorization header must be base64 encoded. For example, if the credential
uses Aladdin
as the username and OpenSesame
as the password, then the field’s
value is the base64-encoding of Aladdin:OpenSesame
, or QWxhZGRpbjpPcGVuU2VzYW1l
.
The Authorization
(or Proxy-Authorization
) header must appear as:
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Make a request with the header:
curl http://kong:8000/{PATH_MATCHING_CONFIGURED_ROUTE} \
-H 'Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l'
gRPC clients are supported too:
grpcurl -H 'Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l' ...
Upstream Headers
When a client has been authenticated, the plugin appends some headers to the request before proxying it to the upstream service, so that you can identify the consumer in your code:
-
X-Consumer-ID
: The ID of the consumer in Kong. -
X-Consumer-Custom-ID
: Thecustom_id
of the consumer (if set). -
X-Consumer-Username
: Theusername
of the consumer (if set). -
X-Credential-Identifier
: The identifier of the credential (only if the consumer is not theanonymous
consumer). -
X-Anonymous-Consumer
: Is set totrue
if authentication fails, and theanonymous
consumer is set instead.
You can use this information on your side to implement additional logic.
You can use the X-Consumer-ID
value to query the Kong Admin API and retrieve
more information about the consumer.
Paginate through the basic-auth Credentials
You can paginate through the basic-auth Credentials for all Consumers using the following request:
You can filter the list by Consumer with the following endpoint:
username
or id
: The username or id of the consumer whose credentials need
to be listed.
Retrieve the Consumer associated with a Credential
It is possible to retrieve a Consumer associated with a basic-auth Credential using the following request:
username or id
: The id
or username
property of the basic-auth
Credential for which to get the associated Consumer.
Note that the username
accepted here is not the username
property of a
Consumer.