Identity Scenario 2.0 Draft 3


February 20, 2012

Abstract

This document describes a Backplane application scenario that allows widgets to exchange identity information about authentication events.

Table of Contents

1. Introduction 1.1. Definitions 1.2. Requirements Language 2. Protocol Flow 2.1. User Login 2.2. User Logout 2.3. Identity Information Update 2.4. Page Load 3. Message Types 3.1. identity/login 3.2. identity/logout 3.3. identity/update 4. Identity Information 4.1. Account Identifier 4.2. User Profile 4.3. Access Credentials 4.4. Linked Accounts 4.5. Extensibility 4.6. Update 5. Use Cases 5.1. User Login 5.2. User Logout: Identity Provider 5.3. User Logout: Site Local 5.4. Web Page (Re)Load 6. Normative References § Authors’ Addresses

 
 TOC 

1. Introduction

Login widgets can facilitate user authentication against third-party identity providers and then use Backplane to publish the authenticated identifiers, details about the authentication event and user profile data for the other widgets on the page to consume.
 TOC 

1.1. Definitions

[[[ TODO: remove draft reference ]]] In addition to the terms defined by [Backplane2.0] (Saad, C., Skvortsov, V., Lukyanov, Y., Zhuravlev, A., Glushkov, I., Howells, C., and J. Bufu, “Backplane 1.2,” June 2011.), the following are also defined:
User
Human involved in online transactions that may involve authentication and exchange of Identity Information.
Identity ProviderThird party entity that performs user authentication and provides an assertion about the authentication result in the form of a User’s Account Identifier being authenticated (logged-in) or not authenticated (logged-out). Optionally the Identity Provider can provide additional Identity Information about the User. AccountEntry maintained by an Identity Provider for a User. Account IdentifierUnique string identifier associated by an Identity Provider with a User for whom it has an Account and it can authenticate. Account Identifiers SHOULD be URIs. It is RECOMMENDED however to limit account identifiers to URLs or URIs of “acct” (Jones, P., Salgueiro, G., and J. Smarr, “Webfinger,” October 2011.) [Webfinger] scheme. Linked AccountAn Account with which another Account has a relationship, usually in the form of some control that can be exercised by the User controlling the former Account on the latter, Linked Account. The relationship and degree of control MAY be expressed through Access Credentials. The owner of the two Accounts may or may not be the same User. Access CredentialsCredentials associated with a Linked Account that were transferred to another Account. They MAY allow the User or application acting on the User’s behalf and controlling the latter Account to perform operations on the Linked Account, such as accessing APIs exposed by the Identity Provider to retrieve data associated with the Linked Account.Identity InformationData about the User associated with a Account such as profile information, attributes or Access Credentials for Linked Accounts.Login WidgetA Widget that facilitates user authentication against an Identity Provider and uses Backplane to publish related information for the other Widgets on the same Web Page.Logged-in StateA Account Identifier is in a Logged-in State on a Channel if the last message posted by a Login Widget on that Channel about that Account Identifer asserts the authenticated state (i.e. is of type “identity/login”, see Section 3.1 (identity/login)).Logged-out StateA Account Identifier is in a Logged-out State on a Channel if the last message posted by a Login Widget on that Channel about that Account Identifer asserts the not authenticated state (i.e. is of type “identity/logout”, see Section 3.1 (identity/login)), or if there are no messages from any Login Widgets on the Channel about the Account Identifier asserting the authenticated state (i.e. no messages of type “identity/login”, see see Section 3.1 (identity/login)).
 TOC 

1.2. Requirements Language

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].
 TOC 

2. Protocol Flow

The following events and actions constitute the Identity Scenario protocol.
 TOC 

2.1. User Login

Whenever a Login Widget on a Web Page facilitates a user login, a identity/login (identity/login) message MUST be published on the Channel associated with the Web Page. The party responsible for posting the identity/login message is the Login Widget’s provider. The manner in which the Login Widget’s provider accomplishes this is outside the scope of this specification. The identity/login messages posted as a result of a user login event MUST have the sticky flag set to true, in order for them them to be retained for a longer time by the Backplane Server and allow other parties to use them to reconstruct the Logged-in or Logged-out States of the Account Identifiers that are or were present in a Channel. Note that multiple user login events can be initiated from a Web Page and the corresponding identity/login messages for each of them will be posted on the Channel; therefore multiple Account Identifiers MAY exist in the Logged-in State on a Channel at a given time.
 TOC 

2.2. User Logout

