(* This module implements the key primitive of the OpenID 2.0 authentication * protocol, as specified in: * http://specs.openid.net/auth/2.0 * * Module author: Adam Chlipala * * Known missing features: * - Compatibility with prior OpenID protocols * - Endpoint discovery via XRIs or Yadis * - Immediate requests (authentication with no opportunity for user * interaction) * - Publishing information for relying party discovery * - Extensions (in the protocol specification's terminology) * * Support for every other aspect of relying party functionality should be * present, including appropriate security measures. *) (* == Quick summary of OpenID == * There are lots of protocol details, but my take on it comes down to one * simple idea. OpenID exports a primitive that allows a web site that verify * that a particular _user_ wishes to provide his identity to a particular * _URL_. There is use of cryptography and other fanciness to implement this * primitive securely and efficiently, but application builders shouldn't need * to think about the implementation details. Indeed, that simple interface is * what this module exports. Thanks to Ur/Web's usual encapsulation guarantees, * client code need not worry about accidentally disturbing state used by the * protocol. * * The last key aspect is that URLs are used to identify users. Each URL should * point to an HTML page containing a special tag which points to another URL * that is assigned responsibility for answering queries about what the user * has authorized. To use the library, you only need to think about the * initial, user-identifying URLs, which form a kind of universal username * namespace. *) (* The protocol provides some options for how particular security requirements * can be satisfied. This module defines a few datatypes for the different * dimensions of choice. *) (* First, we have association types, which are methods of guaranteeing message * integrity. The only options in OpenID 2.0 are two different hash-based * message authentication codes (HMACs). [HMAC_SHA256] is the stronger * scheme. *) datatype association_type = HMAC_SHA1 | HMAC_SHA256 (* Next, there are association session types, which are approaches to * establishing shared secrets that can be used to provide integrity. There are * two versions of the Diffie-Hellman key exchange protocol, based on pairing * with different MAC algorithms. The [NoEncryption] option is only * appropriate for communication via SSL, which already provides secrecy. If * [NoEncryption] is requested over an unencrypted HTTP connection, the library * will automatically switch to [DH_SHA256]. *) datatype association_session_type = NoEncryption | DH_SHA1 | DH_SHA256 (* Finally, you have the option to skip all this crypto stuff in your * application, at some expense. Use of cryptography with shared secrets allows * you to authenticate a user with one fewer round-trip to the remote web server * that is placed in charge of that user's identity. This benefit is traded for * greater space requirements in your application, with several kinds of data * stored in local SQL tables, with the number of rows roughly proportional to * the number of authentications, over short time periods. A stateless approach * uses local state only as a cache for predictable HTTP request results, with * storage use proportional to the number of users. (The stateful approach uses * that same state and more.) *) datatype association_mode = Stateless | Stateful of {AssociationType : association_type, AssociationSessionType : association_session_type} (* It is possible to request authentication in two different modes: *) datatype authentication_mode = ChooseIdentifier of string (* The provider prompts the user to select his identity. * The string argument should be a generic endpoint, e.g., * "https://www.google.com/accounts/o8/id". *) | KnownIdentifier of string (* Require authentication as this precise identifier. *) (* An authentication attempt terminates in one of four ways. * First, the user might get bored and surf away, never finishing the process. * If so, your application will never be told explicitly. * The other possibilities are captured by this datatype: *) datatype authentication = AuthenticatedAs of string (* Successful authentication, with the user's verified identifying * URL *) | Canceled (* The user explicitly canceled the authentication process. *) | Failure of string (* Something went wrong, and here's some text that hopefully diagnoses * the problem. *) (* Finally, here's the function to call to verify that a user wants to * authenticate to your particular web application. Note that this will only * work properly if your project .urp file includes a 'prefix' directive that * gives the full protocol, hostname, and port part of your URLs. * * If authentication proceeds successfully, the function will never return. * Instead, the user is redirected to his identity provider, to authenticate with * whatever method they have agreed on. When that process finishes, the user is * redirected back to your app, at which time the function that you pass as the * first argument below is called with the result, to generate the page to show * to the user. * * If authentication fails before the user is redirected away, the original * function returns an error message suitable for display to technically-savvy * users. *) val authenticate : (authentication -> transaction page) -> {Association : association_mode, (* Your preferences for statefulness and cryptography. * If the remote server doesn't support some kind of * crypto that you ask for, the library automatically * switches to a mode that the server advertises as * supported. *) Identifier : authentication_mode, (* The URL that the user claims identifies him. * It may also point to a generic authentication service * that will take care of deciding the proper * username. *) Realm : option string (* A URL prefix that we are asking the user to authorize. * If provided, it must be a genuine prefix of every * application URL. If omitted, we authorize for just one * specific URL, which is the authentication-specific URL * that the library always chooses automatically. *)} -> transaction string