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/