-
Notifications
You must be signed in to change notification settings - Fork 5
/
README
447 lines (303 loc) · 18.2 KB
/
README
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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
OpenID-LDAP-PHP
***************
An open source PHP-based OpenID IdP package using LDAP as backend.
By Zdravko Stoychev <zdravko (at) 5group (dot) com> aka Dako.
Copyright 1996-2011 by 5Group & Co. http://www.5group.com/
See LICENSE file for more details.
This work is based on CJ Niemira's phpMyID - A standalone, single user, OpenID
Identity Provider, version 0.8, home page: http://siege.org/projects/phpMyID.
OpenID-LDAP-PHP is a small, fairly lightweight, standalone, multi user Identity
Provider for OpenID authentication. It comprises a few PHP scripts that can be
used by one individual to run their own personal OpenID IdP.
This program requires no external libraries, and has very minimal requirements.
It should run on any PHP server (v4.2+), and can support OpenID in 'Smart Mode.'
This program caches all data using built-in PHP session handling, so it requires
no database, and no explicit write access to the file system.
OpenID-LDAP-PHP is NOT compatible with Suhosin or other hardened PHP systems
(Debian users take note).
NOTE: User authentication is done using HTTP Basic authentication, so your
password is transmitted over the wire in plain text, base64 encoded. Thus
we STRONGLY RECOMMEND using SSL for your hosting (https://yourdomain.com)
In fact, if you are not using SSL the Authorization OpenID mode *will*
fail with an error message. Since OpenID-LDAP-PHP version 0.8.7 you are
required to use SSL connection.
'Smart Mode' OpenID authentication requires the use of "big math"
functions. If you do not have bcmath or GMP available, you can use a built
in pure-PHP "big math" library, but it is not very efficient. You are
encouraged to use bcmath if at all possible.
No MySQL or any other database is required. This software does not use a
backend database by design! It uses a LDAP server tho, to fetch users data.
Currently OpenID-LDAP-PHP does not provide any way for creating or
editing user accounts. You have to use some other way to perform this.
There's no reason that OpenID-LDAP-PHP should not work under IIS.
It is proved that OpenID-LDAP-PHP works fine with Microsoft Windows Server
and Active Directory user accounts.
FOR MORE INFORMATION ON OpenID, PLEASE SEE http://openid.net/
************
INSTALLATION
************
OpenID-LDAP-PHP can be installed on just about any PHP server. It is recommended
that you use a server that you own and control.
1) Decide how you want to install OpenID-LDAP-PHP. It requires at least few files,
and can be installed in a number of ways. The files you will be uploading are
- installation root folder:
engine.php The application library
showme.php Username to URL redirection library
index.php This is the file you'll be visiting in your browser
ldap.php The LDAP-link library, contains creds, and options
style.css Some CSS formating definitions
- into images directory:
logo.gif The OpenID logo and text, plus LDAP, on white background
openid.ico A small OpenID logo icon (can be placed in root folder
and renamed to "favicon.ico", see * notes bellow)
openid.gif The OpenID logo on white background
openid.png The OpenID logo with transparent background
openid-logo.gif The OpenID logo and text on white background
user.gif A small person image
Please keep the directory structure while uploading files. Do not store all
files in one location unless you want to edit source files respectively.
2) Upload the files. That's right, just upload 'em. Put 'em wherever you want.
I suggest your root URL, but you can do whatever you need to make them web
accessable, as long as you can figure out what the URL should be.
3) Visit your upload location in a web browser. You should see a message that
says "This is the <company> OpenID provider home page." You should also see
some welcome message and help links.
If you don't see all of these things, proceed to the Troubleshooting section
of this document.
4) If your "Realm" is anything other than the string 'OpenID' (like say, if it
has a number after it) then make note of the value. This means that PHP is
running in "safe mode," and while I disagree for the reasons they change the
realm, there's nothing I can do about it.
Edit your config file, and change the key "auth_realm" to reflect the "Realm"
value displayed in your browser. The default is 'OpenID' and it only needs
to be changed if the string you see in your browser is something different.
If you're going to want to change this to some custom value just edit the
"auth_realm" key to read whatever you want. Remember, however, that you need
to double check your realm value by visiting MyID.config.php in a browser after
you make the change (and upload it).
5) Now you get to configure your LDAP connection settings. Edit ldap.php file
and set up your Primary and secondary (Fallback) server names or their IP
addresses. Also provide BindDN and Password to connect to servers.
SearchDN is a root where users shall be looked up. The entire subtree will
be searched using Filter setting. Note that it contains '%s'; that's where
the username will be substituted before performing the lookup. For more
information about LDAP search filters, go to
http://confluence.atlassian.com/display/DEV/How+to+write+a+LDAP+search+filter
And finally, TestDB setting is similar to Filter one, except it describes
the DN of the user which tryes to login. It is needed in order to validate
provided password. The '%s' will be replaced with provided username.
Fill names matching between OpenID Simple Registration and LDAP fields.
6) Upload modified files again, replacing the ones that were already there.
Visit upload location in a browser again, or refresh the current page. The
output shouldn't change, you're just looking to be sure there are no errors.
Be certain that the 'Realm' listed exactly matches the value you used when
you created your password hash in step 5.
Enter your LDAP username into text-edit field and click "Enter" button. For
example, the URL shall now be "https://yourdomain.com/some/path/username".
You should see a welcome message saying your fullname and your OpenID URL.
If an error message is displayed or "User not found in our database, sorry."
text is shown, then go back and edit your ldap.php file again.
If you still can't get trought it, proceed to the Troubleshooting section.
Click 'Login' - you should be redirected a couple of times and then presented
with a login dialogue box. Enter your username and password and click ok.
Again, you should be bounced around for a sec, then get a message which says
you're logged in as whoever your username is.
If you can't log in, if you get an error, or if doesn't work in some other
way, proceed to the Troubleshooting section.
7) Now, you are logged in, click "Continue" to return to your Identity Provider.
This is the URL you must use to authenticate as to any OpenID-enabled site,
as this is your personal OpenID.
If you wish to use another URL (owned by you), instead of this one, then use
the above link as your openid.server and the new URL as openid.delegate.
The preferred way of setting this up is to determine the URL you wish to
authenticate as (for example "http://myblog.org/"), and add the following
to the HTML <head> section for that document:
<link rel="openid.server" href="https://yourdomain.com/path/username">
<link rel="openid.delegate" href="http://myblog.org/">
You may now use your URL http://myblog.org/ with OpenID-enabled sites.
8) Remember, you have to run this package under SSL in order to protect user
passwords. OpenID-LDAP-PHP generates OpenID for each LDAP user in form:
https://yourdomain.com/some/path/username
This requires some changes in you Apache configuration. We'll use mod_rewrite
features and put these settings into your ssl.conf file - in general host
section, or in some virtual host one, depending of your configuration.
First, you might want (highly recommended) to redirect all non-SSL requests
via SSL. Add this to your "httpd.conf" file:
RewriteEngine On
RewriteRule ^/dir$ https://host/dir/ [R=permanent,L]
RewriteRule ^/dir/$ https://host/dir/ [R=permanent,L]
RewriteRule ^/dir/(.*)$ https://host/dir/$1 [R=permanent,L]
Next, add this to your "ssl.conf" file to proxy usernames to internally
processed requests to index.php script:
SSLProxyEngine On
RewriteEngine On
RewriteCond %{REQUEST_URI} !^/(.+)\.php(.*)$
RewriteCond %{THE_REQUEST} ^[A-Z]{3,9}\ /dir/([A-Za-z0-9]+)\?(.*)\ HTTP/
RewriteRule ^/dir/(.*)$ https://host/dir/index.php?user=%1&%2 [P]
RewriteCond %{REQUEST_URI} !^/(.+)\.php(.*)$
RewriteRule ^/dir/([A-Za-z0-9]+)$ https://host/dir/index.php?user=$1 [P]
Make sure you replace 'host' and 'dir' above with corresponding values from
your setup (i.e. 'yourdomain.com' and 'some/path', for example).
The SSL host definition must be using the IP and not the hostname. It
should look like: <VirtualHost 192.168.1.1:443>. If you fail to do so
you may spend quite some time why mod_rewrite is doing nothing.
Don't forget to change in httpd.conf: "AllowOverride None" to
"AllowOverride All" (it may appear several times).
9) Set right permissions to ldap.php file because it contains your LDAP password
$ cd /var/www/ssl/some/path
$ chown root.apache *
$ chmod 644 *
$ chmod 640 ldap.php
*) Additional notes:
- Using favicon.ico in your webserver root folder could require a change to
your apache.conf file. Add this line to it, if its not there already:
AddType image/x-icon .ico
then restart the httpd service and reload the page in your browser.
- Running PHP under Windows, by default, stores sessions in a directory called
"sessions" in the PHP directory. However, this directory doesn't exist in the
distribution, and it won't be created, so sessions fail and OpenID-LDAP-PHP
won't allow logins. So for phpmyid to work, an empty directory called "sessions"
needs to be created in the php installation directory.
- Connecting to Active Directory is enabled by default and could be disabled by
setting $ldap['isad'] setting to 'false'.
#####
USAGE
#####
There isn't much to using OpenID-LDAP-PHP other than pointing at it, and logging
in. If you wish, you can log out by visiting:
http://yourdomain.com/some/path/username?openid.mode=logout
There is also a 'log in' mode that will prompt you for credentials without
having to be referred from a client site.
http://yourdomain.com/some/path/username?openid.mode=login
####################################
SIMPLE REGISTRATION EXTENSION (SREG)
####################################
OpenID features something called 'sreg' which is a way to supply commonly
requested personal information to any site which you log into. Typically, a
client site uses this to create your profile the first time you log in. This
'sreg' information comprises such things as your nickname, email address, time
zone preference, etc...
All of the SREG keys are optional. To enable the use of any of them, simply
edit ldap.php file and supply name matching between SREG and LDAP attribute,
corresponding to that key. If you don't feel like supplying a particular detail,
just leave it commented out, or empty. Note that these settings are common for
all LDAP users.
####################
ADVANCED CONFIG KEYS
####################
Several other configuration keys exist and can be set in the 'profile' array:
'allow_test' If set to true, this key will allow OpenID-LDAP-PHP to run a special
test mode. Set the key to true, and visit your IdP url. You
should see a "Test" link that was not previously available.
By clicking it, OpenID-LDAP-PHP will conduct a series of tests designed
to validate the functionality of the internal signature and
math functions. This information is useful for troubleshooting.
'auth_realm' You can configure the name of the realm you are prompted to log
into during authentication. Remember, if you change this value,
you will have to adjust your 'auth_password.'
'debug' If set to true, OpenID-LDAP-PHP will do perform debug logging. If you
turn this on, you are strongly encouraged to also set the key
'logfile' to explicitly set the path to your debug log. If not,
OpenID-LDAP-PHP will attempt to automatically ascertain the correct
location to put a 'OpenID-LDAP-PHP.debug.log' file, and will cause an
internal error if it cannot write to that location.
'idp_url' This key defines the identity that OpenID-LDAP-PHP will allow
you to claim. It is almost always set correctly by default.
'logfile' When the 'debug' key is true, this key is used to define the
absolute path to a debug log.
'force_ssl' When writing openid.server and openid.delegate into HTML <head>
section, always use SSL (https) protocol, if this key is 'true'.
######################
# OPTIONAL CONFIG KEYS
######################
'microid' If you would like OpenID-LDAP-PHP to assert your ownership via
MicroID tags, you can configure this key (either as a string or an
array). Any values must be complete URI to the asserted owner.
One suggestion is to enter the value of the URL you are
delegating from (installation step 7). You can also use your
email address. In either case, be sure to prefix your URI
correctly with "mailto:" or "http://" etc...
'pavatar' If you would like OpenID-LDAP-PHP to assert your ownership of a
Pavatar by embedding an optional image tag into its HTML document
header, you can configure this key. The value set should be a
complete URL to your Pavatar image. See http://pavatar.com
for more information.
##########################
# EXPERIMENTAL CONFIG KEYS
##########################
'paranoid' Part of the OpenID specification requires clients to ask the
identity servers to trust a specific root URL for all identity
transactions. OpenID-LDAP-PHP ignores this requirement by default
in favor of a speedier and more fluid login for users, however,
you can a "paranoid" mode that will allow you to receive prompts
to trust each client as you log in to them.
###########################
REALLY ADVANCED CONFIG KEYS
###########################
'allow_gmp' When set to true, the GMP (Gnu MP Bignum library) extension,
if available, can be used for big math calculations (ie
encryption, or "Smart Mode").
'auth_domain' This is the domain value used in the HTTP Basic authentication.
It defaults to your idp_url (see above).
'force_bigmath' If set to true, the internal pure-PHP big math library will be
used to ensure "Smart Mode" is always available, even if neither
bcmath nor gmp extensions can be used. Note that using this may
result in a severe performance degredation for your system. You
should only switch this on if you *really* need to use "Smart
Mode," and cannot otherwise get bcmath or gmp installed on your
system.
'lifetime' This key defines how long an OpenID session is valid for. The
default value takes into consideration both the internal PHP
session lifespan as well as the default frequency of garbage
collection on your system.
###############
TROUBLESHOOTING
###############
*) Can't log in while running OpenID-LDAP-PHP under IIS
By default, PHP for Windows ships in such a way that sessions do not work
correctly out of the box. You will need to create a folder called "sessions"
in your PHP installation directory.
*) Received error: "This site is not compatible with 'suhosin'"
Suhosin is a security add-on for PHP which, amongst other things, removes
PHP's ability to open and access multiple sessions at one time. Simply put,
OpenID-LDAP-PHP is reliant upon this feature, and will therefore not work with
a hardened PHP.
Some users have reported successfully using OpenID-LDAP-PHP with suhosin,
either by modifying the script, or using an alternate webserver (such as
lighttpd). These solutions are unsupported. There is currently no official
support for OpenID-LDAP-PHP with suhosin.
*) Received error: "Missing expected authorization header."
OpenID-LDAP-PHP must be able to read http request headers which are only
available if PHP is running as a webserver module. If you are using PHP
in CGI mode, you must convert the HTTP 'Authorization' header into an
environment variable ("PHP_AUTH_DIGEST") or query parameter ("auth") that
can then be used to perform the authorization.
If you are using Apache, the included 'htaccess' file contains three examples
of how you can use mod_rewrite or mod_setenvif directives to set the
necessary variable. If you need to use this technique, it is recommended
that you place OpenID-LDAP-PHP in its own directory, isolated from the rest
of your web site.
*) Received error: "User <name> not found..." no matter what name I provide.
Check your ldap.php connection settings, again. Also try it out at the
command prompt, if it works?
$ ldapsearch -s sub -x -h <ServerIP> -W -D <BindDN> -b <SearchDN> <Filter>
You could try lookup your own user account. Note that the returned result
should be only 1. If for some reasons the results are more that one, it
wan't work.
*) Why does/doesn't my Server string have "www." in it, my URL does/dosen't?
If your ServerName is set to one value (in your webserver configuration)
and you regularly access it with something else (say, an alias or w / w/o a
www on the front of it), OpenID-LDAP-PHP may get confused.
The easiest way to remedy this situation is to explicitly set the "idp_url"
key in your profile array. The value should be the exact, complete URL, to
your installation of OpenID-LDAP-PHP.
$GLOBALS['profile'] = array(
...
'idp_url' => 'http://yoursite.com/index.php',
...
);
*) Still can't figure it out?
Sometimes the unexpected happens. Sometimes bugs creep into the code. For
all these times, check if you're using the latest version at:
http://www.openid-ldap.org/
EOF