begriffs open source - ai-pg/blob - full-docs/txt/auth-ldap.txt

   1
   2 20.10. LDAP Authentication #
   3
   4    This authentication method operates similarly to password except that
   5    it uses LDAP as the password verification method. LDAP is used only to
   6    validate the user name/password pairs. Therefore the user must already
   7    exist in the database before LDAP can be used for authentication.
   8
   9    LDAP authentication can operate in two modes. In the first mode, which
  10    we will call the simple bind mode, the server will bind to the
  11    distinguished name constructed as prefix username suffix. Typically,
  12    the prefix parameter is used to specify cn=, or DOMAIN\ in an Active
  13    Directory environment. suffix is used to specify the remaining part of
  14    the DN in a non-Active Directory environment.
  15
  16    In the second mode, which we will call the search+bind mode, the server
  17    first binds to the LDAP directory with a fixed user name and password,
  18    specified with ldapbinddn and ldapbindpasswd, and performs a search for
  19    the user trying to log in to the database. If no user and password is
  20    configured, an anonymous bind will be attempted to the directory. The
  21    search will be performed over the subtree at ldapbasedn, and will try
  22    to do an exact match of the attribute specified in ldapsearchattribute.
  23    Once the user has been found in this search, the server re-binds to the
  24    directory as this user, using the password specified by the client, to
  25    verify that the login is correct. This mode is the same as that used by
  26    LDAP authentication schemes in other software, such as Apache
  27    mod_authnz_ldap and pam_ldap. This method allows for significantly more
  28    flexibility in where the user objects are located in the directory, but
  29    will cause two additional requests to the LDAP server to be made.
  30
  31    The following configuration options are used in both modes:
  32
  33    ldapserver
  34           Names or IP addresses of LDAP servers to connect to. Multiple
  35           servers may be specified, separated by spaces.
  36
  37    ldapport
  38           Port number on LDAP server to connect to. If no port is
  39           specified, the LDAP library's default port setting will be used.
  40
  41    ldapscheme
  42           Set to ldaps to use LDAPS. This is a non-standard way of using
  43           LDAP over SSL, supported by some LDAP server implementations.
  44           See also the ldaptls option for an alternative.
  45
  46    ldaptls
  47           Set to 1 to make the connection between PostgreSQL and the LDAP
  48           server use TLS encryption. This uses the StartTLS operation per
  49           RFC 4513. See also the ldapscheme option for an alternative.
  50
  51    Note that using ldapscheme or ldaptls only encrypts the traffic between
  52    the PostgreSQL server and the LDAP server. The connection between the
  53    PostgreSQL server and the PostgreSQL client will still be unencrypted
  54    unless SSL is used there as well.
  55
  56    The following options are used in simple bind mode only:
  57
  58    ldapprefix
  59           String to prepend to the user name when forming the DN to bind
  60           as, when doing simple bind authentication.
  61
  62    ldapsuffix
  63           String to append to the user name when forming the DN to bind
  64           as, when doing simple bind authentication.
  65
  66    The following options are used in search+bind mode only:
  67
  68    ldapbasedn
  69           Root DN to begin the search for the user in, when doing
  70           search+bind authentication.
  71
  72    ldapbinddn
  73           DN of user to bind to the directory with to perform the search
  74           when doing search+bind authentication.
  75
  76    ldapbindpasswd
  77           Password for user to bind to the directory with to perform the
  78           search when doing search+bind authentication.
  79
  80    ldapsearchattribute
  81           Attribute to match against the user name in the search when
  82           doing search+bind authentication. If no attribute is specified,
  83           the uid attribute will be used.
  84
  85    ldapsearchfilter
  86           The search filter to use when doing search+bind authentication.
  87           Occurrences of $username will be replaced with the user name.
  88           This allows for more flexible search filters than
  89           ldapsearchattribute.
  90
  91    The following option may be used as an alternative way to write some of
  92    the above LDAP options in a more compact and standard form:
  93
  94    ldapurl
  95           An RFC 4516 LDAP URL. The format is
  96
  97 ldap[s]://host[:port]/basedn[?[attribute][?[scope][?[filter]]]]
  98
  99           scope must be one of base, one, sub, typically the last. (The
 100           default is base, which is normally not useful in this
 101           application.) attribute can nominate a single attribute, in
 102           which case it is used as a value for ldapsearchattribute. If
 103           attribute is empty then filter can be used as a value for
 104           ldapsearchfilter.
 105
 106           The URL scheme ldaps chooses the LDAPS method for making LDAP
 107           connections over SSL, equivalent to using ldapscheme=ldaps. To
 108           use encrypted LDAP connections using the StartTLS operation, use
 109           the normal URL scheme ldap and specify the ldaptls option in
 110           addition to ldapurl.
 111
 112           For non-anonymous binds, ldapbinddn and ldapbindpasswd must be
 113           specified as separate options.
 114
 115           LDAP URLs are currently only supported with OpenLDAP, not on
 116           Windows.
 117
 118    It is an error to mix configuration options for simple bind with
 119    options for search+bind. To use ldapurl in simple bind mode, the URL
 120    must not contain a basedn or query elements.
 121
 122    When using search+bind mode, the search can be performed using a single
 123    attribute specified with ldapsearchattribute, or using a custom search
 124    filter specified with ldapsearchfilter. Specifying
 125    ldapsearchattribute=foo is equivalent to specifying
 126    ldapsearchfilter="(foo=$username)". If neither option is specified the
 127    default is ldapsearchattribute=uid.
 128
 129    If PostgreSQL was compiled with OpenLDAP as the LDAP client library,
 130    the ldapserver setting may be omitted. In that case, a list of host
 131    names and ports is looked up via RFC 2782 DNS SRV records. The name
 132    _ldap._tcp.DOMAIN is looked up, where DOMAIN is extracted from
 133    ldapbasedn.
 134
 135    Here is an example for a simple-bind LDAP configuration:
 136 host ... ldap ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=exam
 137 ple, dc=net"
 138
 139    When a connection to the database server as database user someuser is
 140    requested, PostgreSQL will attempt to bind to the LDAP server using the
 141    DN cn=someuser, dc=example, dc=net and the password provided by the
 142    client. If that connection succeeds, the database access is granted.
 143
 144    Here is a different simple-bind configuration, which uses the LDAPS
 145    scheme and a custom port number, written as a URL:
 146 host ... ldap ldapurl="ldaps://ldap.example.net:49151" ldapprefix="cn=" ldapsuff
 147 ix=", dc=example, dc=net"
 148
 149    This is slightly more compact than specifying ldapserver, ldapscheme,
 150    and ldapport separately.
 151
 152    Here is an example for a search+bind configuration:
 153 host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapse
 154 archattribute=uid
 155
 156    When a connection to the database server as database user someuser is
 157    requested, PostgreSQL will attempt to bind anonymously (since
 158    ldapbinddn was not specified) to the LDAP server, perform a search for
 159    (uid=someuser) under the specified base DN. If an entry is found, it
 160    will then attempt to bind using that found information and the password
 161    supplied by the client. If that second bind succeeds, the database
 162    access is granted.
 163
 164    Here is the same search+bind configuration written as a URL:
 165 host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub"
 166
 167    Some other software that supports authentication against LDAP uses the
 168    same URL format, so it will be easier to share the configuration.
 169
 170    Here is an example for a search+bind configuration that uses
 171    ldapsearchfilter instead of ldapsearchattribute to allow authentication
 172    by user ID or email address:
 173 host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapse
 174 archfilter="(|(uid=$username)(mail=$username))"
 175
 176    Here is an example for a search+bind configuration that uses DNS SRV
 177    discovery to find the host name(s) and port(s) for the LDAP service for
 178    the domain name example.net:
 179 host ... ldap ldapbasedn="dc=example,dc=net"
 180
 181 Tip
 182
 183    Since LDAP often uses commas and spaces to separate the different parts
 184    of a DN, it is often necessary to use double-quoted parameter values
 185    when configuring LDAP options, as shown in the examples.