-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
387 lines (269 loc) · 15.7 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
phpMyID - A standalone, single user, OpenID Identity Provider
by: CJ Niemira <siege (at) siege (dot) org>
(c) 2006-2008
http://siege.org/projects/phpMyID
phpMyID is a small, fairly lightweight, standalone, single user Identity
Provider for OpenID authentication. It comprises a one PHP script (plus a config
file) 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.
phpMyID is NOT compatible with Suhosin or other hardened PHP systems (Debian
users take note).
User authentication is done using HTTP Digest authentication, so your password
is never transmitted over the wire in plain text.
NOTE: '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.
The name 'phpMy...' does NOT indicate that MySQL or any other database is
required. This software does not use a backend database by design!
There's no reason that phpMyID should not work under IIS. However, getting
HTTP Digest authentication to work properly may require jumping through
some hoops. Please see here: http://php.net/http-auth
FOR MORE INFORMATION ON OpenID, PLEASE SEE http://openid.net
************
INSTALLATION
************
phpMyID 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 phpMyID. It requires at least two files, and
can be installed in a number of ways. The two files you will be uploading
are:
MyID.php The application library
You can rename it if you like
MyID.config.php This is the file you'll be visiting in your browser
It contains your user profile, creds, and options
You can rename it too
Three suggestions for installation are:
a) Don't bother renaming the files because there's no reason to
b) Rename MyID.config.php to index.php and plan to put them in a new
directory
c) Rename 'em both. Like, change MyID.config.php to whatevermakesyouhappy.php
and MyID.php to somethingjustassilly.php. This option is kinda like a
vanity license plate... pointless, but if it makes you happy, go nuts.
2) Upload the files. That's right, just upload 'em. Unless you decided you need
to rename MyID.php, you shouldn't have edited them yet. 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.
If you did rename MyID.php, then you must change the last line of whatever
your config file is now called to reflect the new name (the 'require' line).
3) Visit your config file (the one that used to be MyID.config.php - 'cause I
know you just *had* to rename it) in a web browser. You should see a message
that says "This is an OpenID server endpoint." You should also see a
"Server" URL, and a "Realm" string.
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 'phpMyID' (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 with the reason *why* PHP
changes the realm, there's nothing I can do about it.
If you want to change this to some custom value (pointless to do so, but if
it makes you happy, you can) just edit the "auth_realm" key in your config
file so it reads as 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).
The important part is to keep the "realm" you see in your browser handy.
5) Now you get to decide your login name and password. This is what you will use
to authenticate yourself to phpMyID. Your login name can be anything you
like.
To create your password, you will need an MD5 hashing utility. If you are a
Linux or OSX user, you can use openssl. Simply open a terminal and type:
$ echo -n 'username:realm:password' | openssl md5
If you are a Windows user, and do not already have an MD5 hashing tool, one
is available at http://siege.org/projects/phpMyID/md5.exe . To use it,
download the exe, and open a cmd session. Here's an example of how it works:
C:\Documents and Settings\cniemira>cd Desktop
C:\Documents and Settings\cniemira\Desktop>md5.exe -d"username:realm:password"
In either case, make sure to substitute your username and password where
indicated. You must also substitute "realm" for your authentication realm as
determined in step 4. The resulting output, which will be a long alphanumeric
string, is your "Digest Password" that must now be entered into your config
file in the 'auth_password' field. While you're at it, enter the username you
just used as the 'auth_username' key.
Note that the default username and password are both "test," and were encoded
with the realm "phpMyID". That means you can probably test logging in right
of the bat as 'test'/'test' (assuming your server is not running in safe
mode).
6) Upload your config file again, replacing the one that was already there.
Visit your config file 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.
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) The "Server" URL, is your Identity Provider. This is this URL you must link
as your openid.server and openid.delegate.
The preferred way of setting this up is to determine the URL you wish to
authenticate as (e.g., "http://phpmyid.com", in my case), and add the
following to the HTML <head> section for that document:
<link rel="openid.server" href="http://phpmyid.com/MyID.config.php">
<link rel="openid.delegate" href="http://phpmyid.com/MyID.config.php">
Remember, BOTH the openid.sever and openid.delegate values should be set to
the same thing.
You may now use your URL with OpenID (e.g., "http://phpmyid.com" in my case).
#####
USAGE
#####
There isn't much to using phpMyID other than pointing at it, and logging in.
If you wish, you can log out by visiting:
http://yourdomain.com/path/to/MyID.php?openid.mode=logout
After you "log out" of phpMyID, YOU WILL HAVE TO close your browser. This is
because it will cache your credentials and automatically log you back in the
next time it is prompted to do so. You will not see the login box, as this will
happen transparently. The illusion is that it looks like you never actually
logged out, when in fact you did, and were then logged back in without knowing.
####################################
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
uncomment the line by removing the hashmark, and replace the value with your
own information. If you don't feel like supplying a particular detail, just
leave it commented out.
####################
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 phpMyID 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, phpMyID 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, phpMyID 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,
phpMyID will attempt to automatically ascertain the correct
location to put a 'phpMyID.debug.log' file, and will cause an
internal error if it cannot write to that location.
'idp_url' This key defines the identity that phpMyID 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.
######################
# OPTIONAL CONFIG KEYS
######################
'microid' If you would like phpMyID to assert your ownership via MicroID
tags, you can configure this key (either as a string or an
array). Any values must be complete URLs 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 URL
correctly with "mailto:" or "http://" etc...
'pavatar' If you would like phpMyID 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. phpMyID 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 Digest authentication.
It defaults to your idp_url (see below).
'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 phpMyID 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.
See: https://www.siege.org/forum/viewtopic.php?id=273
*) Received error: "phpMyID 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,
phpMyID is reliant upon this feature, and will therefore not work with a
hardened PHP.
To make phpMyID work with Suhosin, you can try the following:
1) Set the profile key 'allow_suhosin' to "true" in your config file.
2) Set "suhosin.session.encrypt Off" in either your PHP/Suhosin config file,
or as a php_flag in your httpd.conf (or .htaccess).
See: https://www.siege.org/forum/viewtopic.php?pid=3167
*) Received error: "Missing expected authorization header."
phpMyID 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 to set the
necessary variable. If you need to use this technique, it is recommended
that you place phpMyID in its own directory, isolated from the rest of your
web site.
*) Login never works? Double check your authentication realm
Digest authentication can be a bit tricky to set up properly. One of the
biggest stumbling blocks has to do with the authentication realm as described
under installation step 1. If you change servers or if any settings on your
server changes, it is possible that your authentication realm will change as
well. If that happens, you will no longer be able to authenticate to phpMyID,
and must re-create your password hash.
When you log in to phpMyID, your web browser will present the authentication
realm to you in the login box it pops up. It will say something like this:
Enter username and password for "phpMyID-101" at http://phpmyid.com
The quoted value in the above is your authentication realm. Make sure that is
the same value you used when you created your password hash.
*) Login still broken? Try re-encoding the test values.
Sometimes different computers, using different character sets, will produce
different md5 values. Try generating an MD5 hash for "test:phpMyID:test"
(no quotes). If the value you get back isn't this:
37fa04faebe5249023ed1f6cc867329b
then you may have a character set problem. The quick solution for this is
to have your webserver do the hashing for you. It's not the most secure
option in the world, but you can create a temporary php file containing
the following:
<?php
echo md5("user:realm:pass");
?>
Then upload it, hit it in your browser, get your hash, and delete it.
*) 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), phpMyID 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 phpMyID.
$GLOBALS['profile'] = array(
...
'idp_url' => 'http://phpmyid.com/index.php',
...
);
*) Still can't figure it out?
Sometimes the unexpected happens. Sometimes bugs creep into the code. For
all these times, please consult the phpMyID forum at:
https://www.siege.org/forum/
EOF