= Whobar Integration Guide = Welcome to the Whobar integration guide! By integrating Whobar into your site you are participating in a new paradigm of user experience on the web. The goal of Whobar is to make this transition easier. Depending on the complexity of your site, there may be few or many changes required. Please share your experiences with the Whobar community so that we can help improve our documents and code. Before reading this document, you might want to try going through the install guide (INSTALL), and play with the Whobar demo, to get a feel for how Whobar works. == Summary == # Modify your data model # Create your Whobar form # Customize your Whobar configuration file # Create a whobar-handler script # Identify messages coming from Whobar # Decide if any passthrough data is needed # Enable account linking (optional) # Where to go next == Modify your data model == The most basic change a site needs to make when moving to an Identity 2.0 authentication system is to add support for login via a unique identifier that is not generated or managed by the site itself. So the first thing you'll probably want to do is look at your data model and decide how you want to store these new identifiers (anywhere this document refers to "identifiers", take this to mean these globally unique identifiers). The simplest implementation is to have a one-to-one map of identifiers to user accounts. In practical terms this could look like adding an additional column to the "user" table in your database to hold the identifier associated with that account. A more complex implementation is to allow users to have multiple identifiers link to the same user account. This would allow, say, a user to login with their i-name or their OpenID url, and both identifiers would log them in to the same account. This implementation might involve adding a table to your database with a column for identifiers and a foreign key column derived from the primary key of your user table. Once you have made the required changes to your data model, you'll be ready to modify your registration and login scripts to accomodate logins via Whobar. == Create your Whobar form == Next you'll need to create a Whobar form. The best way to do this is to start with the form in the Whobar demo and modify it to fit your needs. The most important part here is deciding what identity data you want Whobar to request for you. The best way to figure out what identity data you need is to analyze your site's registration form. For each input field, look in the OpenID Attribute Exchange schema for an attribute that is a good fit. Then add hidden input fields to the Whobar form where the field names are the exact names of the registration form inputs, prefixed with 'openid.ax.fetch.' (e.g. for , the Whobar request parameter is "openid.ax.fetch.fname"), and the values are the corresponding property URLs (e.g. http://openid.net/schema/namePerson/first). The OpenID Attribute Exchange schema can be found here: http://www.openid.net/specs/openid-attribute-properties-list-1_0-01.html When setup this way, Whobar will send the identity data to your handler script using the same field names as your existing registration form, thus reducing the amount of changes required. Tip: If you have identity data in the form that is not covered in the OpenID Attribute Exchanges schema, feel free to suggest this to the OpenID community for addition. Tip: Your form may require non-identity data as well, like a username, or a preference like "Would you like to receive announcements via email?". Don't try to add these to the Whobar form - the whobar-handler script will prompt the user for these upon registration (described in the next section). == Customize your Whobar configuration file == Next you'll need to customize your Whobar configuration file. The demo configuration file contains documentation describing the various settings. == Create a Whobar handler script == Another basic difference between Whobar authenticaton and conventional web authentication is that with Whobar, registration and login are in many ways the same thing. In both cases, a handler script receives a POST containing set of name-value pairs - consisting of an identifier and possibly some identity data (name, email address, etc.). The pseudocode for this handler script (call it the whobar-handler) looks something like this: * Is this a known identifier (i.e. is it linked to an existing user account)? ** If so, the user is logged-in (invoke login logic). ** If not, a new account is created for the user (invoke registration logic). So the first task of the whobar-handler script is to lookup the user account associated with the identifier, and if this account exists, the user is logged in to that account, the user is sent the conventional "you are logged in" response, and the handler is finished. If no account is found, then a new one should be created. This is where Whobar makes things easy. After customizing the Whobar configuration file with desired property name-value pairs the incoming data POST from Whobar to the whobar-handler script will be identical to a user submitting your site's registration form. So the user will now be in your site's conventional registration flow. The only change you'll need to make to the registration logic is to add the user's identifier to your data store in addition to the other usual registration data. It's really that easy. The response the user should see for incomplete/incorrect data should be the same as if they had filled out an incomplete or incorrect registration form (e.g. the site shows the registration form again, with the submitted data filled in, and messages describing what's missing or incorrect). == Identify messages coming from Whobar == It's important to know which messages to your whobar-handler are coming from Whobar. Depending on your setup, you may want to restrict all access to your whobar-handler script to only Whobar. When Whobar sends the results of the authentication to your whobar-handler, it does so by acting like an HTTP proxy - it accepts the authentication request from the browser, processes it, and composes a message to send to the whobar-handler. When the whobar-handler responds, this response is proxied back to the browser. The easiest way to secure your whobar-handler script is to check that the POST contains a key called 'whobar_secret' which matches the shared secret from the Whobar config file. Another way is to check that the request is coming from a certain host or IP which is owned by you. == Decide if any passthrough data is needed == Any query parameters sent to Whobar when the user submits the login form are returned in the POST to the whobar-handler. This provides a mechanism for sending state information along with the login request. == Set up account linking (optional) == In the situation where there is a one to many mapping of user accounts to identifiers (i.e. a user may log in to the same account with multiple identifiers), site should provide a "Manage identifiers" interface, allowing the user to link identifiers to their account, or delete identifiers. The add-identifier flow is similar to the login flow - the user is shown the Whobar form, and asked to authenticate. The resulting identifier POSTed to the whobar-handler is then linked to the account. All that's required is that an extra piece of passthrough data is sent to the whobar-handler, indicating that the the user is linking accounts, not logging in. == Where to go next == Depending on the complexity of your site, there may be further integration steps not covered here. Please feel free to share your experiences with the Whobar community, so that we can make it easier for others who are doing similar work. Mailing lists: http://listserv.whobar.org If you have installed Whobar on your site, tell us about it! We'll link even to you from whobar.org (if you want). Ping us at feedback@whobar.org. If you decide that Whobar isn't for you, tell us about it! :) We want to know what hurdles people are facing. Is there a key feature missing? Does Whobar not run on your platform? Holler at feedback@whobar.org.