Skip to content

Latest commit

 

History

History
154 lines (122 loc) · 4.88 KB

basic-auth.md

File metadata and controls

154 lines (122 loc) · 4.88 KB
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
        }
    }
}'