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.
1.1. Requirements notation
2.2. Relying Party (RP)
2.3. Identity Provider (IdP)
2.4. AccountChooser (AC)
2.5. AccountChooser Storage
2.6. Display Name
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
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 document specifies the API and some non-functional requirements which are essential to the usefulness of AccountChooser.
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.).
For the purpose of this specification, the following terms are defined.
Collection of information used to aid a user in signing in.
Party that relies on an external service for the user claims including the information about the user authentication events.
Entity that authenticates the user and provides the information about the user to the Relying Party (Relying Party (RP)).
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.
Persistent database maintained by the AccountChooser (AccountChooser (AC)) software, containing zero or more Accounts (Account).
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
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.
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.
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.
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.
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:
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.
The following sections describe the configuration arguments; the title of each is the name of the argument, followed by its default value in parentheses.
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)
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.
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))).
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.
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.
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))).
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.
Identifies the HTML “id” attribute value identifying the field in the “loginUrl” and “signupUrl” pages where a user would enter their email address.
Identifies the HTML “id” attribute value identifying the field in the “loginUrl” and “signupUrl” pages where a user would enter their password.
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.
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.
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:
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).
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.
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.
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.
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.
This specification makes no request to IANA registry.
|[RFC2119]||Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).|
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
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.