Introduction

AccountChooser is a facility where people can store identities they want to use for logging into Web sites.  These are keyed by email addresses and (optional) identity providers.  Your site can use AccountChooser automatically and for free, to help people log in more easily.

Important Note: Although the process includes redirects through accountchooser.com, the account information is saved in the browser using HTML5 local storage. At no time is any user information stored on any server.

ac.js

It’s all done with a chunk of JavaScript called “ac.js”, which does a variety of things depending on where it’s called from, and can be customized with configuration arguments. You could host ac.js yourself, but it’s probably best to pull it in from https://accountchooser.com/ac.js - remember to use secure networking.  This document, and the sample apps, should give you enough information to get started with ac.js.

For reference, its source code is online; the full API provided by ac.js is documented here, and there’s a write-up of the JavaScript implementation here. In this document, when you see something like “login screen (loginUrl:/account-login)”, that means that ac.js has a notion of a “login screen”, named in config variable “loginUrl”, whose default value is “/account-login” (you can change that default).  We give the short names of config variables in this document; they are stored in an object named accountchooser.CONFIG

Without AccountChooser

Let’s assume you have a Web app with a database.  In your database, you store per-account information; email, real name, maybe the user’s pictures, and then per-user application data. You have a way to check if a user-provided login and password correspond to what’s in the database.  Presumably you have a login screen and a sign-up-new-user screen.

Also, you may be a RP (relying party) for an IDP (identity provider), and for certain accounts, dispatch to the IDP to perform login.

To help us walk through all this, we’ve created two separate open-source sample apps, FavColor and AccountChooser Guestbook.  FavColor is a simple app (written in Ruby, based on the Sinatra framework), which stores one fact about each user: their favorite color. It provides a simple JavaScript control so they can update their favorite color.  

AccountChooser Guestbook is a refactoring of App Engine’s sample Guestbook app, removing the Google user integration and replacing it with AccountChooser. It’s written in Java.

Here are links to the core accounts/identity logic, without the benefit of AccountChooser,in FavColor and AccountChooser Guestbook.  If you’ve ever implemented an accounts/identity module, the logic will be familiar.

Storing Account Info in AccountChooser

There is some point in your app which recognizes the situation that a user has successfully logged in.  Likely it occurs twice: Upon successful user login, and upon successful creation of a new user account.  

When this happens, you need to return a page which includes ac.js along with some instructions instructing it to store the account info.  If it’s a returning user signing back in on the same computer then the account info is already stored, so this is a fast, efficient no-op.

The page you return will not actually be displayed, so its content is immaterial; you just need enough of a wrapper to provide a <head> element so ac.js is run.  The invocation should look like this, assuming you’ve just logged in Santa Claus:

<script type="text/javascript"        

     src="https://www.accountchooser.com/ac.js" />

<script type="text/javascript">

  accountchooser.CONFIG.storeAccount = {

    email: "kris.kringle@example.com",

    displayName: "Kris Kringle",

    photoUrl: "https://example.com/santa.jpg"

    providerId: "identity.example.com" };</script>

If AccountChooser doesn’t already know about this user, they’ll see a screen like this and be queried as to whether they want to store the details to facilitate further logins:

Whether or not the user visits this AccountChooser screen, and whether or not they agree to store their account name, they’ll be redirected back to your app’s home screen (homeUrl:/).

You can see the changes required to add AccountChooser account info storage to FavColor and AccountChooser Guestbook Step One.  

AccountChooser and the Login Screen

Now let’s put the stored information to good use.  You need to call ac.js from your login screen (loginUrl:/account-login), for example by embedding this in your <head> element; note that this invocation also changes the default location from /account-login to /utils/mysitelogin:

<script type="text/javascript"

     src="https://www.accountchooser.com/ac.js" />

<script>

 accountchooser.CONFIG.loginUrl = "/utils/mysitelogin";

</script>

ac.js will check to see if it has any stored identities; if there are none, the login screen loads and proceeds without any interruption.  If there are any, the user will see a screen like this, and can pick one of the accounts listed there by clicking on it.

If the user clicks on one of the accounts, ac.js sends an HTTP POST to a status checker (userStatusUrl:/account-status) that you have to implement. It receives two arguments as  URL query parameters: email ("email") and (optionally) Identity Provider ("providerId").  If they picked that Santa-Claus account we just stored, your status checker would see “email=santa@example.com”.  Your status checker should return JSON saying whether or not you know that identity already:

Known/Unknown

If you returned true, ac.js redirects back to your login page, looks through the DOM and finds the email field by its ID value (username:email), fills in the identity key, and places the focus in the password field, found via its ID value (password:password).

If you returned false, ac.js will redirect to your signup page (signupUrl:/account-create). This page should also call ac.js exactly as the sign-in page does, which will fill in the e-mail and display the user’s human-readable name (displayName:displayName) and picture (photoUrl:photoUrl) if those things are on file at AccountChooser.  Then it’ll place the focus in the password field.

You can see the changes required to add AccountChooser login assist to FavColor and AccountChooser Guestbook Step Two.  

Identity Provider Filtering

When you redirect to ac.js from your login page, you can optionally provide a list of Identity Providers that you support.  If you do this, when ac.js redirects back to your account-status page, you can be sure that, should it identify a provider, that provider will be from the list you provide.  For example:

<script type="text/javascript"

     src="https://www.accountchooser.com/ac.js" />

<script>  

  accountchooser.CONFIG.providers = ["yahoo.com", "facebook.com" ];

</script>

That’s All!

By adding simple Javascript callouts to a handful of places in your existing code and adding one new endpoint, without much re-architecting, you’ve added AccountChooser function, saving your users some keystrokes, and probably cutting down on the number of fumblefingered failed login attempts.

Additional Resources