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:

  1. curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "username": "foo1",
  4. "plugins": {
  5. "basic-auth": {
  6. "username": "foo1",
  7. "password": "bar1"
  8. }
  9. }
  10. }'

Then create a Consumer using key authentication:

  1. curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "username": "foo2",
  4. "plugins": {
  5. "key-auth": {
  6. "key": "auth-one"
  7. }
  8. }
  9. }'

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

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

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "methods": ["GET"],
  4. "uri": "/hello",
  5. "plugins": {
  6. "multi-auth":{
  7. "auth_plugins":[
  8. {
  9. "basic-auth":{ }
  10. },
  11. {
  12. "key-auth":{
  13. "query":"apikey",
  14. "hide_credentials":true,
  15. "header":"apikey"
  16. }
  17. }
  18. ]
  19. }
  20. },
  21. "upstream": {
  22. "type": "roundrobin",
  23. "nodes": {
  24. "127.0.0.1:1980": 1
  25. }
  26. }
  27. }'

Example usage

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

request with basic-auth

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

request with key-auth

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

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

  1. HTTP/1.1 401 Unauthorized
  2. ...
  3. {"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.

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "methods": ["GET"],
  4. "uri": "/hello",
  5. "plugins": {},
  6. "upstream": {
  7. "type": "roundrobin",
  8. "nodes": {
  9. "127.0.0.1:1980": 1
  10. }
  11. }
  12. }'