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