Whenever a Login Widget on a Web Page facilitates a user logout, a identity/logout (identity/logout) message MUST be published on the Channel associated with the Web Page. The party responsible for posting the identity/logout message is the Login Widget’s provider. The manner in which the Login Widget’s provider accomplishes this is outside the scope of this specification. The identity/logout messages posted as a result of a user logout event MUST have the sticky flag set to true, in order for them them to be retained for a longer time by the Backplane Server and allow other parties to use them to reconstruct the Logged-in or Logged-out States of the Account Identifiers that are or were present in a Channel.
 TOC 

2.3. Identity Information Update

When Identity Information changes (either at the Identity Provider or at a different party that maintains it), a identity/update (identity/update) message SHOULD be posted on the Channel associated with the Web Page. The party responsible for detecting the change and for posting the identity/update message is the Login Widget’s provider. The manner in which the Login Widget’s provider accomplishes this is outside the scope of this specification. The identity/update message MUST only contain the pieces of Identity Information that have changed, not the complete set of Identity Information data, as described in Section 4.6 (Update). The identity/update messages MUST have the sticky flag set to false.
 TOC 

2.4. Page Load

Whenever a Web Page containing a Login Widget is loaded the Logged-in State of all Account Identifiers that are or were present in the Channel MUST be advertised by having the last identity/login messages for each Account Identifier re-posted on the Channel. The parties responsible detecting a page load and posting the identity/login messages relevant for each Account Identifier are the Login Widget’s providers that facilitated the authentication of the respective users. The manner in which the Login Widget’s providers accomplish this task is outside the scope of this specification. They MAY use the sticky identity/login and identity/logout messages retained in the Channel. The identity/login messages posted as a result of a page load event MUST have the sticky flag set to false, as they are intended for a one-time consumption by Widgets interested in discovering the Logged-in States of the Users Identifiers that are present on the Channel.
 TOC 

3. Message Types

Following are definitions of the Backplane message types employed by the Identity Scenario. Note that message payloads are sent only to server-side Backplane clients. Widgets only receive message headers: no payloads, acting as event notifications. They must contact their corresponding server-side components for the details on how to fully react to each event.
 TOC 

3.1. identity/login

The payload of the ‘identity/login’ message is a JSON object which contains the following fields:
context
the URL of the Web Page where the user login was initiated
identitiesa Portable Contacts object listing the authenticated Account Identifiers, in the format defined in Section 4 (Identity Information)
 TOC 

3.2. identity/logout

The payload of the ‘identity/logout’ message is a JSON object which contains the following fields:
context
the URL of the Web Page where the user logout was initiated
identitiesa Portable Contacts object listing the Account Identifiers that are no longer authenticated, in the format defined in Section 4 (Identity Information)
 TOC 

3.3. identity/update

The payload of the ‘identity/update’ message is a JSON object which contains the following fields:
context
the URL of the Web Page to which the Identity Information update is addressed
identitiesa Portable Contacts object listing the Account Identifiers for which the Identity Information has changed, with the subset of Identity Information data that has actually changed, as described in Section 4.6 (Update)
 TOC 

4. Identity Information

Identity Information communicated between Backplane parties in this scenario is defined in this section and is represented in Portable Contacts (Smarr, J., “Portable Contacts 1.0 Draft C,” August 2008.) [PortableContacts] format with some restrictions and extensions. Portable Contacts data MUST be presented in the JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] format. The Backplane Identity Scenario deals with a single User – the one performing identity-related actions in the context of a concrete browsing session. The “entry” object in the Portable Contacts response node MUST be an array with a single value representing this User and having the Contact Schema defined by Portable Contacts, with the restrictions and extensions described in the following sub-sections.
 TOC 

4.1. Account Identifier

The Contact Schema applied to the single “entry” value is extended with the following element:
accountUri
The User’s Account Identifier (Definitions).
The “accountUri” element MUST be present and it MUST have a non-empty value. The “accountUri” JSON field name is case-insensitive, for better interoperability. Consumers of messages containing this field MUST accept all case-insensitive spellings of the field’s name. Identity Providers may or may not send the same value for the “id” field required by Portable Contacts.
 TOC 

4.2. User Profile

Identity Providers SHOULD leverage as much as possible the Contact Schema defined by Portable Contacts and applied to the single “entry” in the response to supply or facilitate the exchange of User Profile information.
 TOC 

4.3. Access Credentials

The Contact Schema applied to the single “entry” value is extended with the following element:
accessCredentials
OAuth2 Access Credentials associated with the Account represented by the “accountUri” value, as a JSON object representing an Access Token Response defined in Section 5.1 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2].
Example:
"accessCredentials": {
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "scope":"example_scope",
  "example_parameter":"example_value"
}

 TOC 

