Skip to main content
Version: Next

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.

Enabling the plugin#

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

curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "foo",
"plugins": {
"ldap-auth": {
"user_dn": "cn=user01,ou=users,dc=example,dc=org"
}
}
}'

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

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",
"plugins": {
"ldap-auth": {
"base_dn": "ou=users,dc=example,dc=org",
"ldap_uri": "localhost:1389",
"uid": "cn"
},
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'

Example usage#

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

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

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

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

Disable Plugin#

To disable 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.

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
}
}
}'