ldap-auth-advanced

Authenticates consumers against LDAP with a service-account bind and a user search.

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

What it does

ldap-auth-advanced checks a username and password against your LDAP directory, Active Directory for example, and the password lives only there. The gateway connects to LDAP URI as the account under Bind DN, and searches below Base DN for the one entry whose Attribute holds the user name. It then checks the client's password against that entry.

The request passes as the consumer whose ldap-auth-advanced credential holds that entry under User DN, written as the search returns it. A request without credentials, or with a wrong password, is answered 401 with Authorization required. Authentication shows how consumers and credentials fit together.

When to use it

• Staff sign in with their account name, the sAMAccountName of Active Directory, and not with the full name of their directory entry.
• The directory lets nobody search without signing in, so the gateway searches with a service account of its own.
• Users sit in several units below one base, and the search finds each of them wherever their entry is.
• Any account the directory accepts may call an internal route, with Consumer required off, and no consumer is kept per person.

Not for a directory where the user's name is built from one attribute and the base — see ldap-auth (Authenticates consumers against an LDAP directory), passwords kept on the gateway itself — see basic-auth (Authenticates consumers with HTTP Basic credentials) or people who sign in at an identity provider in a browser — see openid-connect (Authenticates users against an OpenID Connect provider).

Set it up

Look users up with a service account and match them by account name

Clients send `Authorization: Ldap` followed by the base64 of user:password, or Basic once Header type is basic.

Under Basics set LDAP URI to ldap.example.com:389, set Base DN to ou=people,dc=example,dc=com, set Bind DN to cn=gateway,ou=services,dc=example,dc=com, set LDAP password to <secret> and set Attribute to sAMAccountName. Under Behavior turn on Use StartTLS and turn on SSL verify.

ldap-auth-advanced · as the console saves it

{
  "ldap_uri": "ldap.example.com:389",
  "use_starttls": true,
  "ssl_verify": true,
  "base_dn": "ou=people,dc=example,dc=com",
  "bind_dn": "cn=gateway,ou=services,dc=example,dc=com",
  "ldap_password": "<secret>",
  "attribute": "sAMAccountName"
}

More scenarios

Map a consumer to the directory entry it signs in ascredential

Written as the search returns it, which on Active Directory is the entry's name with upper-case attribute types, not a DN built from the account name.

Set User DN to CN=Jane Doe,OU=People,DC=example,DC=com.

ldap-auth-advanced credential · as the console saves it

{
  "user_dn": "CN=Jane Doe,OU=People,DC=example,DC=com"
}

Things to know

• User DN — On Active Directory the search returns the entry's name with upper-case attribute types, CN=Jane Doe,OU=People,DC=example,DC=com for example. A name built from the account name does not match it.
• Header type — With basic, the client sends its account name and password in the Basic scheme, and a wrong password is answered 401 with Authorization required.
• Attribute — A name that matches more than one entry under the base DN is refused, so the attribute must identify one person.
• Attribute — An attribute name that carries a space, sAM AccountName for example, is refused when you save.
• Bind DN — A bind DN without its password is refused when you save.
• LDAP URI — A scheme in front of the host, ldaps:// for example, is refused when you save; TLS is turned on with Use LDAPS or Use StartTLS.
• Use StartTLS — On together with Use LDAPS is refused when you save.
• Consumer required — On, a user the directory accepts is still refused unless a consumer holds their DN as a credential of this plugin. Off, the directory alone decides and no consumer is attached to the request.
• AdviceGive the gateway a service account of its own that may only search the directory, and keep its password as a $secret:// reference.

Settings

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

Basics

LDAP URIldap_uristringRequired

Host of the directory with an optional :port, without ldap:// or ldaps://, such as ad.example.com:636. Without a port it uses 636 under LDAPS and 389 otherwise. A value with ldaps:// in front is saved without a word, and every sign-in then answers 500.

1 to 256 characters ·

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

Use LDAPSuse_ldapsbooleandefault false

Open the connection in TLS. Not together with StartTLS.

Base DNbase_dnstringRequired

Where the search for the user starts. Every entry below it is searched.

1 to 4096 characters

Bind DNbind_dnstring

The directory account the search runs as. Left empty, the search binds anonymously. Needs LDAP password beside it.

1 to 4096 characters

LDAP passwordldap_passwordstring

Password of the bind account, required once Bind DN is set. A $secret:// or $env:// reference is resolved before the plugin reads it. Stored on the engine and shown only to roles that manage this object.

1 to 4096 characters

Attributeattributestringdefault cn

The attribute the user name is matched against, as (attribute=name). A descriptor such as cn or sAMAccountName, or a numeric object identifier.

up to 256 characters ·

pattern

^(?:[A-Za-z][A-Za-z0-9-]*|(?:0|[1-9][0-9]*)(?:\.(?:0|[1-9][0-9]*))+)(?:;[A-Za-z0-9-]+)*$

Behavior

Use StartTLSuse_starttlsbooleandefault false

Open a plain connection and upgrade it to TLS. Not together with LDAPS.

SSL verifyssl_verifybooleandefault true

Check the certificate the directory presents. Only read when one of the two TLS switches is on.

Header typeheader_typestringdefault ldap

The word the client puts in front of its credentials, and the word this plugin answers an unauthenticated request with.

one of basic, ldap

Realmrealmstringdefault ldap

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

1 to 128 characters ·

pattern

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

Consumer requiredconsumer_requiredbooleandefault true

Require a consumer for the user the directory accepted.

Timeouttimeoutintegerdefault 10000

How long the plugin waits on the socket, for connecting, writing and reading alike.

1 to 60000 · in milliseconds

Advanced

Size limitsize_limitintegerdefault 2

How many entries the search may bring back. It floors at two so a second person with the same name is seen and the sign-in refused.

at least 2

Time limittime_limitintegerdefault 5

How long the directory may spend on the search. Zero leaves the bound to the directory.

at least 0 · in seconds

Keepalivekeepalivebooleandefault true

Keep the connection in a pool after a sign-in instead of closing it. A pooled connection is always bound again before the next search.

Keepalive pool namekeepalive_pool_namestring

Name of the pool the connection is kept in. Connections with different settings belong in different pools.

1 to 256 characters

Keepalive pool sizekeepalive_pool_sizeintegerdefault 5

How many connections the pool holds.

at least 1

Keepalive timeoutkeepalive_timeoutintegerdefault 60000

at least 1000 · in milliseconds

Credential

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

User DNuser_dnstringRequired

The distinguished name the directory holds for this person, as the search under the base DN returns it.

1 to 4096 characters

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