Skip to main content
Version: Next

basic-auth

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:

NameTypeRequiredDescription
usernamestringTrueUnique username for a Consumer. If multiple Consumers use the same username, a request matching exception is raised.
passwordstringTruePassword 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:

NameTypeRequiredDefaultDescription
hide_credentialsbooleanFalsefalseSet to true will not pass the authorization request headers to the Upstream.

Enabling the Plugin#

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

curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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"}

Disable Plugin#

To disable the jwt-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: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",
"plugins": {},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'