codekingpro/portable-devtools

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>21.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="21.9. Peer Authentication" /><link rel="next" href="auth-radius.html" title="21.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">21.10. LDAP Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-peer.html" title="21.9. Peer Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-radius.html" title="21.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">21.10. LDAP Authentication <a href="#AUTH-LDAP" class="id_link">#</a></h2></div></div></div><a id="id-1.6.8.17.2" class="indexterm"></a><p>3    This authentication method operates similarly to4    <code class="literal">password</code> except that it uses LDAP5    as the password verification method. LDAP is used only to validate6    the user name/password pairs. Therefore the user must already7    exist in the database before LDAP can be used for8    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 as13    <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 specify15    <code class="literal">cn=</code>, or <em class="replaceable"><code>DOMAIN</code></em><code class="literal">\</code> in an Active16    Directory environment.  <em class="replaceable"><code>suffix</code></em> is used to specify the17    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 with21    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 trying23    to log in to the database. If no user and password is configured, an24    anonymous bind will be attempted to the directory. The search will be25    performed over the subtree at <em class="replaceable"><code>ldapbasedn</code></em>, and will try to26    do an exact match of the attribute specified in27    <em class="replaceable"><code>ldapsearchattribute</code></em>.28    Once the user has been found in29    this search, the server disconnects and re-binds to the directory as30    this user, using the password specified by the client, to verify that the31    login is correct. This mode is the same as that used by LDAP authentication32    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 flexibility34    in where the user objects are located in the directory, but will cause35    two separate connections 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. Multiple40        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-standard46        way of using LDAP over SSL, supported by some LDAP server47        implementations.  See also the <code class="literal">ldaptls</code> option for48        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 server51        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> or57    <code class="literal">ldaptls</code> only encrypts the traffic between the58    PostgreSQL server and the LDAP server.  The connection between the59    PostgreSQL server and the PostgreSQL client will still be unencrypted60    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+bind74        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 when77        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 search80        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 doing83         search+bind authentication.  If no attribute is specified, the84         <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 the88         user name.  This allows for more flexible search filters than89         <code class="literal">ldapsearchattribute</code>.90        </p></dd><dt><span class="term"><code class="literal">ldapurl</code></span></dt><dd><p>91         An <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc4516" target="_top">RFC 4516</a>92         LDAP URL.  This is an alternative way to write some of the93         other LDAP options in a more compact and standard form.  The format is94</p><pre class="synopsis">95ldap[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>]]]]96</pre><p>97         <em class="replaceable"><code>scope</code></em> must be one98         of <code class="literal">base</code>, <code class="literal">one</code>, <code class="literal">sub</code>,99         typically the last.  (The default is <code class="literal">base</code>, which100         is normally not useful in this application.)  <em class="replaceable"><code>attribute</code></em> can101         nominate a single attribute, in which case it is used as a value for102         <code class="literal">ldapsearchattribute</code>.  If103         <em class="replaceable"><code>attribute</code></em> is empty then104         <em class="replaceable"><code>filter</code></em> can be used as a value for105         <code class="literal">ldapsearchfilter</code>.106        </p><p>107         The URL scheme <code class="literal">ldaps</code> chooses the LDAPS method for108         making LDAP connections over SSL, equivalent to using109         <code class="literal">ldapscheme=ldaps</code>.  To use encrypted LDAP110         connections using the <code class="literal">StartTLS</code> operation, use the111         normal URL scheme <code class="literal">ldap</code> and specify the112         <code class="literal">ldaptls</code> option in addition to113         <code class="literal">ldapurl</code>.114        </p><p>115         For non-anonymous binds, <code class="literal">ldapbinddn</code>116         and <code class="literal">ldapbindpasswd</code> must be specified as separate117         options.118        </p><p>119         LDAP URLs are currently only supported with120         <span class="productname">OpenLDAP</span>, not on Windows.121        </p></dd></dl></div><p>122   </p><p>123    It is an error to mix configuration options for simple bind with options124    for search+bind.125   </p><p>126    When using search+bind mode, the search can be performed using a single127    attribute specified with <code class="literal">ldapsearchattribute</code>, or using128    a custom search filter specified with129    <code class="literal">ldapsearchfilter</code>.130    Specifying <code class="literal">ldapsearchattribute=foo</code> is equivalent to131    specifying <code class="literal">ldapsearchfilter="(foo=$username)"</code>.  If neither132    option is specified the default is133    <code class="literal">ldapsearchattribute=uid</code>.134   </p><p>135     If <span class="productname">PostgreSQL</span> was compiled with136     <span class="productname">OpenLDAP</span> as the LDAP client library, the137     <code class="literal">ldapserver</code> setting may be omitted.  In that case, a138     list of host names and ports is looked up via139     <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc2782" target="_top">RFC 2782</a> DNS SRV records.140     The name <code class="literal">_ldap._tcp.DOMAIN</code> is looked up, where141     <code class="literal">DOMAIN</code> is extracted from <code class="literal">ldapbasedn</code>.142   </p><p>143    Here is an example for a simple-bind LDAP configuration:144</p><pre class="programlisting">145host ... ldap ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net"146</pre><p>147    When a connection to the database server as database148    user <code class="literal">someuser</code> is requested, PostgreSQL will attempt to149    bind to the LDAP server using the DN <code class="literal">cn=someuser, dc=example,150    dc=net</code> and the password provided by the client.  If that connection151    succeeds, the database access is granted.152   </p><p>153    Here is an example for a search+bind configuration:154</p><pre class="programlisting">155host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchattribute=uid156</pre><p>157    When a connection to the database server as database158    user <code class="literal">someuser</code> is requested, PostgreSQL will attempt to159    bind anonymously (since <code class="literal">ldapbinddn</code> was not specified) to160    the LDAP server, perform a search for <code class="literal">(uid=someuser)</code>161    under the specified base DN.  If an entry is found, it will then attempt to162    bind using that found information and the password supplied by the client.163    If that second connection succeeds, the database access is granted.164   </p><p>165    Here is the same search+bind configuration written as a URL:166</p><pre class="programlisting">167host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub"168</pre><p>169    Some other software that supports authentication against LDAP uses the170    same URL format, so it will be easier to share the configuration.171   </p><p>172    Here is an example for a search+bind configuration that uses173    <code class="literal">ldapsearchfilter</code> instead of174    <code class="literal">ldapsearchattribute</code> to allow authentication by175    user ID or email address:176</p><pre class="programlisting">177host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchfilter="(|(uid=$username)(mail=$username))"178</pre><p>179   </p><p>180    Here is an example for a search+bind configuration that uses DNS SRV181    discovery to find the host name(s) and port(s) for the LDAP service for the182    domain name <code class="literal">example.net</code>:183</p><pre class="programlisting">184host ... ldap ldapbasedn="dc=example,dc=net"185</pre><p>186   </p><div class="tip"><h3 class="title">Tip</h3><p>187     Since LDAP often uses commas and spaces to separate the different188     parts of a DN, it is often necessary to use double-quoted parameter189     values when configuring LDAP options, as shown in the examples.190    </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="21.9. Peer Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-radius.html" title="21.11. RADIUS Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.9. Peer Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.11. RADIUS Authentication</td></tr></table></div></body></html>