TOC 
DraftT. Bray
 Google Inc.
 February 1, 2014


The AccountChooser API

Abstract

The central AccountChooser provides local storage for information about which accounts a person has used to log in to Web sites; included are (at least) email address, and (optionally) a human-readable form of the person's name, a link to a photograph, and the identifier of an Identity Provider.

This document describes the interfaces by which a site may use AccountChooser to simplify people's sign-in experience as well as the requirements to ac.js that implements such mechanisms.



Table of Contents

1.  Introduction
    1.1.  Requirements notation
2.  Terms
    2.1.  Account
    2.2.  Relying Party (RP)
    2.3.  Identity Provider (IdP)
    2.4.  AccountChooser (AC)
    2.5.  AccountChooser Storage
    2.6.  Display Name
3.  Accounts
4.  AccountChooser Invocation
5.  AccountChooser Behavior
    5.1.  Arrival at Site
    5.2.  User Chooses To Create New Account
    5.3.  User Chooses an Account
    5.4.  User Is Signed In
6.  Configuration Arguments
    6.1.  homeUrl (/)
    6.2.  language (en)
    6.3.  loginUrl (/account-login)
    6.4.  mode ()
    6.5.  providerIds ([])
    6.6.  signupUrl (/account-create)
    6.7.  siteDisplayNameId (displayName)
    6.8.  siteEmailId (email)
    6.9.  sitePasswordId (password)
    6.10.  sitePhotoUrlId (photoUrl)
    6.11.  storeAccount ()
    6.12.  uiconfig ()
    6.13.  userStatusUrl (/account-status)
7.  Privacy Considerations
8.  Security Considerations
    8.1.  Branding Content
    8.2.  Compromised AccountChooser Storage
    8.3.  User/RP Connection Tracking
    8.4.  Domain Compromise
9.  IANA Considerations
10.  Normative References
Appendix A.  Acknowledgements
Appendix B.  Notices
§  Author's Address




 TOC 

1.  Introduction

The goal of the AccountChooser is to remember, on behalf of a person using a browser, the accounts they use to sign in to Web sites. Then, rather than typing in usernames, they need only pick an account from a list.

The intent of the design is that multiple different apps can share read and write access to the AccountChooser to simplify and speed up the process of getting its human user signed in.

This API covers the interaction between the AccountChooser and an app which wants to use it. The API takes the form of a JavaScript file invocation, with a variety of configuration arguments.

This document specifies the API and some non-functional requirements which are essential to the usefulness of AccountChooser.



 TOC 

1.1.  Requirements notation

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).



 TOC 

2.  Terms

For the purpose of this specification, the following terms are defined.



 TOC 

2.1.  Account

Collection of information used to aid a user in signing in.



 TOC 

2.2.  Relying Party (RP)

Party that relies on an external service for the user claims including the information about the user authentication events.



 TOC 

2.3.  Identity Provider (IdP)

Entity that authenticates the user and provides the information about the user to the Relying Party (Relying Party (RP)).



 TOC 

2.4.  AccountChooser (AC)

Mechanism to remember, on behalf of a person using a browser, the Accounts (Account) they used to sign in to Web sites so that rather than typing in usernames, they need only pick an account from a list.



 TOC 

2.5.  AccountChooser Storage

Persistent database maintained by the AccountChooser (AccountChooser (AC)) software, containing zero or more Accounts (Account).



 TOC 

2.6.  Display Name

Human-readable name for the person associated with the user claimed identifier.

NOTE: In this specification, email address is used as the user claimed identifier



 TOC 

3.  Accounts

In this document, Accounts (Account) means a collection of information used to aid a user in signing in. An Account (Account) contains up to four pieces of information, all character strings. It MUST contain an email address (referred to in the API as “email”). It SHOULD contain a a human-readable name for the person associated with the email address (“displayName”) and a URI from which a photo of the person may be fetched ("photoUrl"). It MAY contain a domain name identifiying an Identity Provider which may be used to sign in the email address (“providerId”).

In this document, “AccountChooser Storage” means the persistent database maintained by the AccountChooser software, containing zero or more Accounts.



 TOC 

4.  AccountChooser Invocation

To use AccountChooser, an app links to a JavaScript source file named ac.js using the <script> element in an HTML page

ac.js MAY be hosted on any server, but to achieve the effect of a shared memory for accounts, it SHOULD be be linked to at accountchooser.com with JavaScript similar to this:

<script type="text/javascript" src="https://www.accountchooser.com/ac.js" ></script>


 TOC 

5.  AccountChooser Behavior

The discussion in this section describes behavior caused by ac.js. The behavior is that of a Browser, which is assumed to be a Web browser capable of rendering HTML markup and interpreting JavaScript code, which is processing a “text/html” resource representation containing a link to ac.js as described in Section 4 (AccountChooser Invocation).

The proper working of AccountChooser imposes some requirements upon the behavior of ac.js and other requirements upon the behavior of the site that is using it; in this document, that site is called “the RP”, for Relying Party.

The discussion uses terms such as “loginUrl”, “signupUrl”, which are called Configuration Arguments. Some may be described briefly in this section but are fully specified in the next section.



 TOC 

