Identity Scenario 1.2


December 8, 2011

Abstract

This document describes a Backplane application scenario that allows widgets to exchange identity data and 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.  User Identity Information Update
    2.4.  Page Load
3.  Message Types
    3.1.  identity/login
    3.2.  identity/logout
    3.3.  identity/update
4.  User Identity Information
    4.1.  Update
5.  Use Cases
    5.1.  User Login
    5.2.  User Logout
    5.3.  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

In addition to the terms defined by [Backplane1.2] (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:

Identity Provider
Third party entity that performs user authentication and provides an assertion about the authentication result in the form of a User Identifier being authenticated (logged-in) or not authenticated (logged-out). Optionally the Identity Provider can provide user profile data.
User Identifier
Identifier associated by an Identity Provider with a user for whom it has an account and it can authenticate.
User Identity Information
Data associated with a User Identifier such as profile information or attributes.
Login Widget
A 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 State
A User Identifier is in a Logged-in State on a Channel if the last message posted by a Login Widget on that Channel about that User Identifer asserts the authenticated state (i.e. is of type “identity/login”, see Section 3.1 (identity/login)).
Logged-out State
A User Identifier is in a Logged-out State on a Channel if the last message posted by a Login Widget on that Channel about that User 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 User 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 User 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 User 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 User Identifiers that are or were present in a Channel.



 TOC 

2.3.  User Identity Information Update

When User 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 User Identity Information that have changed, not the complete set of User Identity Information data, as described in Section 4.1 (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 User Identifiers that are or were present in the Channel MUST be advertised by having the last identity/login messages for each User Identifier re-posted on the Channel.

The parties responsible detecting a page load and posting the identity/login messages relevant for each User 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.



 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
identities
a Portable Contacts object listing the authenticated User Identifiers, in the format defined in Section 4 (User 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
identities
a Portable Contacts object listing the User Identifiers that are no longer authenticated, in the format defined in Section 4 (User 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 User Identity Information update is addressed
identities
a Portable Contacts object listing the User Identifiers for which the User Identity Information has changed, with the subset of User Identity Information data that has actually changed, as described in Section 4.1 (Update)



 TOC 

4.  User Identity Information

User Identity Information communicated between Backplane parties in this scenario 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 is presented in the JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] format.

Since the scenario deals with a single user (the one performing identity-related actions in the context of a concrete browsing session), “entry” object in the Portable Contacts response node MUST contain a single value.

The “entry” object value MUST contain the “accounts” element with at least one item. Each of the account items represents an identity.

An User Identifier is represented by an “identityUrl” element, which can be either a plain URL (Berners-Lee, T., Masinter, L., and M. McCahill, “Uniform Resource Locators (URL),” December 1994.) [RFC1738], or normalized SGN URI (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [RFC3986] constructed from domain/userid pair by putting these values together: sgn://<DOMAIN>/?ident=<USERID>. In the latter case SGN URI MUST be recognized by Google’s SGNodeMapper (Fitzpatrick, B., “SocialGraph Node Mapper,” 2010.) [Google.SGNodeMapper].

Example of a User 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": [
        {
        "accounts":
            {
                "identityUrl" : "http://twitter.com/johndoe",
                "username": "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"
                  }
                ]
            },
            {
                "identityUrl": "http://example.com/user/johndoe"
            },
            {
                "identityUrl": "sgn://livejournal.com/?ident=johndoe"
            }

        }
    ]
}


 TOC 

4.1.  Update

A User Identity Information update is a subset of the complete set of a User Identity Information, corresponding to a User Identity Information Update (User Identity Information Update) event.

The corresponding Portable Contacts entry MUST only contain the pieces of information that have changed.

Example of a User 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":
            {
                "identityUrl" : "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
  2. 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
    2. retrieves a new channel_id from the Backplane Server
    3. sets up polling for new messages from the Backplane Server at regular intervals
  2. 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
  3. User clicks the Login link for a Login Widget that exists on the Web Page
  4. After the user is authenticated, Login Widget’s server-side component posts a identity/login message on the Channel
  5. Backplane.js library receives the identity/login message and notifies the Widgets on the Web Page that have registered for identity/login notifications
  6. Widgets interested in user login events consume the message and react to the login event as they see fit



 TOC 

5.2.  User Logout

  1. Backplane.js library initializes on each page load:
    1. reads the channel_id from a previously set cookie, or
    2. retrieves a new channel_id from the Backplane Server
    3. sets up polling for new messages from the Backplane Server at regular intervals
  2. 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
  3. A User Identifier in the Logged-in State exists on the Channel from a previous interaction
  4. The user initiates a logout event by clicking o a link or button provided by the Login Widget
  5. Login Widget’s server-side component posts a identity/logout message on the Channel
  6. Backplane.js library receives the identity/logout message and notifies the Widgets on the Web Page that have registered for identity/logout notifications
  7. Widgets interested in user logout events consume the message and react to the logout event as they see fit



 TOC 

5.3.  Web Page (Re)Load

  1. Backplane.js library initializes on each page load:
    1. reads the channel_id from a previously set cookie, or
    2. retrieves a new channel_id from the Backplane Server
    3. sets up polling for new messages from the Backplane Server at regular intervals
  2. 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
  3. The Login Widget detects that a Web Page (Re)Load has occurred.
  4. The Login Widget’s provider is responsible for and re-posts all identity/login messages for all User 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)
  5. Backplane.js library receives the identity/login messages and notifies the Widgets on the Web Page that have registered for identity/login notifications
  6. Widgets interested in user login events consume the message and react to the login event as they see fit: they effectively discover all User Identifiers that are in the Logged-in State in the Channel



 TOC 

6. Normative References

[Backplane1.2] 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.
[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).


 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/