4.4. Linked Accounts

The “accounts” element defined by the Contact Schema is used to represent Linked Accounts (Definitions). In addition to the “domain”, “userid” and “username” fields, the “account” element’s schema is extended to allow a entire Contact Schema entry, including the extension elements defined in the previous sections, but not additional, chained linked accounts. Each “account” entry MUST contain the “accountUri” element and its value MUST NOT be empty.
 TOC 

4.5. Extensibility

The Contact Schema applied to the single “entry” value is extended to allow at the top level any custom fields that Identity Providers may wish to add. See the non-Portable Contacts custom field in the example at the end of the section for a generic use of this extensibility feature. Example of a Identity Information data set expressed as a Portable Contacts entry that may be transferred in a Backplane message:
{
    "startIndex": 0,
    "itemsPerPage": 1,
    "totalResults": 1,
    "entry": [
      {
        "id": "https://facebook.com/johndoe",
        "accountUri": "https://facebook.com/johndoe",
        "emails": [{
            "value": "username@email.com",
            "primary": "true"
          }],
        "photos": [
            {
              "value": "http://img.twitter.com/johndoe1.jpg"
              "type": "original"
            },
            {
              "value": "http://img.twitter.com/johndoe2.jpg"
              "type": "thumbnail"
            },
            {
              "value": "http://img.twitter.com/johndoe3.jpg"
              "type": "small"
            },
            {
              "value": "http://img.twitter.com/johndoe4.jpg"
              "type": "normal"
            },
            {
              "value": "http://img.twitter.com/johndoe5.jpg"
              "type": "large"
            },
            {
              "value": "http://img.twitter.com/johndoe6.jpg"
              "type": "avatar"
            }
        ],
        "accounts": [
            {
              "accountUri" : "http://twitter.com/johndoe",
              "domain": "twitter.com",
              "username": "johndoe"
            },
            {
              "accountUri": "http://example.com/user/johndoe",
              "domain": "example.com",
              "username": "johndoe"
            },
            {
              "accountUri": "sgn://livejournal.com/?ident=johndoe"
              "domain": "livejournal.com",
              "username": "johndoe"
            }
        ],
        "capture": {
            "id": "johndoe",
            "uuid": "d0bb5379-848b-4ec6-b14e-05ec88095730",
            "created": "2012-01-22",
            "lastUpdated": "2012-01-31",
            "currentLocation": "Moon",
            "emailVerified": "johndoe@moon.example.com"
        }
      }
    ]
}

 TOC 

4.6. Update

An Identity Information update is a subset of the complete Identity Information, corresponding to a Identity Information Update (Identity Information Update) event. The corresponding Portable Contacts entry MUST only contain the pieces of information that have changed. Example of a Identity Information update expressed as a Portable Contacts entry that may be transferred in a Backplane message:
{
    "startIndex": 0,
    "itemsPerPage": 1,
    "totalResults": 1,
    "entry": [
        {
        "accounts": [
            {
                "accountUri" : "http://twitter.com/johndoe",
                "photos": [
                  {
                      "value": "http://img.twitter.com/johndoe2-new.jpg"
                      "type": "thumbnail"
                  }
                ]
            }
        ]
        }
    ]
}

 TOC 

5. Use Cases

The following use cases are believed to be the most common ones, illustrating how Widgets discover the Logged-in (or Logged-out) State in two contexts:
  1. right after a user login event occurs
 
  • when a Web Page is (re)loaded
  Other use cases are, of course, possible.
 TOC 

