Project: APISIX (Orchestration & Management / API Gateway)
File: ldap-auth.md

title: ldap-auth keywords: Apache APISIX API Gateway Plugin LDAP Authentication ldap-auth description: This document contains information about the Apache APISIX ldap-auth Plugin. <!-- --> 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 . This Plugin uses for connecting with an LDAP server. 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 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. | | tlsverify| boolean | False | `false` | Whether to verify the server certificate when `usetls` is enabled; If set to `true`, you must set `ssltrustedcertificate` in `config.yaml`, and make sure the host of `ldap_uri` matches the host in server certificate. | | uid | string | False | `cn` | uid attribute. | 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: ```bash adminkey=$(yq '.deployment.admin.adminkey[0].key' conf/config.yaml | sed 's/"//g') ``` ::: ```shell 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: ```shell 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 } } }' ``` After configuring the Plugin as mentioned above, clients can make requests with authorization to access the API: ```shell curl -i -uuser01:password1 http://127.0.0.1:9080/hello ``` ```shell HTTP/1.1 200 OK ... hello, world ``` If an authorization header is missing or invalid, the request is denied: ```shell curl -i http://127.0.0.1:9080/hello ``` ```shell HTTP/1.1 401 Unauthorized ... {"message":"Missing authorization in request"} ``` ```shell curl -i -uuser:password1 http://127.0.0.1:9080/hello ``` ```shell HTTP/1.1 401 Unauthorized ... {"message":"Invalid user authorization"} ``` ```shell curl -i -uuser01:passwordfalse http://127.0.0.1:9080/hello ``` ```shell HTTP/1.1 401 Unauthorized ... {"message":"Invalid user authorization"} ``` 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. ```shell 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 } } }' ```