ldap-auth

Authenticates consumers against an LDAP directory.

Category AuthenticationAdd it to Route, Service, Global rule, Plugin configEngine plugin ldap-authPriority 2540Needs a Consumer with a ldap-auth Credential

What it does

ldap-auth checks a username and password against your LDAP directory, Active Directory for example, and the password lives only there. The client sends both in the Authorization header in the Basic scheme. The gateway then signs in to the directory at LDAP URI with that password, under a name built from UID, the user name and Base DN.

The request passes as the consumer whose ldap-auth credential holds that same name under User DN. A request without credentials is answered 401 with Missing authorization in request, and one with a wrong password 401 with Invalid user authorization. Authentication shows how consumers and credentials fit together.

When to use it

• Staff and service accounts already in Active Directory call an internal API with their directory name and password, and nobody keeps a second password on the gateway.
• Each directory account that may call a route is mapped to its own consumer, so plugins that act by consumer, a limit for example, apply per account.
• The directory answers only over LDAPS on port 636, reached with Use TLS and TLS verify on.

Not for passwords kept on the gateway itself — see basic-auth (Authenticates consumers with HTTP Basic credentials), people who sign in at an identity provider in a browser — see openid-connect (Authenticates users against an OpenID Connect provider) or a decision another service makes for each request — see forward-auth (Delegates authentication to an external service).

Set it up

Sign users in against the directory over TLS by the name of their entry

Users sign in with the cn of their entry under the base DN, on Active Directory the entry's name and not the account name; a name that carries a space cannot sign in.

Set LDAP URI to ldap.example.com:636, set Base DN to ou=people,dc=example,dc=com, leave UID at cn, turn on Use TLS and turn on TLS verify.

ldap-auth · as the console saves it

{
  "ldap_uri": "ldap.example.com:636",
  "base_dn": "ou=people,dc=example,dc=com",
  "uid": "cn",
  "use_tls": true,
  "tls_verify": true
}

More scenarios

Map a consumer to the directory entry it signs in ascredential

The DN the route builds: its UID attribute, the sign-in name, then its base DN.

Set User DN to cn=jane.doe,ou=people,dc=example,dc=com.

ldap-auth credential · as the console saves it

{
  "user_dn": "cn=jane.doe,ou=people,dc=example,dc=com"
}

Things to know

• UID — On Active Directory user entries are named by cn, so a user signs in with the entry's name and not the account name. sAMAccountName does not form a name the directory accepts here.
• UID — A user name that carries a space cannot sign in.
• LDAP URI — With TLS on, still write the port: without one the connection goes to 389, not 636.
• LDAP URI — A scheme in front of the host, ldaps:// for example, is refused when you save; TLS is turned on with Use TLS.
• LDAP URI — An IPv6 address written without square brackets is refused when you save.
• Base DN — Users in deeper OUs cannot sign in: the name is built as <UID>=<user name>,<this DN>. Left empty, it is saved anyway and every sign-in is refused.
• User DN — Must equal <UID>=<user name>,<base DN> exactly, letter case included. Any other spelling of the same DN, or an empty one, gets the same 401 as a wrong password.
• AdviceTurn Hide credentials on unless the backend needs the directory password, and serve the route over HTTPS only.

Settings

The fields as the console shows them, section by section.

LDAP URIldap_uristringRequired

The directory's host and port, such as ad.example.com:636. It is not a URL, and without a port 389 is used.

pattern

^([$]secret://.+|[$][Ee][Nn][Vv]://.+|([^/:\s@\[\]]+|\[[0-9A-Fa-f.]*:[0-9A-Fa-f:.]*\])(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?)$

· example ldap.example.com:389

Base DNbase_dnstringRequired

The DN users live directly under, such as ou=people,dc=example,dc=com. No search runs: the sign-in name is built from it.

UIDuidstringdefault cn

The attribute the user entries are named by, usually cn, put in front of the user name to build the sign-in DN. On Active Directory user entries are named by cn, so the sign-in name has to equal the entry's CN; sAMAccountName does not form a DN.

Use TLSuse_tlsbooleandefault false

Connect with TLS from the first byte (LDAPS), usually on port 636.

TLS verifytls_verifybooleandefault false

Check the certificate the directory presents. Only read when Use TLS is on.

Realmrealmstringdefault ldap

The name the client is asked to sign in to, sent back on every refusal.

1 to 128 characters ·

pattern

^[ -!#-[\]-~]+$

Hide credentialshide_credentialsbooleandefault false

Keep the Authorization header from reaching the upstream. Left off, the directory password travels on with the request.

Credential

What each consumer's credential for ldap-auth carries.

User DNuser_dnstringRequired

The distinguished name this consumer signs in as, such as cn=alice,ou=people,dc=example,dc=com.

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.