5.1.  Arrival at Site

When the Browser arrives at the “loginUrl” page for any reason other than an AccountChooser redirect (see Section 5.3 (User Chooses an Account)), and if there are any Accounts in the AccountChooser, ac.js MUST redirect the Browser to an HTML page, in this document called the “AccountChooser Page”, containing:

If there are no Accounts in the AccountChooser, ac.js MUST NOT perform this redirect, but MUST simply display the content of the “loginUrl” page.



 TOC 

5.2.  User Chooses To Create New Account

If the user chooses chooses the AccountChooser Page's option to create a new account, ac.js MUST redirect the Browser to the “loginUrl” page and render it.



 TOC 

5.3.  User Chooses an Account

If the user chooses one of the Accounts from the AccountChooser Page, ac.js MUST redirect the Browser in such a way as to cause an HTTP POST to the “userStatusUrl” page. The POST has no body, but the names and values of the fields in the chosen Account are provided as URL query parameters. The “email” field will always be provided.

The RP MUST return HTTP status 200 from the “userStatusUrl” in response to this POST, and a response body with media-type “application/json”, containing one of three possible results:



 TOC 

5.4.  User Is Signed In

When a user is signed in successfully, the RP SHOULD redirect to a page containing a link to ac.js and with the “storeAccount” Configuration Argument (see Section 6.11 (storeAccount ())) loaded with an Account containing fields about the signed-in user.

When the “storeAccount” Configuration Argument is provided, ac.js MUST check to see if there is an Account in the AccountChooser Storage with matching email and if so, may update the AccountChooser Storage.

If the AccountChooser Storage is updated in any way, ac.js MUST first redirect the Browser to a page describing the change to be made to AccountChooser Storage, and asking for the user's consent to that page. If the user witholds consent, ac.js MUST NOT update AccountChooser Storage. This process is called “conditional update” of AccountChoose Storage.

If there is no Account with the email provided by the RP, ac.js MUST create and conditionally store a new Account containing all the fields provided by the RP.

If there is an Account with the email provided by the RP, ac.js MUST use fields provided by the RP to conditionally update the AccountChooser Storage in the following circumstances.

Whether or not the AccountChooser storage has been updated, ac.js MUST finally redirect the Browser to the “homeUrl” page.



 TOC 

6.  Configuration Arguments

Configuration arguments affect the operation of AccountChooser. Most have default values, provided in this section. JavaScript code embedded in an HTML page sets values by assigning to fields in a JavaScript object named “accountchooser.CONFIG”, for example as follows:

<script type="text/javascript" src="https://www.accountchooser.com/ac.js" ></script>
<script type="text/javascript">
accountchooser.CONFIG.homeUrl = "/myAppHome";
</script>

Or, alternately:

<script type="text/javascript" src="https://www.accountchooser.com/ac.js" ></script>
<script type="text/javascript">
accountchooser.CONFIG = {
  "homeUrl" : "/myAppHome",
  "userStatusUrl" : "/checkAccount"
};
</script>

The following sections describe the configuration arguments; the title of each is the name of the argument, followed by its default value in parentheses.



 TOC 

6.1.  homeUrl (/)

Identifies the RP’s home page, where a signed-in user would normally start their work. ac.js is required to redirect the Browser to this page upon successful signin; see Section 5.4 (User Is Signed In)



 TOC 

6.2.  language (en)

Requests that the AccountChooser Page be displayed in a particular language. ac.js SHOULD support a wide range of human languages, identified by standard two letter codes such as “ca” for Catalan and “zh_CN” for Simplified Chinese.



 TOC 

6.3.  loginUrl (/account-login)

Identifies the login page. This specification requires certain behaviors for ac.js when arriving at this page; see Section 5 (AccountChooser Behavior).

This page SHOULD contain an HTML form with input fields for a user to sign in with an email and password (see the discussion of “siteEmailId” in Section 6.8 (siteEmailId (email)) and “sitePasswordId” in Section 6.9 (sitePasswordId (password))).



 TOC 

6.4.  mode ()

The possible values are are “login” and “signup”. If the value is “login”, ac.js MUST NOT redirect the browser from the “loginUrl” page, but render it and allow the user to proceed with sign-in. If the value is “signup”, ac.js MUST redirect the Browser to the “signupUrl” page.

Normally, the behavior of ac.js is based on checking the current page against the “loginUrl” and “signupUrl” values as described in Section 5 (AccountChooser Behavior), but this Configuration Argument may be used to override the default behavior.



 TOC 

6.5.  providerIds ([])

The value of this Configuration Argument MUST be a JSON list, containing strings identifying Identity Providers by their top-level domains, for example “facebook.com” and “yahoo.com”.

When ac.js generates the AccountChooser Page, it MUST NOT include any Accounts which include a “providerId” field which does not appear in the provided list.



 TOC 

6.6.  signupUrl (/account-create)

Identifies the new-account sign-up page. In certain cases, ac.js is required to direct users to this page; see Section 5 (AccountChooser Behavior).

