]>
Commit | Line | Data |
---|---|---|
428744a1 | 1 | .TH basic_ldap_auth 8 "14 January 2005" "Squid LDAP Auth" |
b3def772 | 2 | . |
cfca18fc | 3 | .SH NAME |
428744a1 | 4 | basic_ldap_auth - LDAP authentication helper for Squid |
b3def772 | 5 | . |
cfca18fc | 6 | .SH SYNOPSIS |
428744a1 | 7 | .B basic_ldap_auth |
b627c18a | 8 | -b "base DN" [-u attribute] [options] [ldap_server_name[:port]|URI]... |
9 | .br | |
428744a1 | 10 | .B basic_ldap_auth |
b627c18a | 11 | -b "base DN" -f "LDAP search filter" [options] [ldap_server_name[:port]|URI]... |
b3def772 | 12 | . |
cfca18fc | 13 | .SH DESCRIPTION |
14 | This helper allows Squid to connect to a LDAP directory to | |
15 | validate the user name and password of Basic HTTP authentication. | |
076d1037 | 16 | LDAP options are specified as parameters on the command line, |
17 | while the username(s) and password(s) to be checked against the | |
18 | LDAP directory are specified on subsequent lines of input to the | |
19 | helper, one username/password pair per line separated by a space. | |
20 | .P | |
21 | As expected by the basic authentication construct of Squid, after | |
22 | specifying a username and password followed by a new line, this | |
23 | helper will produce either OK or ERR on the following line | |
24 | to show if the specified credentials are correct according to | |
25 | the LDAP directory. | |
b3def772 | 26 | .P |
27 | The program has two major modes of operation. In the default mode | |
28 | of operation the users DN is constructed using the base DN and | |
29 | user attribute. In the other mode of operation a search | |
30 | filter is used to locate valid user DN's below the base DN. | |
31 | . | |
428744a1 AJ |
32 | .SH OPTIONS |
33 | . | |
cfca18fc | 34 | .TP |
35 | .BI "-b " "basedn " (REQUIRED) | |
36 | Specifies the base DN under which the users are located. | |
b3def772 | 37 | . |
cfca18fc | 38 | .TP |
39 | .BI "-f " filter | |
2fd77e91 | 40 | LDAP search filter to locate the user DN. Required if the users |
41 | are in a hierarchy below the base DN, or if the login name is | |
42 | not what builds the user specific part of the users DN. | |
cfca18fc | 43 | .IP |
2fd77e91 | 44 | The search filter can contain up to 15 occurrences of %s |
cfca18fc | 45 | which will be replaced by the username, as in "uid=%s" for |
b3def772 | 46 | RFC2037 directories. For a detailed description of LDAP search |
47 | filter syntax see RFC2254. | |
48 | . | |
cfca18fc | 49 | .TP |
50 | .BI "-u " userattr | |
b3def772 | 51 | Specifies the name of the DN attribute that contains the username/login. |
52 | Combined with the base DN to construct the users DN when no search filter | |
53 | is specified (-f option). Defaults to 'uid' | |
cfca18fc | 54 | .IP |
b3def772 | 55 | Note: This can only be done if all your users are located directly under |
56 | the same position in the LDAP tree and the login name is used for naming | |
57 | each user object. If your LDAP tree does not match these criterias or if | |
58 | you want to filter who are valid users then you need to use a search filter | |
59 | to search for your users DN (-f option). | |
60 | . | |
cfca18fc | 61 | .TP |
b627c18a | 62 | .BI "-U " passwordattr |
63 | Use ldap_compare instead of ldap_simple_bind to verify the users password. | |
64 | passwordattr is the LDAP attribute storing the users password. | |
65 | . | |
66 | .TP | |
cfca18fc | 67 | .BI "-s " base|one|sub |
68 | search scope when performing user DN searches specified | |
b3def772 | 69 | by the -f option. Defaults to 'sub'. |
cfca18fc | 70 | .IP |
71 | .B base | |
72 | object only, | |
73 | .B one | |
74 | level below the base object or | |
75 | .BR sub tree | |
76 | below the base object | |
77 | . | |
78 | .TP | |
79 | .BI "-D " "binddn " "-w " password | |
80 | The DN and password to bind as while performing searches. Required by the | |
81 | .BI -f | |
82 | flag if the directory does not allow anonymous searches. | |
83 | .IP | |
84 | As the password needs to be printed in plain text in your Squid configuration | |
2fd77e91 | 85 | it is strongly recommended to use a account with minimal associated privileges. |
cfca18fc | 86 | This to limit the damage in case someone could get hold of a copy of your |
87 | Squid configuration file. | |
b3def772 | 88 | . |
cfca18fc | 89 | .TP |
954a8513 | 90 | .BI "-D " "binddn " "-W " "secretfile " |
91 | The DN and the name of a file containing the password | |
92 | to bind as while performing searches. | |
93 | .IP | |
94 | Less insecure version of the former parameter pair with two advantages: | |
95 | The password does not occur in the process listing, | |
96 | and the password is not being compromised if someone gets the squid | |
97 | configuration file without getting the secretfile. | |
98 | . | |
99 | .TP | |
70c46401 | 100 | .BI -P |
cfca18fc | 101 | Use a persistent LDAP connection. Normally the LDAP connection |
102 | is only open while validating a username to preserve resources | |
103 | at the LDAP server. This option causes the LDAP connection to | |
104 | be kept open, allowing it to be reused for further user | |
105 | validations. Recommended for larger installations. | |
b3def772 | 106 | . |
cfca18fc | 107 | .TP |
b627c18a | 108 | .BI -O |
109 | Only bind once per LDAP connection. Some LDAP servers do not | |
110 | allow re-binding as another user after a successful ldap_bind. | |
111 | The use of this option always opens a new connection for each | |
112 | login attempt. If combined with the -P option for persistent | |
113 | LDAP connection then the connection used for searching for the | |
114 | user DN is kept persistent but a new connection is opened | |
115 | to verify each users password once the DN is found. | |
116 | . | |
117 | .TP | |
cfca18fc | 118 | .BI -R |
119 | do not follow referrals | |
b3def772 | 120 | . |
cfca18fc | 121 | .TP |
122 | .BI "-a " never|always|search|find | |
b3def772 | 123 | when to dereference aliases. Defaults to 'never' |
cfca18fc | 124 | .IP |
125 | .BI never | |
126 | dereference aliases (default), | |
127 | .BI always | |
128 | dereference aliases, only while | |
129 | .BR search ing | |
130 | or only to | |
131 | .B find | |
132 | the base object | |
b3def772 | 133 | . |
70c46401 | 134 | .TP |
7ba68818 | 135 | .BI -H " ldapuri" |
b627c18a | 136 | Specity the LDAP server to connect to by LDAP URI (requires OpenLDAP libraries). |
137 | Servers can also be specified last on the command line. | |
7ba68818 | 138 | . |
139 | .TP | |
20b6fc8e | 140 | .BI -h " ldapserver" |
b627c18a | 141 | Specify the LDAP server to connect to. Servers can also be specified last |
142 | on the command line. | |
20b6fc8e | 143 | .TP |
70c46401 | 144 | .BI -p " ldapport" |
b3def772 | 145 | Specify an alternate TCP port where the ldap server is listening if |
b627c18a | 146 | other than the default LDAP port 389. Can also be specified within the |
147 | server specificiation by using servername:port syntax. | |
cfca18fc | 148 | . |
653b264e | 149 | .TP |
076d1037 | 150 | .BI -v " 2|3" |
151 | LDAP protocol version. Defaults to 2 if not specified. | |
152 | . | |
153 | .TP | |
653b264e | 154 | .BI -Z |
155 | Use TLS encryption | |
156 | . | |
157 | .TP | |
158 | .BI -S certpath | |
159 | Enable LDAP over SSL (requires Netscape LDAP API libraries) | |
160 | . | |
161 | .TP | |
162 | .BI -c connect_timeout | |
163 | Specify timeout used when connecting to LDAP servers (requires | |
164 | Netscape LDAP API libraries) | |
165 | .TP | |
166 | .BI -t search_timeout | |
167 | Specify time limit on LDAP search operations | |
168 | . | |
307228f1 | 169 | .TP |
b627c18a | 170 | .BI -d |
307228f1 | 171 | Debug mode where each step taken will get reported in detail. |
172 | Useful for understanding what goes wrong if the results is | |
173 | not what is expected. | |
174 | . | |
cfca18fc | 175 | .SH EXAMPLES |
176 | For directories using the RFC2307 layout with a single domain, all | |
177 | you need to specify is usually the base DN under where your users | |
b3def772 | 178 | are located and the server name: |
cfca18fc | 179 | .IP |
428744a1 | 180 | basic_ldap_auth -b "ou=people,dc=your,dc=domain" ldapserver |
cfca18fc | 181 | .P |
b3def772 | 182 | If you have sub-domains then you need to use a search filter approach |
183 | to locate your user DNs as these can no longer be constructed direcly | |
184 | from the base DN and login name alone: | |
cfca18fc | 185 | .IP |
428744a1 | 186 | basic_ldap_auth -b "dc=your,dc=domain" -f "uid=%s" ldapserver |
cfca18fc | 187 | .P |
b3def772 | 188 | And similarily if you only want to allow access to users having a |
189 | specific attribute | |
190 | .IP | |
428744a1 | 191 | basic_ldap_auth -b "dc=your,dc=domain" -f "(&(uid=%s)(specialattribute=value))" ldapserver |
b3def772 | 192 | .P |
2fd77e91 | 193 | Or if the user attribute of the user DN is "cn" instead of "uid" and |
194 | you do not want to have to search for the users then you could use something | |
195 | like the following example for Active Directory: | |
cfca18fc | 196 | .IP |
428744a1 | 197 | basic_ldap_auth -u cn -b "cn=Users,dc=your,dc=domain" ldapserver |
cfca18fc | 198 | .P |
2fd77e91 | 199 | If you want to search for the user DN and your directory does not allow |
200 | anonymous searches then you must also use the -D and -w flags to specify | |
201 | a user DN and password to log in as to perform the searches, as in the | |
202 | following complex Active Directory example | |
cfca18fc | 203 | .IP |
428744a1 | 204 | basic_ldap_auth -P -R -b "dc=your,dc=domain" -D "cn=squid,cn=users,dc=your,dc=domain" -w "secretsquidpassword" -f "(&(userPrincipalName=%s)(objectClass=Person))" activedirectoryserver |
b3def772 | 205 | . |
206 | .SH NOTES | |
207 | . | |
208 | When constructing search filters it is strongly recommended to test the filter | |
428744a1 | 209 | using ldapsearch before you attempt to use basic_ldap_auth. This to verify |
b3def772 | 210 | that the filter matches what you expect. |
cfca18fc | 211 | . |
212 | .SH AUTHOR | |
213 | This manual page was written by | |
214 | .I Henrik Nordstrom <hno@squid-cache.org> | |
215 | .P | |
428744a1 | 216 | basic_ldap_auth is written by |
cfca18fc | 217 | .I Glenn Newton <gnewton@wapiti.cisti.nrc.ca> |
218 | and | |
219 | .I Henrik Nordstrom <hno@squid-cache.org> | |
220 | . | |
221 | .SH KNOWN ISSUES | |
222 | Will crash if other % values than %s is used in -f, or if more than 15 %s | |
223 | is used. | |
224 | . | |
225 | .SH QUESTIONS | |
226 | Any questions on usage can be sent to | |
227 | .IR "Squid Users <squid-users@squid-cache.org>" , | |
b3def772 | 228 | or to your favorite LDAP list/friend if the question is more related to |
229 | LDAP than Squid. | |
cfca18fc | 230 | . |
231 | .SH REPORTING BUGS | |
232 | Report bugs or bug-fixes to | |
b3def772 | 233 | .I Squid Bugs <squid-bugs@squid-cache.org> |
234 | or ideas for new improvements to | |
cfca18fc | 235 | .I Squid Developers <squid-dev@squid-cache.org> |
b3def772 | 236 | . |
b3def772 | 237 | .SH "SEE ALSO" |
238 | .BR ldapsearch ( 1 ), | |
239 | .br | |
240 | Your favorite LDAP documentation | |
241 | .br | |
242 | .BR RFC2254 " - The String Representation of LDAP Search Filters," |