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

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.10. LDAP Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-peer.html" title="20.9. Peer Authentication" /><link rel="next" href="auth-radius.html" title="20.11. RADIUS Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.10. LDAP Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-peer.html" title="20.9. Peer Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 20. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 20. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-radius.html" title="20.11. RADIUS Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-LDAP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.10. LDAP Authentication <a href="#AUTH-LDAP" class="id_link">#</a></h2></div></div></div><a id="id-1.6.7.17.2" class="indexterm"></a><p>
   3     This authentication method operates similarly to
   4     <code class="literal">password</code> except that it uses LDAP
   5     as the password verification method. LDAP is used only to validate
   6     the user name/password pairs. Therefore the user must already
   7     exist in the database before LDAP can be used for
   8     authentication.
   9    </p><p>
  10     LDAP authentication can operate in two modes. In the first mode,
  11     which we will call the simple bind mode,
  12     the server will bind to the distinguished name constructed as
  13     <em class="replaceable"><code>prefix</code></em> <em class="replaceable"><code>username</code></em> <em class="replaceable"><code>suffix</code></em>.
  14     Typically, the <em class="replaceable"><code>prefix</code></em> parameter is used to specify
  15     <code class="literal">cn=</code>, or <em class="replaceable"><code>DOMAIN</code></em><code class="literal">\</code> in an Active
  16     Directory environment.  <em class="replaceable"><code>suffix</code></em> is used to specify the
  17     remaining part of the DN in a non-Active Directory environment.
  18    </p><p>
  19     In the second mode, which we will call the search+bind mode,
  20     the server first binds to the LDAP directory with
  21     a fixed user name and password, specified with <em class="replaceable"><code>ldapbinddn</code></em>
  22     and <em class="replaceable"><code>ldapbindpasswd</code></em>, and performs a search for the user trying
  23     to log in to the database. If no user and password is configured, an
  24     anonymous bind will be attempted to the directory. The search will be
  25     performed over the subtree at <em class="replaceable"><code>ldapbasedn</code></em>, and will try to
  26     do an exact match of the attribute specified in
  27     <em class="replaceable"><code>ldapsearchattribute</code></em>.
  28     Once the user has been found in
  29     this search, the server re-binds to the directory as
  30     this user, using the password specified by the client, to verify that the
  31     login is correct. This mode is the same as that used by LDAP authentication
  32     schemes in other software, such as Apache <code class="literal">mod_authnz_ldap</code> and <code class="literal">pam_ldap</code>.
  33     This method allows for significantly more flexibility
  34     in where the user objects are located in the directory, but will cause
  35     two additional requests to the LDAP server to be made.
  36    </p><p>
  37     The following configuration options are used in both modes:
  38     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ldapserver</code></span></dt><dd><p>
  39         Names or IP addresses of LDAP servers to connect to. Multiple
  40         servers may be specified, separated by spaces.
  41        </p></dd><dt><span class="term"><code class="literal">ldapport</code></span></dt><dd><p>
  42         Port number on LDAP server to connect to. If no port is specified,
  43         the LDAP library's default port setting will be used.
  44        </p></dd><dt><span class="term"><code class="literal">ldapscheme</code></span></dt><dd><p>
  45         Set to <code class="literal">ldaps</code> to use LDAPS.  This is a non-standard
  46         way of using LDAP over SSL, supported by some LDAP server
  47         implementations.  See also the <code class="literal">ldaptls</code> option for
  48         an alternative.
  49        </p></dd><dt><span class="term"><code class="literal">ldaptls</code></span></dt><dd><p>
  50         Set to 1 to make the connection between PostgreSQL and the LDAP server
  51         use TLS encryption.  This uses the <code class="literal">StartTLS</code>
  52         operation per <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc4513" target="_top">RFC 4513</a>.
  53         See also the <code class="literal">ldapscheme</code> option for an alternative.
  54        </p></dd></dl></div><p>
  55    </p><p>
  56     Note that using <code class="literal">ldapscheme</code> or
  57     <code class="literal">ldaptls</code> only encrypts the traffic between the
  58     PostgreSQL server and the LDAP server.  The connection between the
  59     PostgreSQL server and the PostgreSQL client will still be unencrypted
  60     unless SSL is used there as well.
  61    </p><p>
  62     The following options are used in simple bind mode only:
  63     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ldapprefix</code></span></dt><dd><p>
  64         String to prepend to the user name when forming the DN to bind as,
  65         when doing simple bind authentication.
  66        </p></dd><dt><span class="term"><code class="literal">ldapsuffix</code></span></dt><dd><p>
  67         String to append to the user name when forming the DN to bind as,
  68         when doing simple bind authentication.
  69        </p></dd></dl></div><p>
  70    </p><p>
  71     The following options are used in search+bind mode only:
  72     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ldapbasedn</code></span></dt><dd><p>
  73         Root DN to begin the search for the user in, when doing search+bind
  74         authentication.
  75        </p></dd><dt><span class="term"><code class="literal">ldapbinddn</code></span></dt><dd><p>
  76         DN of user to bind to the directory with to perform the search when
  77         doing search+bind authentication.
  78        </p></dd><dt><span class="term"><code class="literal">ldapbindpasswd</code></span></dt><dd><p>
  79         Password for user to bind to the directory with to perform the search
  80         when doing search+bind authentication.
  81        </p></dd><dt><span class="term"><code class="literal">ldapsearchattribute</code></span></dt><dd><p>
  82          Attribute to match against the user name in the search when doing
  83          search+bind authentication.  If no attribute is specified, the
  84          <code class="literal">uid</code> attribute will be used.
  85         </p></dd><dt><span class="term"><code class="literal">ldapsearchfilter</code></span></dt><dd><p>
  86          The search filter to use when doing search+bind authentication.
  87          Occurrences of <code class="literal">$username</code> will be replaced with the
  88          user name.  This allows for more flexible search filters than
  89          <code class="literal">ldapsearchattribute</code>.
  90         </p></dd></dl></div><p>
  91     </p><p>
  92      The following option may be used as an alternative way to write some of the
  93      above LDAP options in a more compact and standard form:
  94      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ldapurl</code></span></dt><dd><p>
  95          An <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc4516" target="_top">RFC 4516</a>
  96          LDAP URL.  The format is
  97 </p><pre class="synopsis">
  98 ldap[s]://<em class="replaceable"><code>host</code></em>[:<em class="replaceable"><code>port</code></em>]/<em class="replaceable"><code>basedn</code></em>[?[<em class="replaceable"><code>attribute</code></em>][?[<em class="replaceable"><code>scope</code></em>][?[<em class="replaceable"><code>filter</code></em>]]]]
  99 </pre><p>
 100          <em class="replaceable"><code>scope</code></em> must be one
 101          of <code class="literal">base</code>, <code class="literal">one</code>, <code class="literal">sub</code>,
 102          typically the last.  (The default is <code class="literal">base</code>, which
 103          is normally not useful in this application.)  <em class="replaceable"><code>attribute</code></em> can
 104          nominate a single attribute, in which case it is used as a value for
 105          <code class="literal">ldapsearchattribute</code>.  If
 106          <em class="replaceable"><code>attribute</code></em> is empty then
 107          <em class="replaceable"><code>filter</code></em> can be used as a value for
 108          <code class="literal">ldapsearchfilter</code>.
 109         </p><p>
 110          The URL scheme <code class="literal">ldaps</code> chooses the LDAPS method for
 111          making LDAP connections over SSL, equivalent to using
 112          <code class="literal">ldapscheme=ldaps</code>.  To use encrypted LDAP
 113          connections using the <code class="literal">StartTLS</code> operation, use the
 114          normal URL scheme <code class="literal">ldap</code> and specify the
 115          <code class="literal">ldaptls</code> option in addition to
 116          <code class="literal">ldapurl</code>.
 117         </p><p>
 118          For non-anonymous binds, <code class="literal">ldapbinddn</code>
 119          and <code class="literal">ldapbindpasswd</code> must be specified as separate
 120          options.
 121         </p><p>
 122          LDAP URLs are currently only supported with
 123          <span class="productname">OpenLDAP</span>, not on Windows.
 124         </p></dd></dl></div><p>
 125    </p><p>
 126     It is an error to mix configuration options for simple bind with options
 127     for search+bind.  To use <code class="literal">ldapurl</code> in simple bind mode, the
 128     URL must not contain a <code class="literal">basedn</code> or query elements.
 129    </p><p>
 130     When using search+bind mode, the search can be performed using a single
 131     attribute specified with <code class="literal">ldapsearchattribute</code>, or using
 132     a custom search filter specified with
 133     <code class="literal">ldapsearchfilter</code>.
 134     Specifying <code class="literal">ldapsearchattribute=foo</code> is equivalent to
 135     specifying <code class="literal">ldapsearchfilter="(foo=$username)"</code>.  If neither
 136     option is specified the default is
 137     <code class="literal">ldapsearchattribute=uid</code>.
 138    </p><p>
 139      If <span class="productname">PostgreSQL</span> was compiled with
 140      <span class="productname">OpenLDAP</span> as the LDAP client library, the
 141      <code class="literal">ldapserver</code> setting may be omitted.  In that case, a
 142      list of host names and ports is looked up via
 143      <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc2782" target="_top">RFC 2782</a> DNS SRV records.
 144      The name <code class="literal">_ldap._tcp.DOMAIN</code> is looked up, where
 145      <code class="literal">DOMAIN</code> is extracted from <code class="literal">ldapbasedn</code>.
 146    </p><p>
 147     Here is an example for a simple-bind LDAP configuration:
 148 </p><pre class="programlisting">
 149 host ... ldap ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net"
 150 </pre><p>
 151     When a connection to the database server as database
 152     user <code class="literal">someuser</code> is requested, PostgreSQL will attempt to
 153     bind to the LDAP server using the DN <code class="literal">cn=someuser, dc=example,
 154     dc=net</code> and the password provided by the client.  If that connection
 155     succeeds, the database access is granted.
 156    </p><p>
 157     Here is a different simple-bind configuration, which uses the LDAPS scheme
 158     and a custom port number, written as a URL:
 159 </p><pre class="programlisting">
 160 host ... ldap ldapurl="ldaps://ldap.example.net:49151" ldapprefix="cn=" ldapsuffix=", dc=example, dc=net"
 161 </pre><p>
 162     This is slightly more compact than specifying <code class="literal">ldapserver</code>,
 163     <code class="literal">ldapscheme</code>, and <code class="literal">ldapport</code> separately.
 164    </p><p>
 165     Here is an example for a search+bind configuration:
 166 </p><pre class="programlisting">
 167 host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchattribute=uid
 168 </pre><p>
 169     When a connection to the database server as database
 170     user <code class="literal">someuser</code> is requested, PostgreSQL will attempt to
 171     bind anonymously (since <code class="literal">ldapbinddn</code> was not specified) to
 172     the LDAP server, perform a search for <code class="literal">(uid=someuser)</code>
 173     under the specified base DN.  If an entry is found, it will then attempt to
 174     bind using that found information and the password supplied by the client.
 175     If that second bind succeeds, the database access is granted.
 176    </p><p>
 177     Here is the same search+bind configuration written as a URL:
 178 </p><pre class="programlisting">
 179 host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub"
 180 </pre><p>
 181     Some other software that supports authentication against LDAP uses the
 182     same URL format, so it will be easier to share the configuration.
 183    </p><p>
 184     Here is an example for a search+bind configuration that uses
 185     <code class="literal">ldapsearchfilter</code> instead of
 186     <code class="literal">ldapsearchattribute</code> to allow authentication by
 187     user ID or email address:
 188 </p><pre class="programlisting">
 189 host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchfilter="(|(uid=$username)(mail=$username))"
 190 </pre><p>
 191    </p><p>
 192     Here is an example for a search+bind configuration that uses DNS SRV
 193     discovery to find the host name(s) and port(s) for the LDAP service for the
 194     domain name <code class="literal">example.net</code>:
 195 </p><pre class="programlisting">
 196 host ... ldap ldapbasedn="dc=example,dc=net"
 197 </pre><p>
 198    </p><div class="tip"><h3 class="title">Tip</h3><p>
 199      Since LDAP often uses commas and spaces to separate the different
 200      parts of a DN, it is often necessary to use double-quoted parameter
 201      values when configuring LDAP options, as shown in the examples.
 202     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-peer.html" title="20.9. Peer Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 20. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-radius.html" title="20.11. RADIUS Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.9. Peer Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.11. RADIUS Authentication</td></tr></table></div></body></html>