5.1. User Login

  1. Backplane.js library initializes on each page load:
  1. reads the channel_id from a previously set cookie, or
 
  • retrieves a new channel_id from the Backplane Server
   
  • sets up polling for new messages from the Backplane Server at regular intervals
   
  • Widgets on the page subscribe to receive notifications for all Backplane messages, or for specific message types that they are interested in; for Identity Scenario, presumably identity/* messages types
   
  • User clicks the Login link for a Login Widget that exists on the Web Page
   
  • After the user is authenticated, Login Widget’s server-side component posts a identity/login message on the Channel
   
  • Backplane.js library receives the identity/login message and notifies the Widgets on the Web Page that have registered for identity/login notifications
   
  • Widgets interested in user login events consume the message and react to the login event as they see fit
 
 TOC 

5.2. User Logout: Identity Provider

If the user logs out from the Identity Provider a identity/logout message SHOULD (and ideally MUST) be published on the Backplane channel. Widgets can react to this state change and update the session they have with the user to reflect the new logged-out state.
  1. Backplane.js library initializes on each page load:
  1. reads the channel_id from a previously set cookie, or
 
  • retrieves a new channel_id from the Backplane Server
   
  • sets up polling for new messages from the Backplane Server at regular intervals
   
  • Widgets on the page subscribe to receive notifications for all Backplane messages, or for specific message types that they are interested in; for Identity Scenario, presumably identity/* messages types
   
  • A Account Identifier in the Logged-in State exists on the Channel from a previous interaction
   
  • The user initiates a Identity Provider logout event by clicking o a link or button provided by the Login Widget
   
  • Login Widget’s server-side component posts a identity/logout message on the Channel
   
  • Backplane.js library receives the identity/logout message and notifies the Widgets on the Web Page that have registered for identity/logout notifications
   
  • Widgets interested in user logout events consume the message and react to the logout event as they see fit
 
 TOC 

5.3. User Logout: Site Local

The widgets on a site may wish to end the session they have with a user independently from the logged-in or logged-out state the user has with their Identity Provider. This can be desired if, for example, the site knows the user is leaving the site and wants to force a re-login when the user returns, or perhaps if the site does not want to rely on the Identity Provider support of identity/logout advertisements. In this case the widget must reset the Backplane channel in order to ensure the current session and logged-in state is ended.
  1. Backplane.js library initializes on each page load:
  1. reads the channel_id from a previously set cookie, or
 
  • retrieves a new channel_id from the Backplane Server
   
  • sets up polling for new messages from the Backplane Server at regular intervals
   
  • Widgets on the page subscribe to receive notifications for all Backplane messages, or for specific message types that they are interested in; for Identity Scenario, presumably identity/* messages types
   
  • A Account Identifier in the Logged-in State exists on the Channel from a previous interaction
   
  • The user initiates a site local logout by clicking o a link or button provided by the local website
   
  • The site resets the Backplane channel and terminates the local session it has for the user
  If the same user (having the same Logged-in state with their Identity Provider) returns to a Backplane-enabled page, the site has the opportunity to process again the identity/login events and create a new local session even though it is the same user.
 TOC 

5.4. Web Page (Re)Load

  1. Backplane.js library initializes on each page load:
  1. reads the channel_id from a previously set cookie, or
 
  • retrieves a new channel_id from the Backplane Server
   
  • sets up polling for new messages from the Backplane Server at regular intervals
   
  • Widgets on the page subscribe to receive notifications for all Backplane messages, or for specific message types that they are interested in; for Identity Scenario, presumably identity/* messages types
   
  • The Login Widget detects that a Web Page (Re)Load has occurred.
   
  • The Login Widget’s provider is responsible for and re-posts all identity/login messages for all Account Identifiers that are in the Logged-in State in the Channel (that have previously logged in in the Channel, likely on a different Web Page on the same domain)
 
  • Backplane.js library receives the identity/login messages and notifies the Widgets on the Web Page that have registered for identity/login notifications
  • Widgets interested in user login events consume the message and react to the login event as they see fit: they effectively discover all Account Identifiers that are in the Logged-in State in the Channel

 TOC 

6. Normative References

[Backplane2.0] Saad, C., Skvortsov, V., Lukyanov, Y., Zhuravlev, A., Glushkov, I., Howells, C., and J. Bufu, “Backplane 1.2,” June 2011.
[Google.SGNodeMapper] Fitzpatrick, B., “SocialGraph Node Mapper,” 2010.
[OAuth2] Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.
[PortableContacts] Smarr, J., “Portable Contacts 1.0 Draft C,” August 2008.
[RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, “Uniform Resource Locators (URL),” RFC 1738, December 1994 (TXT).
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986, January 2005 (TXT, HTML, XML).
[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[Webfinger] Jones, P., Salgueiro, G., and J. Smarr, “Webfinger,” October 2011.

 TOC 

Authors’ Addresses

Chris Saad
Echo
Email: chris@aboutecho.com
URI: http://aboutecho.com
Vlad Skvortsov
Echo
Email: vss@aboutecho.com
URI: http://aboutecho.com
Yuri Lukyanov
Echo
Email: snaky@aboutecho.com
URI: http://aboutecho.com
Alexander Zhuravlev
Echo
Email: zaa@aboutecho.com
URI: http://aboutecho.com
Ivan Glushkov
Echo
Email: gli@aboutecho.com
URI: http://aboutecho.com
Carl Howells
Janrain
Email: chowells@janrain.com
URI: http://www.janrain.com/
Tom Raney
Janrain
Email: traney@janrain.com
URI: http://www.janrain.com/
Johnny Bufu
Janrain
Email: jbufu@janrain.com
URI: http://www.janrain.com/