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/