Basic Authentication

Add Basic Authentication to a Service or a Route (or the deprecated API entity) with username and password protection. The plugin will check for valid credentials in the Proxy-Authorization and Authorization header (in this order).

Terminology

• plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
• Service: the Kong entity representing an external upstream API or microservice.
• Route: the Kong entity representing a way to map downstream requests to upstream services.
• upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.
• API: a legacy entity used to represent your upstream services. Deprecated in favor of Services since CE 0.13.0 and EE 0.32.

Configuration

Enabling the plugin on a Service

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=basic-auth"  \
    --data "config.hide_credentials=true"

• service: the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=basic-auth"  \
    --data "config.hide_credentials=true"

• route_id: the id of the Route that this plugin configuration will target.

Enabling the plugin on an API

If you are using an older version of Kong with the legacy API entity (deprecated in favor of Services since CE 0.13.0 and EE 0.32.), you can configure this plugin on top of such an API by making the following request:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=basic-auth"  \
    --data "config.hide_credentials=true"

• api: either id or name of the API that this plugin configuration will target.

Global plugins

All plugins can be configured using the http://kong:8001/plugins/ endpoint. A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Once applied, any user with a valid credential can access the Service/API. To restrict usage to only some of the authenticated users, also add the ACL plugin (not covered here) and create whitelist or blacklist groups of users.

Usage

In order 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. To create a Consumer, you can execute the following request:

curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/

A Consumer can have many credentials.

If you are also using the ACL plugin and whitelists with this service, you must add the new consumer to a whitelisted group. See ACL: Associating Consumers for details.

Create a Credential

You can provision new username/password credentials by making the following HTTP request:

$ curl -X POST http://kong:8001/consumers/{consumer}/basic-auth \
    --data "username=Aladdin" \
    --data "password=OpenSesame"

consumer: The id or username property of the Consumer entity to associate the credentials to.

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.

Then the Authorization (or Proxy-Authorization) header must appear as:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Simply make a request with the header:

$ curl http://kong:8000/{path matching a configured Route} \
    -H 'Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l'

Upstream Headers

When a client has been authenticated, the plugin will append 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 on Kong
• X-Consumer-Custom-ID, the custom_id of the Consumer (if set)
• X-Consumer-Username, the username of the Consumer (if set)
• X-Credential-Username, the username of the Credential (only if the consumer is not the ‘anonymous’ consumer)
• X-Anonymous-Consumer, will be set to true when authentication failed, and the ‘anonymous’ consumer was 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:

$ curl -X GET http://kong:8001/basic-auths

{
    "total": 3,
    "data": [
        {
            "created_at": 1511379926000,
            "id": "805520f6-842b-419f-8a12-d1de8a30b29f",
            "password": "37b1af03d3860acf40bd9c681aa3ef3f543e49fe",
            "username": "baz",
            "consumer_id": "5e52251c-54b9-4c10-9605-b9b499aedb47"
        },
        {
            "created_at": 1511379863000,
            "id": "8edfe5c7-3151-4d92-971f-3faa5e6c5d7e",
            "password": "451b06c564a06ce60874d0ea2f542fa8ed26317e",
            "username": "foo",
            "consumer_id": "89a41fef-3b40-4bb0-b5af-33da57a7ffcf"
        },
        {
            "created_at": 1511379877000,
            "id": "f11cb0ea-eacf-4a6b-baea-a0e0b519a990",
            "password": "451b06c564a06ce60874d0ea2f542fa8ed26317e",
            "username": "foobar",
            "consumer_id": "89a41fef-3b40-4bb0-b5af-33da57a7ffcf"
        }
    ]
}

You can filter the list using the following query parameters:

Retrieve the Consumer associated with a Credential

It is possible to retrieve a Consumer associated with a basic-auth Credential using the following request:

curl -X GET http://kong:8001/basic-auths/{username or id}/consumer

{
   "created_at":1507936639000,
   "username":"foo",
   "id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
}

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.