basic-auth.md

title	keywords	description
basic-auth	Apache APISIX API Gateway Plugin Basic Auth basic-auth	This document contains information about the Apache APISIX basic-auth Plugin.

Description

The basic-auth Plugin is used to add basic access authentication to a Route or a Service.

This works well with a Consumer. Consumers of the API can then add their key to the header to authenticate their requests.

Attributes

For Consumer:

Name	Type	Required	Description
username	string	True	Unique username for a Consumer. If multiple Consumers use the same username, a request matching exception is raised.
password	string	True	Password of the user. This field supports saving the value in Secret Manager using the APISIX Secret resource.

NOTE: encrypt_fields = {"password"} is also defined in the schema, which means that the field will be stored encrypted in etcd. See encrypted storage fields.

For Route:

Name	Type	Required	Default	Description
hide_credentials	boolean	False	false	Set to true will not pass the authorization request headers to the Upstream.

Enable Plugin

To enable the Plugin, you have to create a Consumer object with the authentication configuration:

:::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')

:::

curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "username": "foo",
    "plugins": {
        "basic-auth": {
            "username": "foo",
            "password": "bar"
        }
    }
}'

You can also use the APISIX Dashboard to complete the operation through a web UI.

Once you have created a Consumer object, you can then configure a Route or a Service to authenticate requests:

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

Example usage

After you have configured the Plugin as mentioned above, you can make a request to the Route as shown below:

curl -i -ufoo:bar http://127.0.0.1:9080/hello

HTTP/1.1 200 OK
...
hello, world

If the request is not authorized, an error will be thrown:

HTTP/1.1 401 Unauthorized
...
{"message":"Missing authorization in request"}

And if the user or password is not valid:

HTTP/1.1 401 Unauthorized
...
{"message":"Invalid user authorization"}

Delete Plugin

To remove the basic-auth Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

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