diff options
| -rw-r--r-- | Auth/OpenID/Consumer.php | 170 |
1 files changed, 78 insertions, 92 deletions
diff --git a/Auth/OpenID/Consumer.php b/Auth/OpenID/Consumer.php index eabe043..b900032 100644 --- a/Auth/OpenID/Consumer.php +++ b/Auth/OpenID/Consumer.php @@ -2,35 +2,39 @@ /** * This module documents the main interface with the OpenID consumer - * libary. The only part of the library which has to be used and isn't - * documented in full here is the store required to create an - * OpenIDConsumer instance. More on the abstract store type and + * libary. The only part of the library which has to be used and + * isn't documented in full here is the store required to create an + * Auth_OpenID_Consumer instance. More on the abstract store type and * concrete implementations of it that are provided in the - * documentation for the constructor of the OpenIDConsumer class. + * documentation for the Auth_OpenID_Consumer constructor. * * OVERVIEW + * ======== * * The OpenID identity verification process most commonly uses the * following steps, as visible to the user of this library: * - * 1. The user enters their OpenID into a field on the consumer's - * site, and hits a login button. - * 2. The consumer site checks that the entered URL describes an - * OpenID page by fetching it and looking for appropriate link tags - * in the head section. - * 3. The consumer site sends the browser a redirect to the identity - * server. This is the authentication request as described in the - * OpenID specification. - * 4. The identity server's site sends the browser a redirect back to - * the consumer site. This redirect contains the server's response - * to the authentication request. + * 1. The user enters their OpenID into a field on the consumer's + * site, and hits a login button. + * + * 2. The consumer site discovers the user's OpenID server using the + * YADIS protocol. + * + * 3. The consumer site sends the browser a redirect to the identity + * server. This is the authentication request as described in + * the OpenID specification. + * + * 4. The identity server's site sends the browser a redirect back + * to the consumer site. This redirect contains the server's + * response to the authentication request. * * The most important part of the flow to note is the consumer's site * must handle two separate HTTP requests in order to perform the full * identity check. * * LIBRARY DESIGN - * + * ============== + * * This consumer library is designed with that flow in mind. The goal * is to make it as easy as possible to perform the above steps * securely. @@ -38,23 +42,23 @@ * At a high level, there are two important parts in the consumer * library. The first important part is this module, which contains * the interface to actually use this library. The second is the - * {@link Auth_OpenID_OpenIDStore} class, which describes the - * interface to use if you need to create a custom method for storing - * the state this library needs to maintain between requests. + * Auth_OpenID_Interface class, which describes the interface to use + * if you need to create a custom method for storing the state this + * library needs to maintain between requests. * * In general, the second part is less important for users of the * library to know about, as several implementations are provided - * which cover a wide variety of situations in which consumers may - * use the library. + * which cover a wide variety of situations in which consumers may use + * the library. * - * This module contains a class, {@link Auth_OpenID_Consumer}, with - * methods corresponding to the actions necessary in each of steps 2, - * 3, and 4 described in the overview. Use of this library should be - * as easy as creating a {@link Auth_OpenID_Consumer} instance and - * calling the methods appropriate for the action the site wants to - * take. + * This module contains a class, Auth_OpenID_Consumer, with methods + * corresponding to the actions necessary in each of steps 2, 3, and 4 + * described in the overview. Use of this library should be as easy + * as creating an Auth_OpenID_Consumer instance and calling the + * methods appropriate for the action the site wants to take. * * STORES AND DUMB MODE + * ==================== * * OpenID is a protocol that works best when the consumer site is able * to store some state. This is the normal mode of operation for the @@ -71,11 +75,11 @@ * * Several store implementation are provided, and the interface is * fully documented so that custom stores can be used as well. See - * the documentation for the {@link Auth_OpenID_Consumer} class for - * more information on the interface for stores. The concrete - * implementations that are provided allow the consumer site to store - * the necessary data in several different ways: in the filesystem, in - * a MySQL database, or in an SQLite database. + * the documentation for the Auth_OpenID_Consumer class for more + * information on the interface for stores. The implementations that + * are provided allow the consumer site to store the necessary data in + * several different ways, including several SQL databases and normal + * files on disk. * * There is an additional concrete store provided that puts the system * in dumb mode. This is not recommended, as it removes the library's @@ -86,12 +90,13 @@ * between requests at all. * * IMMEDIATE MODE + * ============== * * In the flow described above, the user may need to confirm to the - * identity server that it's ok to authorize his or her identity. The - * server may draw pages asking for information from the user before - * it redirects the browser back to the consumer's site. This is - * generally transparent to the consumer site, so it is typically + * lidentity server that it's ok to authorize his or her identity. + * The server may draw pages asking for information from the user + * before it redirects the browser back to the consumer's site. This + * is generally transparent to the consumer site, so it is typically * ignored as an implementation detail. * * There can be times, however, where the consumer site wants to get a @@ -105,6 +110,7 @@ * request. * * USING THIS LIBRARY + * ================== * * Integrating this library into an application is usually a * relatively straightforward process. The process should basically @@ -114,64 +120,44 @@ * is entered in that field and the form is submitted, it should make * a request to the your site which includes that OpenID URL. * - * When your site receives that request, it should create an - * {@link Auth_OpenID_Consumer} instance, and call beginAuth on it. - * If beginAuth completes successfully, it will return an - * {@link Auth_OpenID_AuthenticationRequest} instance. Otherwise it - * will provide some useful information for giving the user an error - * message. - * - * Now that you have the {@link Auth_OpenID_AuthenticationRequest} - * object, you need to preserve the value in its $token field for - * lookup on the user's next request from your site. There are - * several approaches for doing this which will work. If your - * environment has any kind of session-tracking system, storing the - * token in the session is a good approach. If it doesn't you can - * store the token in either a cookie or in the return_to url provided - * in the next step. - * - * The next step is to call the constructRedirect method on the - * {@link Auth_OpenID_Consumer} object. Pass it the - * {@link Auth_OpenID_AuthenticationRequest} object returned by the previous - * call to beginAuth along with the return_to and trust_root URLs. - * The return_to URL is the URL that the OpenID server will send the - * user back to after attempting to verify his or her identity. The - * trust_root is the URL (or URL pattern) that identifies your web - * site to the user when he or she is authorizing it. - * - * Next, send the user a redirect to the URL generated by - * constructRedirect. - * - * That's the first half of the process. The second half of the - * process is done after the user's ID server sends the user a - * redirect back to your site to complete their login. + * First, the application should instantiate the Auth_OpenID_Consumer + * class using the store of choice (Auth_OpenID_FileStore or one of + * the SQL-based stores). If the application has any sort of session + * framework that provides per-client state management, a dict-like + * object to access the session should be passed as the optional + * second parameter. (The default behavior is to use PHP's standard + * session machinery.) + * + * Next, the application should call the Auth_OpenID_Consumer object's + * 'begin' method. This method takes the OpenID URL. The 'begin' + * method returns an Auth_OpenID_AuthRequest object. + * + * Next, the application should call the 'redirectURL' method of the + * Auth_OpenID_AuthRequest object. The 'return_to' URL parameter is + * the URL that the OpenID server will send the user back to after + * attempting to verify his or her identity. The 'trust_root' is the + * URL (or URL pattern) that identifies your web site to the user when + * he or she is authorizing it. Send a redirect to the resulting URL + * to the user's browser. + * + * That's the first half of the authentication process. The second + * half of the process is done after the user's ID server sends the + * user's browser a redirect back to your site to complete their + * login. * * When that happens, the user will contact your site at the URL given - * as the return_to URL to the constructRedirect call made above. The - * request will have several query parameters added to the URL by the - * identity server as the information necessary to finish the request. - * - * When handling this request, the first thing to do is check the - * 'openid.return_to' parameter. If it doesn't match the URL that - * the request was actually sent to (the URL the request was actually - * sent to will contain the openid parameters in addition to any in - * the return_to URL, but they should be identical other than that), - * that is clearly suspicious, and the request shouldn't be allowed to - * proceed. - - * Otherwise, the next step is to extract the token value set in the - * first half of the OpenID login. Create a {@link Auth_OpenID_Consumer} - * object, and call its completeAuth method with that token and a - * dictionary of all the query arguments. This call will return a - * status code and some additional information describing the the - * server's response. See the documentation for completeAuth for a - * full explanation of the possible responses. - * - * At this point, you have an identity URL that you know belongs to - * the user who made that request. Some sites will use that URL - * directly as the user name. Other sites will want to map that URL - * to a username in the site's traditional namespace. At this point, - * you can take whichever action makes the most sense. + * as the 'return_to' URL to the Auth_OpenID_AuthRequest::redirectURL + * call made above. The request will have several query parameters + * added to the URL by the identity server as the information + * necessary to finish the request. + * + * Lastly, instantiate an Auth_OpenID_Consumer instance as above and + * call its 'complete' method, passing in all the received query + * arguments. + * + * There are multiple possible return types possible from that + * method. These indicate the whether or not the login was successful, + * and include any additional information appropriate for their type. * * PHP versions 4 and 5 * |