User Interface
The following provides some guidelines for the user interface define of becoming an OAuth service provider.
1. OAuth Approval Page design
The main page you need to design is the one that end-users will use to approve a delegation request which will allow another website to access the data your company stores about that end-user. The OAuth standard does not define how this should look, it is up to you, and there are many different approaches to take with this UI. However when designing your UI, remember that not only do you have to get your end-users to use it, but you also need to convince developers to use this UI instead of them just asking your customers for their login information. If the developers think your UI is too complex or wordy, they are likely to skip it entirely. In this section we will give an overview, and in the next section we will provide a number of examples.
Another sad fact is that end-users understand the UI flow of giving their login information to one of these startups, but most end-users have never encountered the OAuth approval flow before and may be surprised/confused by it, especially if your approval page is complex. In fact, many user express confusion because they feel like they have to give their approval twice. For example, the startup might have a button that says "click here to give us access to your address book." That then sends the user to the Oauth approval webpage that asks the user to "click approve to give the site access to your address book." The second page seems redundant to end-users because they are not security experts, so they don't understand why they cannot just give this permission while they are on the startup's web page.
One way that OAuth does improve the user experience is that if the user is asked to enter their login information on the startups website, it will not be auto-filled by their browser, so it makes the user do more work (and in some cases they won't even remember their login details and will have to look them up). If the startup instead uses the OAuth flow, then if the user is already logged into the service provider then they simply click one button on each website. If they are not logged into the service provider, then the service provider will present them with a login page and their browser will probably auto-fill their login information.
So what elements might you include on the page:
Provide an approval button, as well a a way to leave the process if the user does not want to approve the requested access.
Short explanation - In general the shorter the better
FAQ/long explanation - You might also provide other advanced details like how users can revoke these tokens, or the fact that their password won't be shared with the other website. However the more prominent you make this information, the more cluttered your UI can get which can cause developers to go back to screen scraping, so you will need to find a balance that works for your company.
Identity the data being requested - If your company has multiple sets of data about the end-users, you can list what data set (or data sets) are being requested
Identify the OAuth consumer - This can be done by giving their domain name, a descriptive name they registered with your company (and which hopefully you double-checked), a description of the site, etc. You might also provide ratings/reviews/metrics about that consumer. For example, how many people have already delegated access to them, and what comments have those users made.
Access Level & Timeline - If your API supports different levels of access to the requested data and/or for different time frames, you can either let the user choose, or tell them what level of access the consumer requested. While letting the user choose certainly gives them more control, it also makes the process more complex, so again you need to find a balance.
Subsets - Very advanced service providers might let a user choose a subset of the requested data set to be made available to the 3rd party. In the examples below we show how Google Health lets an end-user choose which Health profile, and MS Live lets an end-user choose which fields of their address book.
Switch account - You might also give users an easy way to switch to a different account on your site, and delegate access to data in that account.
The key theme to remember is to balance simplicity with user control/notification. Your company's lawyers will probably want to review this page, and are likely to want to add lots of caveats and explanation. As a reminder of the "competition" you might show them the UI of a startup that does screen scraping.
If your OAuth APIs become popular, you might also find that they are accessed via an OAuth Proxy like the one that iGoogle provides to gadgets, but that other gadget hosting websites might add in the future. In that case, the OAuth "consumer" is now partially the gadget container (for example iGoogle) and partially the gadget itself that could have been written either by your firm or a 3rd party. The OAuth Proxy will send your website the identity of both the container as well as the URL of the gadget. That allows you to display information about both on your approval page. Once a service provider supports such a UI, we will try to add an example here.
2. OAuth Approval Page Samples
Below are some examples of existing delegation pages.
Here is an example of what Google used for their proprietary version of OAuth called AuthSub. The section in the middle about one-time access is an advanced option, but most OAuth consumers request on-going access to the user's data.
This example below adds a yellow warning to indicate to the user that the OAuth consumer has not finished registering with Google.
Here is a more recent UI that Google is using which moves some of the advanced explanation further down the page. This UI also allows an OAuth consumer to request access to multiple sets of data that Google stores for an end-user.
A more advanced Google UI is used for the Google Health product. In the case of the Google Health application, the end-user can create health profiles for multiple people (such as children), and the OAuth approval page allows the end-user to select which of these profiles should be accessible to the other service. Google Health also allows the OAuth consumer to specify whether it just wants the ability to post information to a user's profile, or whether it also want the ability to "read the entire profile." The user then has to approve the requested level of access which is described in the orange section. The Google Health API documentation includes additional resources with UI mocks, such as the Data providers overview.
Here is a screenshot of MySpace's approval page, including the ability for the user to specify a policy preference that indicates whether the 3rd party app can store/cache the user's contact information.
The following approval page is for a travel website
The web delegation API with the most bells and whistles is the one Microsoft Live provides. Here are two Blog entries with more details:
http://dev.live.com/blogs/devlive/archive/2008/02/27/213.aspx
http://winliveid.spaces.live.com/
They offer the ability for users to specify a time limit on the delegation, as well as the ability to choose whether the delegation is read-only or read-write. They even let the user choose specific fields of data in their contact list which are made available to the 3rd party.
For other web delegation UI examples look at Yahoo, Flickr, AOL, Facebook, eBay & Amazon. There is also an OAuth wiki with a list of some other OAuth service providers.
3. OAuth Approval Page & Phishing
Another topic that will likely come up when you developer your UI for OAuth is that the user experience may look like phishing. Imagine for example that the user is not logged into your site, i.e. the service provider, and they start the OAuth flow from a startup. The user will have clicked on a button that says something like "click here to give us access to your address book" and in the proper OAuth flow your site will then show them a login page. After they user logs in, you will then show them your OAuth approval page. Unfortunately the startup could phish the user by not redircting them to your site when they first start the process, but instead send them to a page they control that looks like your login page. Once the user has submitted their login credentials there, they can then redirect the user to your website.
While it is true that this phishing technique can be used, the unfortunate reality is that end-users are already giving their login information to startups doing screen-scraping or using "desktop" APIs. So don't let "the perfect be the enemy of the good."
4. OAuth and OpenSocial
Another source you might look at for your UI approval page are social networks like Facebook or networks that support the OpenSocial standard. These networks allow users to add applications, and give those applications access to some of their data. As an example, here is a blog entry from MySpace that discusses their approval flow. Scroll down to the second screenshot for an example.
http://developer.myspace.com/Community/blogs/devteam/archive/2008/06/30/quick-update-on-acc.aspx
Most of the options just control what APIs and data the application has access to, i.e. the user's contact list, activity stream, photos, etc,
However they also provide some additional options to the user in addition to the ones listed in section two above. These include:
Showing a link to this application from the service providers site to make it easy for the user to visit it
Allowing the user's friends to see that the end-user has added this application
As you can imagine, the startups building these applications love having this visibility, and potential for getting new users. The general OAuth Practices section discussed the potential for your company to develop a positive relationship with these startups that helps both companies. The OpenSocial experience is a good example of such a relationship.
5. OAuth management page
Once the user has delegated access to some 3rd party site, you should also consider providing a way for them to review those delegations, and modify them. Google provides a simple one which simplest lists the OAuth consumers along with the data they can access, and the option to revoke that access. This management page is available from the same place a user would change their password.
Google Health provides a more advanced management page which lets the user see what websites have access to a particular health profile, and with what level of access. It also shows the last time the 3rd party accessed the user's data.
To see other examples, try the websites of other service providers that support web delegation APIs.
6. OAuth in Apps
As applications make more advanced use of web delegation APIs like OAuth, it is also possible to surface information about OAuth within individual applications. In section 4 above we already described how social networks show information about what applications a user has subscribed to. Below is a screenshot from Google Health which also shows what 3rd party sites have access to an end-user's health profile.
Both social networks and Google Health also have the concept of activity streams which allows these 3rd party applications to post information back to the OAuth service provider. In the case of a social network that activity stream is usually shared with an end-user's "friends" whereas on Google Health that information is only shared with specific medical institutions or 3rd parties to whom the end-user has delegated access to read their Health profile. These "activity streams" or "notices" can be thought of like secure E-mail inboxes because they receive messages from 3rd parties, but they are "secure" because they are not susceptible to spam or impersonation like standard E-mail systems.
In the OAuth Practices section we discussed "claims, reputations & assertions." As an example, the screenshot from Google Health below show a structured summary of all the secure messages send to the user's Health profile, along with the source of each individual assertion, such as medical conditions. If another hospital is given permission by the user to download their Health profile, then that hospital can see the source of these assertions and potentially decide to trust them (depending on its business practices and its trust of Google and the original data source).
7. Valdiating your OAuth implementation
Because OAuth is a recent standard, your company might also be looking for ways to validate that your implementation properly follows the OAuth standard. One way to do that is to use the OAuth Proxy in iGoogle. A number of companies who are OAuth service providers have already been built gadgets on iGoogle that connect back to their OAuth enabled APIs as a form of interoperability testing. Your company can do this as well.
In fact, because the gadget specification is now available open source in the Apache Shindig project, your company might also consider leveraging gadgets in your own applications. For example, if a startup pulls data from your sites to build a mashup, then they might want to build a gadget that will run on your site to show the end-result of that mashup, and the gadget could in turn connect back to the startup's website using OAuth.
8. Conclusion
Hopefully this information helps you think about the steps needed to become an OAuth service provider. If you have suggestions on how to improve this guide, please send mail to the OAuth standards mailing list, or contact esachs at Google.