ldap-auth.md

title	keywords	description
ldap-auth	Apache APISIX API Gateway Plugin LDAP Authentication ldap-auth	This document contains information about the Apache APISIX ldap-auth Plugin.

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:

Name	Type	Required	Description
user_dn	string	True	User 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:

Name	Type	Required	Default	Description
base_dn	string	True		Base dn of the LDAP server. For example, ou=users,dc=example,dc=org.
ldap_uri	string	True		URI of the LDAP server.
use_tls	boolean	False	false	If set to true uses TLS.
tls_verify	boolean	False	false	Whether 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.
uid	string	False	cn	uid attribute.

Enable plugin

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

:::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": "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: $admin_key" -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"}

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.

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