LDAP Bind

Valve for LDAP based authentication

Introduction

Use this valve to validate user credentials (username/password) stored in an LDAP directory.

Note that bind requires the DN of the user authenticating and most likely you need to locate the user using a search before performing the bind.

Prerequisites

Before using this valve the LdapClient module must be configured and deployed.

Configuration

Valve name: LDAPBind

Common LDAP valve configuration can be found here.

Properties

Name	Description	Default value	Mandatory	Expanded
dn	Bind DN.
password	Bind password.
non_critical_errors	List of non-critical (AD) error codes.
error_key	Name of item property receiving non-critical error code.	"ad_error"

Example

{
  "name" : "LDAPBind",
  "config" : {
    "destination" : "default",
    "dn" : "${item.id}",
    "password" : "${request.password}"
  }
}

Microsoft Active Directory caveats

When binding to Active Directory (AD) error 49 (invalid credentials) sometimes needs to be considered non-critical (continue processing) and instead the custom AD error (embedded in the detail/diagnostics message) should be used.

To activate this functionality add the custom codes you need to handle to property "non_critical_errors" (as an array of strings or a csv string). If error 49 occurs, valve will search the error details for custom codes an add the found code to the current item using property name specified by "error_key". Use this property later in the flow to handle the error.

Error code are strings not numbers

Code	Error	Description
525	user not found	Returned when an invalid username is supplied.
52e	invalid credentials	Returned when a valid username is supplied but an invalid password/credential is supplied.
530	not permitted to logon at this time	Returned when a valid username and password/credential are supplied during times when login is restricted.
531	not permitted to logon from this workstation	Returned when a valid username and password/credential are supplied, but the user is restricted from using the workstation where the login was attempted.
532	password expired	Returned when a valid username is supplied, and the supplied password is valid but expired.
533	account disabled	Returned when a valid username and password/credential are supplied but the account has been disabled.
701	account expired	Returned when a valid username and password/credential are supplied but the account has expired.
773	user must reset password	Returned when a valid username and password/credential are supplied, but the user must change their password immediately (before logging in for the first time, or after the password was reset by an administrator).
775	account locked out	Returned when a valid username is supplied, but the account is locked out. Note that this error will be returned regardless of whether the password is invalid.

Authentication pipe example

Pipe is called with two parameters:

• username

• password

First the LDAP entry for the user is located using a search in "dc=example,dc=com" filtering on the uid attribute. The search result entries will be added as items to the current item set using entry DN as identifier (see LDAP Search).

Next step is bind examining the current item set to make sure it contains exactly one item. If not; pipe and authentication will fail. If item set is empty, the user does not exist (i.e. incorrect username is supplied). If the item set contains more than one item the search is too wide and base_dn and/or filter need to be more specific.

If current item set is valid, a bind will be performed using the expanded values for dn and password. If bind fails pipe will fail. If bind is successful the item (including specified attributes) is returned.

{
  "id" : "auth01",
  "config" : {
    "valves" : [ 
      {
        "name" : "LDAPSearch",
        "config" : {
          "destination" : "default",
          "base_dn" : "dc=example,dc=com",
          "scope" : "SUB",
          "filter" : "uid=${request.username}",
          "attributes" : [ {
            "name" : "uid",
            "multivalue" : false
          }, {
            "name" : "cn",
            "multivalue" : false
          }, {
            "name" : "mail",
            "multivalue" : true
          } ]
        }
      }, 
      {
        "name" : "LDAPBind",
        "config" : {
          "destination" : "default",
          "dn" : "${item.id}",
          "password" : "${request.password}"
        }
      }
    ]
  }
}