| P. Dingle | |
| Ping Identity | |
| T. Bray | |
| Google Inc. | |
| July 20, 2015 |
OpenID AccountChooser Basic API Profile 1.0
draft-accountchooser-basic-profile-06
AccountChooser is a facility where users can store basic identifying information for accounts that they use for signing in to Web sites (Sites). Once stored, users are able to use the AccountChooser user interface to transmit simple account hint information such as email addresses or federated issuer identifiers to sites rather than typing that information manually into login or signup forms.
This specification standardizes a simple JavaScript interface that can be offered by an AccountChooser, enabling Sites to embed AccountChooser functionality into login and signup pages, and allowing Sites to push new Account Records into the Chooser, through the manipulation of a JSON object passed as a javascript variable to an API maintained by the Chooser, removing the need for Sites to write code.
For developers wishing to build or deeply integrate with an AccountChooser programatically, or for a deeper understanding of hot and cold choosers, storage best practices and privacy recommendations, see the OpenID AccountChooser Developer Specification 1.0 document.
The most common representation of a relationship between a user and a web site today is an account - a collection of attributes and settings, organized around a unique identifier such as an email address, and protected by a locally stored credential, most often a password. Creation, use, and management of accounts are tedious and repetitive activities, as users end up typing the same information over and over again. Often users can feel challenged to recall which set of identity information has been supplied to which site.
In addition to account management, sites may optionally offer federated account options, where the site does not store a credential for the account directly, but instead relies on another service (such as a social network or corporate federation service) to validate the identity of the user. In this case, a user returning to a site may not only need to remember which username they used with a site, but also which federated identity provider they linked to the site.
From the perspective of a user, an AccountChooser is a place where the user can store records of their different accounts, and reuse those records easily across multiple sites. The visual nature of an AccountChooser provides additional cues to remember which identities are stored where, and the act of "choosing" rather than typing means that login and sign-up are faster and less error-prone. The AccountChooser can be queried by sites, and while the user sees all the account records they might want to pass back to the site for the purposes of login or sign-up, the site only receives the identity information that the user chooses.
From the perspective of a site, the chooser is a way to help users remember their login information, thus reducing the likelihood of account abandonment and decreasing drop-off that may occur during login and signup. By embedding the AccountChooser Javascript into login and signup pages, the site is able to populate those pages with Account Record information received from the AccountChooser rather than directly from the user.
This document standardizes a design pattern for behavior of an AccountChooser and for a javascript-specific interaction between a Site and an Account Chooser. A conformant AccountChooser exists today at <https://accountchooser.com>. All examples derive from this reference implementation.
+--------------------------------------+ +----------------------+
| AccountChooser | |AccountChooser Storage|
| | | |
| +----------------+ +--------------+ | | +----------------+ |
| | AccountChooser | | storeAccount | | | | Account Record | |
| | Page | | Page | | | +----------------+ |
| +----------------+ +--------------+ |<-->| |
| +-------------+ | | +----------------+ |
| | ac.js | | | | Account Record | |
| +-------------+ | | +----------------+ |
| ^ ^ | | |
+------------------|---|---------------+ | +----------------+ |
| | | | Account Record | |
+--------+ +-----------+ | +----------------+ |
| | +----------------------+
| |
+----------------------+ +-----------------------+
| <script src="ac.js"> | | <script src="ac.js"> |
| | | |
| +-----------------+ | | +-------------------+ |
| | Primary Account | | | | Federated Account +----------+
| +-----------------+ | | +-------------------+ | |
| | | | +-------------+
| +-----------------+ | | +-------------------+ | | +---------+ |
| | Primary Account | | | | Primary Account | | | | Primary | |
| +-----------------+ | | +-------------------+ | | | Account | |
| | | | | +---------+ |
| Site | | Site | | +---------+ |
+----------------------+ +-----------------------+ | | Primary | |
| | Account | |
| +---------+ |
| |
| Site |
| (Identity |
| Provider) |
+-------------+
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].
For the purpose of this specification, the following terms are defined.
A collection of information used to aid a user in signing in.
An account that is validated directly at the site, for example by prompting the user for a password.
An account that is not validated directly at the site, but instead validated by an external entity such as a social network or a corporate IAM system, using identity standards.
A tightly limited set of account attributes stored by an AccountChooser and passed to a Site.
A website or other service at which users have accounts. Accounts may be primary accounts or federated accounts.
Mechanism to remember, on behalf of a person using a browser, the Accounts they used to sign in to Web sites so that rather than typing in usernames, they need only pick an account from a list.
NOTE: The user is presented a list of her own Accounts so that she need only pick one from the list rather than typing in a username to login.
A persistent database maintained by the AccountChooser, containing zero or more Account Records.
Javascript file invoked by the Account Holder that performs AccountChooser tasks.
The script element used at the Site to invoke ac.js. The example file reference used in this document is <script type="text/javascript" src="https://www.accountchooser.com/ac.js" />
A JSON object that accompanies an ac.js call and passes parameters from the site to the AccountChooser.
A JSON object that represents the current state of the account at the site.
The account record attribute that uniquely identifies the user. This specification uses the email field as the User Claimed Identifier.
A human-readable name for the person associated with the user claimed identifier.
A URL identifying the service capable of validating the account referenced in the account record. In the case where the service specified by the Provider ID is not the Account Holder service, the Account Holder will likely make a federated call to the service indicated in order to validate the account, rather than locally validating the account.
An account record is a collection of attributes that are passed between Sites and Account Choosers during invocation of the AccounChooser JavaScript. Examples of account record operations include requesting an account record to be chosen, checking the status of a chosen account record against an existing account at a site, or requesting that a new account record be stored. The AccountChooser negotiates with the user to complete those requests.
An Account Record is represented by up to four pieces of information.
| name | type | default value | description |
|---|---|---|---|
| string | N/A | Email address and user claimed identifier. | |
| displayName | string | N/A | Display Name. |
| photoUrl | string | N/A | A URI from which a photo of the person can be fetched. Must use the HTTPS scheme. |
| providerId | string | N/A | Domain name identifying a federated Identity Provider. |
The account record storage object is a JSON object containing between one and four text-based attributes.
An example of an account record, shown as a JSON object, is shown below:
<script type="text/javascript">
accountchooser.CONFIG.storeAccount = {
email: "nikhil_corlett@yahoo.com",
displayName: "Nikhil Corlett",
photoUrl: "https://example.com/nikhil_corlett.jpg"
providerId: "identity.example.com" };
</script>
Upon receipt of an account record, the receiver MUST:
When an account record is passed to ac.js in the storeAccount variable, the following restrictions apply. The store account context is described in Section 9.
The method by which a site interacts with AccountChooser is a JavaScript file named ac.js, which performs a variety of tasks depending on where it is called from, and can be customized with configuration arguments.
The ac.js file may either be hosted with the site domain, or referenced remotely from the AccountChooser domain. This guide uses the default convention of a remotely referenced file from https://www.accountchooser.com/ac.js.
Sites trigger user interaction with the AccountChooser by invoking the ac.js file from three different user contexts: user signup, user login, and after successful user authentication (generally from the authenticated home page). In addition, a programmatic status checker URL can be implemented by the Site.
The AccountChooser ac.js file establishes the following javascript variables:
Values of the accountchooser.CONFIG variable represent configuration parameters sent from the Site to the AccountChooser at the time the ac.js file is invoked. The contents of accountchooser.CONFIG must conform to the elements listed below:
Note: The value of a URL parameter (loginUrl, signupUrl, userStatusUrl, or homeUrl) can be an absolute URL or a relative reference [RFC3986]. Relative references are resolved against the URL of the web page.
Following is the list of the configuration parameters:
| name | type | default value | description |
|---|---|---|---|
| loginUrl | string | 'account-login' | Location of the primary login form |
| signupUrl | string | 'account-create' | Location of the user registration page. |
| userStatusUrl | string | 'account-status' | Location of the home web page. |
| homeUrl | string | '/' | Location of the user registration page. |
| siteEmailId | string | 'email' | Email input field ID (HTML id= attribute value) in the signup and login forms. |
| sitePasswordId | string | 'password' | Password input field ID in the signup and login forms. |
| siteDisplayNameId | string | 'displayName' | Display name input field ID in the signup form. Can be set to null or empty if your signup form does not need the user's name. |
| sitePhotoUrlId | string | 'photoUrl' | Profile photo URL input field ID in the signup form. Can be set to null or empty if your signup form does not need the user's profile picture. |
| mode | string | N/A | Mode for the current page. The possible values are 'login' and 'signup'. ac.js normally sets the mode by checking the current URL against the loginUrl and signupUrl parameters, but this parameter may be used to override that behavior.//TODO: are absolute URLs outside of the current origin allowed? |
| uiConfig | object | N/A | Interface customization object (defined in Section 4.2) |
| language | string | 'en' | The display language of the AccountChooser page. |
| providers | list of strings | 'en' | List of supported Identity Providers, usually given by top-level domain name, for example facebook.com. //TODO add xref to place where providers list is defined |
| storeAccount | object | N/A | Triggers the storage of an Account Record Object (defined in Section 3.1). |
The value of the uiConfig parameter is a JSON object whose members may be used to control the appearance of the AccountChooser Page. They are:
| name | type | default value | description |
|---|---|---|---|
| title | string | N/A | Suggested title for AccountChooser Window/Tab (note this is window title not page title). |
| favicon | string | N/A | URI identifying a favicon to display in the address bar of theAccountChooser Page. |
| branding | string | N/A | URI identifying a resource with media-type text/html to be displayed on the AccountChooser page as visual identification of the site. MUST be HTTPS. |
An example interface configuration object:
accountchooser.CONFIG.uiConfig = {
title: 'Sign in to Example.com',
favicon: 'https://example.com/favicon.ico',
branding: 'https://example.com/branding/ac-blurb.html'
}
To successfully integrate AccountChooser into a site, the site will modify two existing pages, and create two new pages that execute transparently to the user.
The site MUST modify:
The site MUST create:
The site MAY create:
Other pages are specified by the site as redirection targets, however these pages do not contain references to ac.js and do not interact with AccountChooser.
When ac.js is embedded into a login page and configured with the correct CONFIG object, the user experience is only interrupted in the case where account records exist in the user's AccountChooser. In the case where there are no records, ac.js immediately exits, leaving the user to authenticate without assistance. Once that authentication occurs, the site can then make an Account Record Insertion request, such that the next time the user visits the Login Page, they will have an account record populated.
The following <script> objects MUST be placed into the web page such that they will be executed prior to the population of the returned page:
The site SHOULD place the objects in the HEAD element of the web document. The site MAY place the object in the BODY element of the document, but the scripts MUST occur prior to display of any page elements.
The site MUST perform the following configurations:
The site SHOULD place the objects in the HEAD element of the web document. The site MAY place the object in the BODY element of the document, but the scripts MUST occur prior to display of any page elements.
The site MAY perform the following configurations:
A non-normative example of a fully specified login page:
<html>
<head>
<script type="text/javascript" src="https://www.accountchooser.com/ac.js" />
<script type="text/javascript">
accountchooser.CONFIG={
loginUrl: "utils/mysitelogin",
mode: "login",
siteEmailId: "form_username",
sitePasswordId: "form_password" };
</script>
</head>
<body>
<form>
<input id="form_username" type="text" />
<input id="form_password" type="password" />
<input id="submit" type="submit">Login</input>
</form>
...
When ac.js is embedded into a signup page and configured with the correct CONFIG object, the user experience is only interrupted in the case where account records exist in the user's AccountChooser. In the case where there are no records, ac.js immediately exits, leaving the user to sign up without assistance. Once the registration is complete, the site can then redirect to the store account page, ensuring that the next time the user visits the site, an account record will be populated.
The following elements MUST be placed into the web page such that they will be executed prior to the population of the returned page:
The site SHOULD place the objects in the HEAD element of the web document. The site MAY place the object in the BODY element of the document, but the scripts MUST occur prior to display of any page elements.
The site MUST perform the following configurations:
The site MAY perform the following configurations:
A non-normative example of a signup page:
<html>
<head>
<script type="text/javascript" src="https://www.accountchooser.com/ac.js" />
<script type="text/javascript">
accountchooser.CONFIG={
loginUrl: "utils/register_now",
mode: "signup",
siteEmailId: "form_username",
sitePasswordId: "form_password",
siteDisplayNameId: "form_displayame",
sitePhotoUrlId: "form_avatar_location" };
</script>
</head>
<body>
<form>
<input id="form_username" type="text" />
<input id="form_displayname" type="text" />
<input id="form_avatar_location" type="text"/>
<input id="form_password" type="password" />
<input id="form_confirmpassword" type="password" />
<input id="submit" type="submit">Login</input>
</form>
...
The User Status Page is invoked by the AccountChooser after a user chooses an Account Record. The outcome of the User Status check determines which page the user is redirected to (the Login Page, the Signup Page, or possibly a Federated Identity Provider).
The site MUST implement a user status page.
The AccountChooser will perform an HTTP POST to the URL specified in the userStatusUrl. If no value is set for userStatusUrl, the AccountChooser will POST to the relative reference noted as the default value for userStatusUrl in section 4.2. The following parameters are sent in the HTTP POST: //TODO - what exact format? Are these separate parameters or one single JSON object
//TODO - this is repetitive, rework
The following objects MUST be placed into the web page header such that they will be executed prior to the population of the returned page:
A non-normative example of a User Status Page with AccountChooser integration:
<html>
<head>
<script type="text/javascript" src="https://www.accountchooser.com/ac.js" />
<meta http-equiv="content-type" content="application/json">
</head>
<body>
...
The response body MUST be a JSON object conforming to [RFC4627] containing ONE of the following parameters:
The site MUST NOT return content other than the User Status object. Following are non-normative examples of the User Status object.
{ "registered":true }
Example 1: The user is registered with a password
{ "registered":false }
Example 2: The user is not currently registered at the site
{ "authUri":"https://idp.example.com/auth/" }
Example 3: The user is registered with a federated identity
//TODO: what about error conditions? What does the Account Status Page do if the account record is malformed?
The store account page is hosted at the Site, and invoked to create or update a user's record in the AccountChooser. The site SHOULD implement the store account page, unless that function is known to be delegated to a Federated Identity Provider. Once the account record has been stored, the AccountChooser will redirect the user to the value specified in the homeUrl variable.
The site SHOULD invoke the StoreAccount Page under two circumstances:
The following elements MUST be placed into the web page such that they will be executed prior to the population of the returned page:
The site MAY populate the accountchooser.homeUrl variable to alter the location where the AccountChooser will redirect after account storage is complete. The Site MUST NOT place any other content into body of the web page, as control will not be returned to the page.
<html>
<head>
<script type="text/javascript" src="https://www.accountchooser.com/ac.js" />
<script type="text/javascript">
accountchooser.CONFIG.homeUrl = "./welcomepage.html";
accountchooser.CONFIG.storeAccount = {
email: "nikhil_corlett@yahoo.com",
displayName: "Nikhil Corlett",
photoUrl: "https://example.com/nikhil_corlett.jpg"
providerId: "identity.example.com" };
</script>
</head>
<body>
...
A non-normative example of a Store Account Page:
Sites MAY configure the Interface Configuration Object and pass it to the AccountChooser to brand content displayed by the AccountChooser. For security reasons, The AccountChooser will not load any content containing executable code, or served over an unencrypted transport layer. At least one of the following json elements MAY be placed into the accountchooser.CONFIG.uiConfig variable:
<?php
header('Content-Type: text/html');
header("Access-Control-Allow-Origin: *");
header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
header('Access-Control-Max-Age: 86400');
header('Access-Control-Allow-Credentials: true');
?>
<html>
<body>
<p>Example of text to be displayed on the AccountChooser page</p>
</body>
</html>
A non-normative example of a branding page:
If a Site supports federated login, AccountChooser can be used both to identify a user account and the Identity Provider it is associated with. This simultaneous user and IDP discovery process can simplify the user experience.
Sites MAY implement federated account support. Any requirements noted in this section are only applicable to those sites that do implement federated support.
Configuration of the login page AccountChooser script can be augmented to inform AccountChooser about which Identity Providers are supported by the site, so that the AccountChooser can hide Account Records that would otherwise result in an error if chosen.
The site MAY populate the providers variable in the login page or signup page accountChooser.CONFIG object. If the providers variable is populated, the value MUST be a JSON array containing one or more string values. The values populated within the providers value SHOULD directly correlate to the list of federated providers supported by the site.
If a site populates the providers variable, that site SHOULD also be capable of supplying a response to the AccountChooser containing an authentication URI for the provider when requested during the user status check.
<html>
<head>
<script type="text/javascript" src="https://www.accountchooser.com/ac.js" />
<script type="text/javascript">
accountchooser.CONFIG.loginUrl="utils/mysitelogin";
accountchooser.CONFIG.providers = [ "yahoo.com", "facebook.com" ];
</script>
</head>
<body>
...
A non-normative example of a login page augmented with an identity provider filter list:
AccountChooser is capable of initiating federated login requests on behalf of the site. To initiate a federated login, the site passes a response to the AccountChooser during the user status check that instructs the AccountChooser as to where to redirect the browser.
The site MAY initiate a federated request via the AccountChooser by returning a response body during user status check that contains the authUri element, rather than the registered element
{ "authUri":"https://idp.example.com/auth/"}
A non-normative example of an authUri returned from a user status check:
This section includes Privacy-Specific threats described in section 5.2 of [RFC6973].
Whatever domain hosts the ac.js script has the opportunity to extract account records for the purposes of correlation outside of what is specified by this document. It is RECOMMENDED that Sites only include an Account Chooser file reference operated by a trusted third party domain with an appropriate privacy and security policy.
Sites SHOULD ensure that all interactions with an AccountChooser, including the ac.js file reference all occur over a TLS-protected channel.
Sites MUST NOT request account records for any reason other than facilitation of login or sign up.
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. The site MUST NOT include any values in the HTML that contain executable commands, including but not limited to JavaScript, HTML, or CSS exploits.
Sites MUST NOT attempt to create records in the AccountChooser that do not correspond to actual accounts.
This specification makes no request to IANA registry.
| [ISO639] | International Organization for Standardization, "ISO 639-1:2002. Codes for the representation of names of languages -- Part 1: Alpha-2 code", 2002. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005. |
| [RFC4627] | Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, DOI 10.17487/RFC4627, July 2006. |
| [RFC6973] | Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M. and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, DOI 10.17487/RFC6973, July 2013. |
The OpenID Community would like to thank the following people for the work they have done in the drafting and editing of this specification.
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.