Skip to main content
Version: Next

multi-auth

Description#

The multi-auth Plugin is used to add multiple authentication methods to a Route or a Service. It supports plugins of type 'auth'. You can combine different authentication methods using multi-auth plugin.

This plugin provides a flexible authentication mechanism by iterating through the list of authentication plugins specified in the auth_plugins attribute. It allows multiple consumers to share the same route while using different authentication methods. For example, one consumer can authenticate using basic authentication, while another consumer can authenticate using JWT.

Attributes#

For Route:

NameTypeRequiredDefaultDescription
auth_pluginsarrayTrue-Add supporting auth plugins configuration. expects at least 2 plugins

Enable Plugin#

To enable the Plugin, you have to create two or more Consumer objects with different authentication configurations:

First create a Consumer using basic authentication:

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": "foo1",
"plugins": {
"basic-auth": {
"username": "foo1",
"password": "bar1"
}
}
}'

Then create a Consumer using key authentication:

curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
{
"username": "foo2",
"plugins": {
"key-auth": {
"key": "auth-one"
}
}
}'

Once you have created Consumer objects, 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": {
"multi-auth":{
"auth_plugins":[
{
"basic-auth":{ }
},
{
"key-auth":{
"query":"apikey",
"hide_credentials":true,
"header":"apikey"
}
}
]
}
},
"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:

Send a request with basic-auth credentials:

curl -i -ufoo1:bar1 http://127.0.0.1:9080/hello

Send a request with key-auth credentials:

curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -i
HTTP/1.1 200 OK
...
hello, world

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

{"message":"Authorization Failed"}

Delete Plugin#

To remove the multi-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
}
}
}'