ldap-auth

Description

The ldap-auth Plugin can be used to add LDAP authentication to a Route or a Service.

This Plugin works with the Consumer object and the consumers of the API can authenticate with an LDAP server using basic authentication.

This Plugin uses lua-resty-ldap for connecting with an LDAP server.

Attributes

For Consumer:

NameTypeRequiredDescription
user_dnstringTrueUser dn of the LDAP client. For example, cn=user01,ou=users,dc=example,dc=org. This field supports saving the value in Secret Manager using the APISIX Secret resource.

For Route:

NameTypeRequiredDefaultDescription
base_dnstringTrueBase dn of the LDAP server. For example, ou=users,dc=example,dc=org.
ldap_uristringTrueURI of the LDAP server.
use_tlsbooleanFalsefalseIf set to true uses TLS.
tls_verifybooleanFalsefalseWhether to verify the server certificate when use_tls is enabled; If set to true, you must set ssl_trusted_certificate in config.yaml, and make sure the host of ldap_uri matches the host in server certificate.
uidstringFalsecnuid attribute.

Enable plugin

First, you have to create a Consumer and enable the ldap-auth Plugin on it:

ldap-auth - 图1note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

  1. admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
  1. curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
  2. {
  3. "username": "foo",
  4. "plugins": {
  5. "ldap-auth": {
  6. "user_dn": "cn=user01,ou=users,dc=example,dc=org"
  7. }
  8. }
  9. }'

Now you can enable the Plugin on a specific Route or a Service as shown below:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
  2. {
  3. "methods": ["GET"],
  4. "uri": "/hello",
  5. "plugins": {
  6. "ldap-auth": {
  7. "base_dn": "ou=users,dc=example,dc=org",
  8. "ldap_uri": "localhost:1389",
  9. "uid": "cn"
  10. },
  11. },
  12. "upstream": {
  13. "type": "roundrobin",
  14. "nodes": {
  15. "127.0.0.1:1980": 1
  16. }
  17. }
  18. }'

Example usage

After configuring the Plugin as mentioned above, clients can make requests with authorization to access the API:

  1. curl -i -uuser01:password1 http://127.0.0.1:9080/hello
  1. HTTP/1.1 200 OK
  2. ...
  3. hello, world

If an authorization header is missing or invalid, the request is denied:

  1. curl -i http://127.0.0.1:9080/hello
  1. HTTP/1.1 401 Unauthorized
  2. ...
  3. {"message":"Missing authorization in request"}
  1. curl -i -uuser:password1 http://127.0.0.1:9080/hello
  1. HTTP/1.1 401 Unauthorized
  2. ...
  3. {"message":"Invalid user authorization"}
  1. curl -i -uuser01:passwordfalse http://127.0.0.1:9080/hello
  1. HTTP/1.1 401 Unauthorized
  2. ...
  3. {"message":"Invalid user authorization"}

Delete Plugin

To remove the ldap-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: $admin_key" -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. }'