This page SHOULD contain an HTML form with input fields for a user to sign in with an email and password (see the discussion of “siteEmailId” in Section 6.8 (siteEmailId (email)) and “sitePasswordId” in Section 6.9 (sitePasswordId (password))). It MAY contain input fields to provide entry of human-readable name and a link to a picture (see the discussion of “siteDisplayNameId” in Section 6.7 (siteDisplayNameId (displayName)) and “sitePhotoUrlId” in Section 6.10 (sitePhotoUrlId (photoUrl))).



 TOC 

6.7.  siteDisplayNameId (displayName)

Identifies the HTML “id” attribute value identifying the field in the “loginUrl” and “signupUrl” pages where a user would enter a human-readable form of their name.



 TOC 

6.8.  siteEmailId (email)

Identifies the HTML “id” attribute value identifying the field in the “loginUrl” and “signupUrl” pages where a user would enter their email address.



 TOC 

6.9.  sitePasswordId (password)

Identifies the HTML “id” attribute value identifying the field in the “loginUrl” and “signupUrl” pages where a user would enter their password.



 TOC 

6.10.  sitePhotoUrlId (photoUrl)

Identifies the HTML “id” attribute value identifying the field in the “loginUrl” and “signupUrl” pages where a user would enter a link to an image of themselves.



 TOC 

6.11.  storeAccount ()

This Configuration Argument is actually a directive, instructing AccountChooser to conditionally update the AccountChooser storage; for details, see Section 5.4 (User Is Signed In).

The value MUST be a JSON object, describing the fields of an Account. It MUST include an “email” field and MAY include “displayName”, “providerId”, and “photoUrl” fields.



 TOC 

6.12.  uiconfig ()

The value of this Configuration Argument is a JSON object whose members may be used to control the appearance of the AccountChooser Page. They are:



 TOC 

6.13.  userStatusUrl (/account-status)

Identifies the page where ac.js sends a POST when a user selects an Account from the AccountChooser display. For details, see Section 5.3 (User Chooses an Account).



 TOC 

7.  Privacy Considerations

The Accounts in the AccountChooser Storage MUST NOT be transmitted over any network connection.

The RP MUST NOT be informed of the content of any Account unless a user has consented by clicking on that Account on the AccountChooser page.

ac.js MUST NOT perform any updates to the AccountChooser Storage unless explicitly approved by the user; see Section 5.4 (User Is Signed In).

The information concerning which Accounts have been used by which user for which RP MUST NOT be made available to any human or software program.



 TOC 

8.  Security Considerations



 TOC 

8.1.  Branding Content

The “branding” field in the “uiconfig” Configuration Argument causes ac.js to fetch arbitrary HTML and attempt to display it in the context of the AccountChooser page. An attacker could use this to inject JavaScript, HTML, or CSS exploits to compromise AccountChooser security.

Therefore, AccountChooser implementations MUST aggressively filter the HTML content identified by the “branding” URI to ensure at least that no JavaScript can execute and to reduce the probability of other exploits.



 TOC 

8.2.  Compromised AccountChooser Storage

A significant failure of AccountChooser Storage security would result in disclosure of the information in each of the Accounts stored there, and also implicitly of the fact that each Account has been used to log in to at least one RP.

While the information in an Account is Personally-identifying, it is not, generally speaking, very sensitive; email addresses are generally quite easily discoverable, as are the linkages between those addresses and display-names, or images of the person involved.

Disclosure of the connection between an email address and the IDP used to log it in could simplify the job of an attacker trying to compromise those accounts at the IDP, because they would know the username part of the username/password combination.



 TOC 

8.3.  User/RP Connection Tracking

If an attacker were to defeat this specification’s requirement that the mapping of which Accounts have been used for which RPs, the attacker would know which accounts have been used for which sites. This could simplify the job of an attacker trying to compromise those accounts, because they would know the username part of the username/password combination.

In some situations, the information showing which RPs a user has signed into might be compromising or damaging to the user. In such situations, users might consider not using AccountChooser for sign-in, and sites for which this is likely to be true might consider not offering AccounChooser-based sign-in.



 TOC 

8.4.  Domain Compromise

The initial AccountChooser implementation required the use of domain-specific browser-based storage to achieve several of the non-functional and privacy requirements of this specification, where the domain in question is “accountchooser.com”. An attacker who arranged to control the resources served from “accountchooser.com” could completely subvert all the privacy and security requirements of this specification. This could be accomplished by subverting the DNS mapping of the “accountchooser.com” domain name, or by seizing control of the server at that address.

Thus, secure operation of the AccountChooser requires careful attention to the secure management of the site’s domain name and server.



 TOC 

9.  IANA Considerations

This specification makes no request to IANA registry.



 TOC 

10. Normative References

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).


 TOC 

Appendix A.  Acknowledgements

The OpenID Community would like to thank the following people for the work they have done in the drafting and editing of this specification.

Nat Sakimura -- Nomura Research Institute



 TOC 

Appendix B.  Notices

Copyright (c) 2013 The OpenID Foundation.

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.



 TOC 

Author's Address

  Tim Bray
  Google Inc.
Email:  tbray@textuality.com