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