Backplane Protocol 2.0 – Draft 12

May 2012

Abstract

Backplane Protocol is a framework that facilitates message
exchanges and event notifications between third-party
JavaScript components within a web page.



Table of Contents

1. 
Introduction
2. 
Definitions
    2.1. 
Requirements Language
3. 
Overview
4. 
Trust
5. 
Access Levels
    5.1. 
Regular Access
    5.2. 
Privileged Access
        5.2.1. 
Authorization
6. 
Discovery, Registration and Authorization
    6.1. 
Backplane Server Discovery
        6.1.1. 
Dynamic Discovery
        6.1.2. 
Static Discovery
    6.2. 
Backplane Client Registration
        6.2.1. 
Dynamic Client Registration
        6.2.2. 
Static Client Registration
        6.2.3. 
Manual Client Registration
    6.3. 
Authorization
        6.3.1. 
Backplane Client Initiated Authorization
        6.3.2. 
Backplane Server Initiated Authorization
7. 
Padded Responses
8. 
Buses
9. 
Channels
10. 
Backplane Messages
11. 
Message Retention
    11.1. 
Sticky Messages
12. 
Message Sequences and Retrieval
    12.1. 
Access Scopes
13. 
Backplane Server API
    13.1. 
Authenticated Access Token Request
    13.2. 
Anonymous Access Token Request
    13.3. 
Get Messages
    13.4. 
Get Single Message
    13.5. 
Post Message
14. 
Backplane JavaScript API
    14.1. 
Initialization
    14.2. 
Subscription Management
    14.3. 
Hints
    14.4. 
Usage Example
15. 
Security Considerations
    15.1. 
Channel Name Sensitivity
    15.2. 
Message Payloads
16. 
Normative References
§ 
Authors’ Addresses



 TOC 


1. 
Introduction

Web pages have evolved from being loaded from a single resource
to being able to reference third-party, external components
that get loaded, run and rendered by the web browser within
the same web page.

These components can be active and continue to run after the
web page completed loading and are generally decoupled
— not under the control of a single entity.

Interactions between the end user, the web page, and its
features provided through such components can greatly benefit
when all parties involved can exchange information with each
other, and can do it in a standardized way.

The Backplane framework facilitates such interactions
by providing an open standard API that is secure in the
context of the assumed trust relationships between the parties
involved. Messages are delivered reliably and in order. The
framework may be used in different scenarios which build on
top of the transport-level semantics described in this
document.



 TOC 


2. 
Definitions

Web Page
Document obtained from a web resource and loaded by the end
user’s web browser.

Widget
Third-party JavaScript component referenced from the Web
Page that is loaded and run in the end user’s browser.

Backplane Client
Entity that uses the Backplane framework to
exchange information.

Backplane Message
A JSON object representing the unit of communication between
Backplane Clients.

Message Identifier
Unique string assigned by Backplane Servers to each incoming
Backplane Messages for the purpose of identifying and
referencing them via the “since” retrieval mechanism.

Backplane Header
A Backplane Message without the payload field.

Backplane JavaScript API
JavaScript API used by Widgets to initialize and subscribe
to Backplane Messages.

Backplane JavaScript Library
Backplane JavaScript API implementation.

Backplane Server API
Server API through which Backplane Clients send and retrieve
Backplane Messages.

Backplane Server
Backplane Server API implementation.

Bus
Logical grouping of Backplane Clients that need to interact
with each other, typically belonging to one organization.

Channel
Subset of Backplane Messages that belong to a Bus and are
addressed to the Backplane Clients interacting with the end
user through a single session and Web Page.

Message Sequence
A set of Backplane Messages that meet a certain filter criteria,
in the same order as they have been received by a Backplane
server.

Message Age
The length of time since the Message was received by the
Backplane server.



 TOC 


2.1. 
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 


3. 
Overview

An operational Backplane framework consists of the
following components:

  • A Backplane Server
  • A Backplane JavaScript Library
  • Widgets that act as Backplane Clients
  • Widgets’ server-side counterparts that act as Backplane Clients.

A Backplane Server is an independent orchestrator of the
message interchange between Backplane Clients and may serve
multiple independent Buses.

A Backplane framework instance needs to be configured
prior to use: all Backplane Clients and the Server have to share
the same Bus. Backplane Clients operating at the
Privileged Access Level (Privileged Access)
need a password to authenticate themselves to the Server.



 TOC 


4. 
Trust

The Backplane framework is intended to be used and
operate under the following trust relationships. Any number
of security issues can arise if any of these assumptions do
not hold.

The end user trusts the Web Page owner (and indirectly all
Widget owners) that the Web Page will not attack or exploit
their web browser.

The Web Page owner (and indirectly the end user) trusts all
Widget owners that the Widgets will not abuse the Backplane
framework by trying to impersonate other Widgets’
behavior in order to obtain and access information that is
not directed to them, such as end user account information
addressed to other Widgets.

The Web Page owner (and indirectly the end user), and
Widget owners trust the Backplane Server API and Backplane
JavaScript API implementations that they will comply with
this specification.

The Web Page owner (and indirectly the end user) trusts
all content on the Web Page to not attack the widgets or
the Backplane framework. This must explicitly
include all JavaScript loaded for any purpose, including
JavaScript that is not part of any of the Widgets on the
Web Page.

Backplane Clients trust the Bus owner and the authenticity
of Backplane Messages received through a Bus, i.e all
Backplane Clients that were granted permission to post on
the Bus by its owner.



 TOC 


5. 
Access Levels

Considering the significantly different security enforcement
capabilities of applications running in a web browser versus the
ones running on a web server, two access levels are defined for
Backplane Clients: Regular and Privileged.

Each access level is exercised for retrieving messages from the
Get Messages (Get Messages) endpoint
by presenting either a regular or a privileged access token
obtained from the
token (Authenticated Access Token Request) endpoint.

The access token MUST be presented as described
in section 2 (Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 2011.) [OAuth2.token.bearer].

Backplane Servers MUST validate the access token presented
with all requests received at the
Get Messages (Get Messages)
endpoint and determine the access level associated with it.



 TOC 


5.1. 
Regular Access

Regular access level is given to Backplane Clients running in
the web browser (Widgets and the Backplane JavaScript Library)
and are obtained through anonymous calls to the
token (Authenticated Access Token Request) endpoint.

Bus owners and Backplane Servers acting on their behalf MUST
NOT give authorization credentials for Privileged access level
to Backplane Clients running in the web browser.

Even though
section 2 (Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 2011.) [OAuth2.token.bearer] specifies
that access tokens SHOULD NOT be sent in HTTP request query
parameters, for Backplane clients deployed in the browser
(specifically, Javascript loaded from <script> tags)
it may be the only option. Backplane Servers SHOULD accept
regular access tokens sent in HTTP request query
parameters.

Backplane Servers MUST only make Backplane Message Headers
(not full Backplane Messages) available to Clients having
Regular access level.



 TOC 


5.2. 
Privileged Access

Privileged access level is given to Backplane Clients that
are not running in a web browser (typically the Widgets’
server-side components) and are obtained through authenticated
calls to the
token (Authenticated Access Token Request) endpoint.

Backplane Servers MUST NOT accept privileged access level tokens
sent in HTTP request query parameters.

Backplane Clients having Privileged access level can perform
the following operations on a Bus for which they have obtained
authorization (Authorization) credentials
from the Bus owner:



 TOC 


5.2.1. 
Authorization

Registered (Backplane Client Registration)
Backplane Clients must be authorized with Privilged Access
Level. This can be done in one of the following ways:

  • By Backplane Server administrators. It is outside of
    the scope of this specification how the administrators
    learn from their customers, the Bus Owners, the Buses
    and Backplane Clients to be authorized with Privileged
    Access.

  • By Bus Owners, through an administrative interface
    provided by the Backplane Server. The interactions
    between a Backplane Server and its Bus Owner customers
    (e.g. registration, authentication, Bus allocation)
    remain outside of the scope of this specification.



 TOC 


6. 
Discovery, Registration and Authorization

For a functional setup, the Bus Owners, Backplane Servers and
Backplane Clients needing Privileged Access have to perform
the following preliminary interactions:



 TOC 


6.1. 
Backplane Server Discovery



 TOC 


6.1.1. 
Dynamic Discovery

It is RECOMMENDED that Backplane Servers support dynamic
discovery, as described in
[OAuth.Dynamic.Client.Registration] (Hardjono, T., Machulak, M., Maler, E., and C. Scholz, “OAuth Dynamic Client Registration Protocol,” Oct 2011.) section
5. Discovery of Server’s Client Registration Endpoint.
[[[ doesn’t cover authorization/token endpoints, it probably should ]]]



 TOC 


6.1.2. 
Static Discovery

When dynamic discovery is not available, Backplane Clients
must independently acquire and keep configuration entries
for the registration, authorization, token and message
endpoints of the Backplane Servers they wish to interact
with.



 TOC 


6.2. 
Backplane Client Registration

Backplane Clients need to be registered with the Backplane
Server in order to be authorized with
Privileged Access (Privileged Access).

As part of the registration process Backplane Servers MUST
associate with each client a message source URL that will be
used as the source field value for
the messages posted by that client.

Backplane Servers SHOULD provide one of the following
registation methods, listed in decreasing order of preference.



 TOC 


6.2.1. 
Dynamic Client Registration

It is RECOMMENDED that Backplane Servers and Backplane
Clients employ
[OAuth.Dynamic.Client.Registration] (Hardjono, T., Machulak, M., Maler, E., and C. Scholz, “OAuth Dynamic Client Registration Protocol,” Oct 2011.) as
described in sections “6. Client Registration with Pushed
Metadata” and “7. Client Registration with Pushed URL and
Pulled Metadata”.



 TOC 


6.2.2. 
Static Client Registration

Backplane Servers MAY provide an administrative interface
through which Bus Owners can register Backplane Clients.
The interactions between a Backplane Server and its
Bus Owner customers (e.g. registration, authentication, Bus
allocation) remain outside of the scope of this
specification.

For the purpose of Privileged Access Level authorization a
server-side Backplane Client needs to be identified by a URL
that corresponds to the Redirection URI defined in
section 2.1.1 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2] and used
in the authorization step in
section 4 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2].
The redirection URI MUST be obtained and approved by the Bus
Owner administrator. Backplane Servers may assist Bus Owner
administrators by providing the redirection URIs of well known
Backplane Clients (such as popular Widget providers) in their
administration user interface.

When completing a
Backplane Server Initiated Authorization (Backplane Server Initiated Authorization)
if the previously unregistered Backplane Client opted to
also send client credentials, the Backplane Server MAY
register (Static Client Registration)
the Backplane Client. The Backplane Server MUST verify all
of the following:

  • The grant_type is “code”.

  • The code is present and the value is recognized as a
    previously issued, one-time use, valid code.

  • The redirect_uri is present and matches the
    redirect_uri for which the supplied code was
    issued.

  • The client_id is present with a value that is neither
    empty nor already registered.

Backplane Servers MAY register the redirect_uri as the
message source URL associated with the client.

After a successful registration the Backplane Server
MUST continue processing the
Authenticated Access Token Request (Authenticated Access Token Request)



 TOC 


6.2.3. 
Manual Client Registration

As a last resort, Backplane Server administrators MAY
manually register Backplane Clients and make them available
to Bus Owners for Privileged Access authorization.



 TOC 


6.3. 
Authorization



 TOC 


6.3.1. 
Backplane Client Initiated Authorization

A Bus Owner MAY initiate standard OAuth 2.0 authorization
code flow from the Backplane Client as described in
section 4.1 Authorization Code (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2],
if supported by the Backplane Client. Backplane Servers
SHOULD support the standard OAuth Authorization Code flow.



 TOC 


6.3.2. 
Backplane Server Initiated Authorization

Backplane Servers MAY provide an administrative interface
through which Bus Owners can initiate the authorization of
registered (Backplane Client Registration)
Backplane Clients using a slightly modified OAuth
Authorization Code flow described in this section.

Once the Backplane Client has been identified and the Bus
Owner has selected the Buses for authorization, the
Backplane Server persists the authorization grant,
generates an OAuth code for it and sends it with an
unsolicited OAuth Authorization Response to the Backplane
Client’s redirection URI. The successful authorization
response SHOULD contain the
scope field with the appropriate
list of
Access Scopes (Access Scopes).

Since an unsolicited OAuth Authorization Response is issued,
the Backplane Server’s
token (Authenticated Access Token Request) endpoint
MUST be identified in the Redirection URI using a query
parameter named
bp_token_endpoint.

The Backplane Client continues by following the OAuth
Authorization Code flow from this point, and exchanges the
authorization code for an access token at the Backplane
Server’s token endpoint, as described in
sections 4.1.3 and 4.1.4 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2] and
Access Token Request (Authenticated Access Token Request).



 TOC 


7. 
Padded Responses

For API requests made by the Javascript clients (such as the
Backplane Javascript Library), the response MUST be formatted
specially, as described in this section. Such requests are
identified by the presence of a
callback parameter.

The body of a successful response begins with the value of
the callback parameter from the
request. That value is followed by a "(" (opening
parenthesis), then the JSON-encoded result value, then a
")" (closing parenthesis).

Error responses MUST be returned with HTTP status code 200
and MUST also be in the format described above for successful
responses. In addition, the JSON payload of error responses
MUST contain at least a field named “error”.



 TOC 


8. 
Buses

A Bus is a logical grouping of Backplane Clients that need to
interact with each other, typically belonging to one
organization. Buses allow a Backplane Server to service
multiple customers. Bus names are short strings
referencing the Bus owner’s name (e.g. “customer.com”,
“organization.org”).
Backplane Clients must know the identifiers for the Buses through
which they wish to exchange Backplane Messages.

It is assumed that a relationship of trust exists between all
clients granted permission to post messages to a specific
Bus (see Trust (Trust)).



 TOC 


9. 
Channels

A Channel is a subset of Backplane Messages that belong to a Bus
and are addressed to the Backplane Clients interacting with the
end user through a single session and Web Page. A Channel is
similar to a session identifier for the user but is shared by
multiple Backplane Clients.

Channels are:

  • allocated within Buses
  • referenced by unique, unguessable identifiers
  • created implicitly once a Backplane Message gets
    posted to a channel that doesn’t yet exist
  • non-persistent and expire after being inactive (no
    messages posted) for specific amount of time (e.g. 30
    minutes)
  • sensitive; see Channel Name Sensitivity (Channel Name Sensitivity).

Channel identifiers are used by Backplane Clients for message
retrieval. All Backplane Clients that know a given Channel identifier
can receive Backplane Messages posted to that Channel.

Channel identifiers MUST only contain characters from the
base64url (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648.section5] character set
and be at least 32 characters long. New channels are generated
only on
anonymous access token requests (Anonymous Access Token Request).

The channel name MUST NOT be guessable given knowledge of the
algorithms in use or any details of the request being made
(RFC 4086 (Eastlake, D., Schiller, J., and S. Crocker, “Randomness Requirements for Security,” June 2005.) [RFC4086] discusses the
requirements and pitfalls of generating unguessable values
in great detail).

There can be at most one channel active on a Web Page at a
given time.



 TOC 


10. 
Backplane Messages

A Backplane Message is a JSON object with the following fields:

messageURL (string)
a URL that a client can use to retrieve the message

source (string)
an URL identifying the client which posted the message,
associated with the client during
registration (Backplane Client Registration)

type (string)
opaque to the core Backplane Protocol specification; value,
semantic and associated payload format is defined in
application scenario specifications

bus (string)
the name of the Bus the message was posted to

channel (string)
the identifier of Channel the message was posted to

sticky (boolean)
sticky flag. See
Sticky Messages (Sticky Messages)

payload (object)
arbitrary data specific to the particular message type

All message field values except “payload” MUST NOT contain the
space character (UCS code point 32).

The presence of certain fields in a Backplane Message depends on
the context it appears in.

A downstream (server-to-client) Backplane Message delivered to
a client with
privileged access (Privileged Access)
MUST contain all the fields listed above; downstream messages
delivered to
regular access (Regular Access)
clients MUST contain all except the “payload” field from the
fields listed above.

An upstream (client-to-server) Backplane Message MUST contain
the fields “bus”, “channel”, “payload”, “type”, it MAY contain
the “sticky” field and MUST NOT contain any other fields. If the
“sticky” field is omitted the Backplane Server MUST consider the
posted message non-sticky.

Example downstream Backplane Message:

{
        "bus": "customer.com",
        "channel": "67dc880cc265b0dbc755ea959b257118",
        "messageURL": "https://bp.example.com/v2/message/097a5cc401001f95b45d37aca32a3bd2",
        "source": "http://aboutecho.com",
        "payload": {
                "role": "administrator"
        },
        "type": "identity/ack",
        "sticky": false
}



 TOC 


11. 
Message Retention

Backplane Servers MUST maintain a buffer of messages received
from all their clients until messages become older than a
certain threshold. Such threshold MUST be no less than 1 minute.
It is RECOMMENDED that Backplane Servers set the threshold to at
least 5 minutes. A message is considered obsolete once its age
reaches the threshold.

It is RECOMMENDED that Backplane Servers make messages available
for retrieval as soon as possible after they are posted.

Backplane Clients that require reliable message delivery
MUST poll their Backplane Servers with an interval of 30
seconds or less in order to avoid omissions.



 TOC 


11.1. 
Sticky Messages

Some Backplane Protocol application scenarios may require
longer lived Backplane Messages, such as for keeping a shared
state about a end user’s logged-in identity or profile data.

Support for such scenarios is accomplished by flagging
messages as “sticky” when they are posted (see
Post Message To A Channel (Post Message)).
Backplane Servers MUST retain sticky messages for at least 5
minutes. It is RECOMMENDED that Backplane Servers retain
sticky messages for 8 hours.

Backplane Clients can request retrieval of Backplane Frames
that only encapsulate sticky messages by using the “sticky”
Access Scope (Access Scopes) filter.
See also
Message Retrieval Conventions (Message Sequences and Retrieval)
below.

Application scenario protocols MUST specify the criteria for
posting sticky messages, if any, such as defining certain
message types or operations as sticky.

Application scenario protocols SHOULD define sticky messages
in such a way as to minimize the number of sticky messages
that may be retained by the Backplane Server at any one time
for a channel, in order to reduce complexity of retrieval and
processing by the Backplane Clients that rely on them.



 TOC 


12. 
Message Sequences and Retrieval

Backplane Clients may wish to retrieve a subset of all the
messages they have access to, such as belonging to certain Buses
or Channels, having a certain type, source, or other attributes
such as sticky.

A Message Sequence is the subset of the entire stream of
Backplane Messages that match a filter criteria, in the same
order as they have been received by a Backplane Server.

The token (Authenticated Access Token Request) endpoint
is used to obtain an access token tailored to the filter
criteria desired by the client. The access token is used
at the
Get Messages (Get Messages)
endpoint to retrieve the messages in the current buffer that
belong to the associated Message Sequence.

The Message Identifier of the last Backplane Message in a
retrieved batch of messages is returned as the value of the
“since” query parameter of the nextURL response field, such that
the nextURL value will point to the messages that will
immediately follow in the buffer and will not retrieve any of
the messages that were already retrieved.

The server MUST NOT return messages older than the one pointed
to by the ‘since’ message id, even if that particular message
no longer exists in the buffer while older, sticky messages
may still exist.



 TOC 


12.1. 
Access Scopes

The filter criteria for defining a Message Sequence are passed
to the token endpoint when
requesting access tokens (Authenticated Access Token Request)
as a list of access scopes using the space character (UCS code
point 32) as the delimiter in the following format:

Access Scope Format:
<message_field_name>:<message_field_value>

where message_field_name is any
of the following message fields:

  • source
  • type
  • bus
  • channel
  • sticky
  • messageURL

and message_field_value is the
expected field’s value.

An access scope is evaluated by performing a case-sensitive
string comparison between the expected field’s value in the
access scope, and the field value from the Backplane Message.

A list of access scopes is evaluated as follows:

  • a logical OR operation is performed for all access scopes having the same field name

  • a logical AND operation is performed among all access scopes having different field names

Example access scopes: all sticky messages of type
“identity/ack” posted by “http://aboutecho.com” to any
channel belonging to the “customer.com” bus.

bus:customer.com source:http://aboutecho.com type:identity/ack sticky:true

Example access scopes: all messages (belonging to bus A OR bus B) AND (having type C OR type D)

bus:A bus:B type:C type:D

When issuing or verifying the scope of an access token,
Backplane Servers MUST enforce that the requester is
authorized with
Privileged Access (Privileged Access)
for all “bus:” access scopes.

Backplane servers maintain configuration that defines which
buses are available to clients presenting certain
client_id’s. When fulfilling access token requests the server
grants the client access to the set of buses mentioned in the
‘scope’ parameter provided it is equal to or a subset of what
is defined in the server’s configuration. In case of a
successful request the client is allowed to both post and
listen to the specified set of buses. If no buses are
requested through the value of the scope parameter, the issued
token’s scope will consist of all buses as per the server
configuration for the presented client_id.

Application scenario protocol extensions MAY define
additional authorization requirements against other scope
type and Backplane Message fields.



 TOC 


13. 
Backplane Server API



 TOC 


13.1. 
Authenticated Access Token Request

The OAuth “Token Endpoint” as defined in
section 2.2 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2] is used by clients
capable of securely maintaining a client secret and
authenticating to obtain an access token that will later be
used for retrieving messages from the
Get Messages (Get Messages)
endpoint.

Endpoint
/v2/token
HTTP mehod
POST
Security
HTTPS
Parameters
The parameters constitute an access token request as
defined in either
section 4.1.3 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2]
( “authorization_code” grant type) or
section 4.4.2 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2]
(“client credentials” grant type).

The parameters MUST be presented as prescribed by OAuth2.
Furthermore, credentials (“client_id” and “client_secret”
MUST always be sent using
HTTP Basic Authentication (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.) [RFC2617].
The rest of the parameters MUST be sent
“application/x-www-form-urlencoded” in the HTTP POST
request body.

  • client_id (string, REQUIRED)
  • client_secret (string, REQUIRED)
  • grant_type:
    MUST be “client_credentials”, “code”,
    or “refresh_token”

  • code (string):
    REQUIRED if and only if grant_type is “code”

  • redirect_uri (string):
    REQUIRED if and only if grant_type is “code”

  • refresh_token (string):
    REQUIRED if and only if grant_type is
    “refresh_token”; a refresh token previously
    issued for a privileged access level token

  • scope (string, OPTIONAL):
    a list of
    filter criteria (Access Scopes)
    delimited by the space character (UCS code point 32)
    for the messages the client is interested in.

Returns
On success, a JSON object is returned per
section 5.1 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2]
with the following fields:

Response example

{
  "access_token": "465203f03680f59b7ddd5e1e5d851461",
  "token_type": "Bearer"
}

If the “grant_type” parameter is “code”:

If the “grant_type” parameter is “client_credentials” the
client is requesting a token based on previously issued and
validated authorization grants, with a scope possibly spawning
across multiple authorization grants received from different
bus owners.

If the “grant_type” parameter is “refresh_token” the server
MUST:

  • verify that the presented refresh token was issued to the
    same client_id;

  • invalidate the access token issued with the refresh token;

  • issue a new access token with the same capabilities as
    the previous one, or with a different but authorized
    scope if a scope parameter was also included in the
    request.

The server MUST check the credentials of the client. If the
credentials are valid, the request is an authenticated access
token request; otherwise the server MUST return error per
section 5.2 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2] (error
“unautorized_client”).

The server MUST check that the client making the request is
authorized for the requested scopes. If the client is not
authorized for any of the requested scopes the server MUST
return error per
section 5.2 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2] (error
“invalid_scope”).

In response to a successful authenticated access token request
the Backplane Server issues an
privileged access token (Privileged Access)
to the client for the requested scope. If no buses are
specified in the “scope” parameter submitted in the
request, access is granted to all buses that are part of
authorization grants previously issued to the client.



 TOC 


13.2. 
Anonymous Access Token Request

This endpoint is used by clients incapable of maintaining a
secret and performing authentication (mainly JavaScript
clients running in the browser) to obtain an access token that
will later be used for retrieving messages from the
Get Messages (Get Messages)
endpoint from a newly server-side generated Channel.

Endpoint
/v2/token
HTTP mehod
GET
Security
HTTPS
Parameters
  • callback (string, REQUIRED):
    callback function to pad the response with (see
    Padded Responses (Padded Responses));
    MUST only contain alphanumeric characters (a-zA-Z0-9)

  • scope (string, OPTIONAL):
    a list of
    filter criteria (Access Scopes)
    delimited by the space character (UCS code point 32)
    for the messages the client is interested in.

  • refresh_token (string, OPTIONAL): a refresh token
    previously issued for a regular access level token

Returns
On success, a JSON object is returned similar to
section 5.1 (Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2]
with the following fields:

Response example

callback(
  {
    "access_token": "465203f03680f59b7ddd5e1e5d851461",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "channel:0a92d76f54f7877a68abe19c5b3ffcf8",
    "refresh_token": "fBHoOLdOxH4BC4eLJ8cBqkYYR2hRcoiK"
  }
)

The client MAY specify a narrower scope for filtering
purposes, i.e. the client MUST NOT include any “bus” or
“channel” fields in the requested scope. The server MUST
NOT allow an anonymous client access to buses or channels
other than its own, even if the anonymous client requested
such a broader scope. (Note that requesting a narrower,
filtered scope for the first token obtained when the channel
name is generated will leave the anonymous client no way for
later obtaining a token scoped for all the messages of the
channel.)

In response to a anonymous access token request the
Backplane Server allocates a
new channel (Channels) and issues a
regular access token (Regular Access)
to the client (no message payloads) for the channel. New
channels are generated only for anonymous access token
requests. The channel is not bound to a bus until the first
message is posted to the channel (see
Post Message (Post Message)).

Regular access tokens issued in response to anonymous access
token requests MUST expire. It is RECOMMENDED that such
tokens expire within 1 hour after having been issued.

As an operational note, this API call SHOULD NOT be
implemented in a way that makes it capable of blocking and
use of one of the mechanisms in section 7 of
RFC 4086 (Eastlake, D., Schiller, J., and S. Crocker, “Randomness Requirements for Security,” June 2005.) [RFC4086] is RECOMMENDED.

If the “refresh_token” parameter is included in the request,
the server must issue a new regular access level access token
with the scope not exceeding the channel of the initial access
token, and possibly narrower if so requested through the use
of the “scope” request parameter.



 TOC 


13.3. 
Get Messages

Retrieve messages from the server.

Endpoint
/v2/messages
HTTP mehod
GET
Security
HTTPS
Authorization
The client MUST present the access token obtained from a
Access Token Request (Authenticated Access Token Request)
as described in
section 2 (Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 2011.) [OAuth2.token.bearer].
Backplane Servers SHOULD accept regular access tokens sent
in the HTTP request query parameters and they MUST NOT
accept privileged access level tokens sent in HTTP
request query parameters. The server MUST retrieve the
Access Scopes (Access Scopes)
associated with the presented access token, determine the
Message Sequence (Message Sequences and Retrieval)
filter and access level (Access Levels),
and respond accordingly.

Parameters
  • block (integer, OPTIONAL, default 0):
    if no messages are available for immediate retrieval,
    this parameter communicates how long (in seconds) the
    server should wait before returning an empty response

  • callback (string, OPTIONAL):
    callback function to pad the response with (see
    Padded Responses (Padded Responses));
    MUST only contain alphanumeric characters (a-zA-Z0-9)

  • since (string, OPTIONAL): the Message Identifier
    representing the starting point of the requested
    Message Sequence. See
    Message Sequences and Retrieval (Message Sequences and Retrieval).

Returns
On success, a JSON object is returned
with the following fields:

  • nextURL (string):
    a complete URL pointing to the Get Messages endpoint
    that the client can invoke to retrieve subsequent
    messages from the server. The URL MUST contain a
    Message Identifier in the
    since query parameter.

  • messages[]:
    an array of messages in the order they were originally
    received by the server. Each message within the array
    is represented as a JSON object of the same structure
    as returned by the
    Get Single Message (Get Single Message)
    API method.

Response example

{
  "nextURL": "https://bp.example.com/v2/messages?since=958bfa2dd8aed82c86afbd54b4a314a5",
  "messages": [
    {
      "bus": "customer.com",
      "channel": "67dc880cc265b0dbc755ea959b257118",
      "messageURL": "https://bp.example.com/v2/message/097a5cc401001f95b45d37aca32a3bd2",
      "payload": {
        "role": "administrator"
      },
      "source": "http://aboutecho.com",
      "type": "identity/ack",
      "sticky": true
    }
  ]
}



 TOC 


13.4. 
Get Single Message

Retrieve a single message from the server.

Endpoint
/v2/message/<msg_id>:
The full endpoint URL constitutes the
messageURL obtained from a
Get Messages (Get Messages)
response.

HTTP mehod
GET
Security
HTTPS
Authorization
The client MUST present the access token obtained from a
Access Token Request (Authenticated Access Token Request)
as described in
section 2.1 (Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 2011.) [OAuth2.token.bearer],
to prove that it has access to the message.
The server MUST retrieve the
Access Scopes (Access Scopes)
associated with the presented access token, determine its
access level (Access Levels) and respond
accordingly with either a Backplane Header, a Backplane
Message (including payload), or error.

Query parameter
Returns
  • HTTP status code 404 (“Not Found”) if the message is
    no longer available.

  • HTTP status code 403 (“Forbidden”) if the client
    is not authorized to retrieve messages from the Bus
    the message belongs to.

  • On success, a HTTP status code 200 (“OK”) is returned,
    with the response body containing a Backplane Message
    JSON object, with the following fields:

    • messageURL (string):
      the URL of the message, see
      Get Single Message (Get Single Message)

    • source (string):
      an arbitrary URL identifying the client which has posted the message.

    • type (string):
      message type (arbitrary string).

    • bus (string):
      the bus name the message was posted to

    • channel (string):
      the channel name the message was posted do.

    • sticky (string):
      the sticky flag for the message, as specified by
      the application scenario that defines this
      message type

    • payload (object, OPTIONAL):
      message payload. Only available to privileged access clients.

Response example:

{
  "messageURL": "https://bp.example.com/v2/message/097a5cc401001f95b45d37aca32a3bd2",
  "source": "http://aboutecho.com",
  "type": "identity/ack"m
  "sticky": true,
  "bus": "customer.com",
  "channel": "67dc880cc265b0dbc755ea959b257118",
  "payload": {
    "role": "administrator"
  },
}



 TOC 


13.5. 
Post Message

Publishes a message to a Backplane framework.

Endpoint
/v2/message
HTTP mehod
POST
Security
HTTPS
Authorization
The client MUST present the access token obtained from a
Access Token Request (Authenticated Access Token Request)
as described in
section 2.1 (Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 2011.) [OAuth2.token.bearer].
The server MUST retrieve the
Access Scopes (Access Scopes)
associated with the presented access token and determine
that it has
Privileged Access Level (Privileged Access)
for each of the Buses referenced in the request body.

Request body
The body of the request is a JSON object of the following
structure:

  • message:
    a JSON object representing the Backplane message
    to be posted, with the following structure:

    • type (string):
      message type (arbitrary string)

    • bus (string):
      the name of the bus to post the message to

    • sticky (boolean, OPTIONAL):
      the sticky (Sticky Messages)
      flag; if omitted the Backplane Server MUST consider the
      posted message non-sticky

    • channel (string):
      the name of the channel to post the message to

    • payload (object):
      the message payload

Returns
  • HTTP status code 201 (“Created”) upon success.

  • HTTP status code 403 (“Forbidden”) if the client is
    not authorized to post messages to any of the
    referenced Buses. The server processes the messages
    in the request one by one; if a message can’t be
    posted for any reason, the whole request fails and
    none of the messages get posted.

The server MUST check that the channel in a message was
previously allocated as a result of a
Access Token Request (Authenticated Access Token Request).
If the channel is not yet bound to a bus, the server MUST bind
it to the bus specified in the same message object from the
request.
If the channel is already bound to a different bus than the
one specified in the same message object in the request, the
entire request is considered invalid and is aborted.

Request example:

{
  "message":
    {
      "type": "identity/ack",
      "sticky": true,
      "bus": "customer.com",
      "channel": "67dc880cc265b0dbc755ea959b257118",
      "payload": {
        "role": "administrator"
      }
    }
}



 TOC 


14. 
Backplane JavaScript API

A Backplane JavaScript Library runs in an end user’s browser
and mediates communication between Backplane-enabled Widgets on
the page and the Backplane Server.

Only one instance of the Backplane JavaScript Library on a
given page is possible. The library has to be the first to load
on the page to make it possible for other scripts to use its
subscription functionality.

The Backplane JavaScript Library provides the following
API (all methods are static):

/**
 * Initializes the backplane library
 *
 * @param {Object} Params - hash with configuration parameters.
 *   Possible hash keys:
 *     serverBaseURL (required) - Base URL of Backplane Server
 *     busName (required) - Customer's backplane bus name
 */
Backplane.init(Params);

/**
 * Subscribes to messages from Backplane server
 *
 * @param {Function} Callback - Callback function which accepts backplane messages.
 * @returns Subscription ID which can be used later for unsubscribing.
 */
Backplane.subscribe(Callback);

/**
 * Removes specified subscription
 *
 * @param {Integer} Subscription ID
 */
Backplane.unsubscribe(SubscriptionID);

/**
 * Returns channel ID (like http://backplane.customer.com/v2/bus/customer.com/channel/8ec92f459fa70b0da1a40e8fe70a0bc8)
 *
 * @returns Backplane channel ID
 */
Backplane.getChannelID();

/**
 * Notifies backplane library about the fact that subscribers are going
 * to receive backplane messages within specified time interval.
 *
 * @param {Integer} TimeInterval - Time interval in seconds
 * @param {Array} MessageTypes (optional) - a list of expected message types
 */
Backplane.expectMessagesWithin(TimeInterval, MessageTypes);



 TOC 


14.1. 
Initialization

A Backplane framework is initialized using the
Backplane.init method.

During initialization the library generates a random
Channel Name unless information about one for the specified
bus name already exists in the
backplane-channel cookie. Since
client-side generation of the channel name is non-secure,
the library performs a request to obtain a channel name
from the Backplane Server.

There can be at most one channel active on a Web Page at a
given time.

After initialization the library stores the current Channel
Name in the backplane-channel
cookie set against the complete domain name of currently
opened page. The cookie is set for 5 years in advance and
keeps information about association of Bus names to Channel
Names (to support possibility to use the library with several
different Bus names on the same domain). The information
about the association is stored in a serialized form.

Here is an example of cookie that stores association
of Bus names example.com and
example.org to the corresponding
channel names 123 and
456:

backplane-channel=example.com:123|example.org:456

After the channel ID has been determined, the library
performs a first reading of messages from a channel, discards
all of them (remembering only the identifier of the very
last one) and starts polling the Backplane Server for new
messages since the latest Backplane Message. This way the
library is guaranteed to push to subscribers only those
Backplane Messages which arrived after the library had been
fully initialized.



 TOC 


14.2. 
Subscription Management

The library provides a method for Widgets to set up
notification callbacks: Backplane.subscribe.
The method returns a subscription id which can be later used
for unsubscribing using the Backplane.unsubscribe
method.

After the initialization the library starts polling the
Backplane Server for new events. All incoming events are
delivered to the Widgets that have registered callbacks with
the library.



 TOC 


14.3. 
Hints

For performance reasons the Backplane JavaScript Library
polls the Backplane Server with a low frequency (e.g once a
minute). Since Backplane events usually are initiated
on the client side (e.g. the user clicking a button), Widgets
on the page are in a position to hint the library that a
Backplane Message may be soon delivered. Upon the receipt of
such hint (via
expectMessagesWithin method), the
library temporarily increases the polling frequency (e.g.
to once a second) and then gradually decreases it to the
default low value one.

The expectMessagesWithin method
can accept an optional list of expected message types.

If the library accepts any
message from the passed message types list, it gradually
returns to the lower polling frequency mode;

If messages with only one type are expected, the second
argument may be specified as a string;

Each call of the method adds passed message types to the
list of expected message types. In other words, if
a user calls the method with a message type “type1″ and
then performs one more call with a message type “type2″,
the library will run in the fast polling mode until it
received messages of all
the types or until the libray reached the maximum allotted
waiting time interval.



 TOC 


14.4. 
Usage Example

Backplane.init({
    serverBaseURL: "http://backplane.customer.com/v2",
    busName: "customer.com"
});

var escSubscription = Backplane.subscribe(function(backplaneMessage) {
    alert(backplaneMessage.payload);
});

// We can ask the library to perform more frequent polling
// if a widget, for example, expects a message from Backplane pretty soon
// using the expectMessagesWithin method which accepts
// time interval of possible message arrival in seconds
Backplane.expectMessagesWithin(10);

// The method can accept an option list with expected message types.
// The library stops fast polling when it receives a message of
// either type.
Backplane.expectMessagesWithin(10, ["type1", "type2"]);

// Subsequent calls extend the list of expected message types.
// The library stops fast polling only after it has received
// a message of type1 or type2 AND a message of type3 or type4.
Backplane.expectMessagesWithin(10, ["type3", "type4"]);

Backplane.unsubscribe(escSubscription);

// If a widget needs Backplane channel ID it can get it using the
// getChannelID method
Backplane.getChannelID();



 TOC 


15. 
Security Considerations

See Trust (Trust).



 TOC 


15.1. 
Channel Name Sensitivity

The Channel Name acts as a session identifier shared among a
group of trusted parties. Knowledge of a Channel Name offers
Regular Access level to Backplane Server API.

It is therefore important that the Channel Name is not
compromised, by either:

  • Trusting any third-party JavaScript source included in the
    Web Page without due verification, or

  • Disclosing Channel Names to untrusted parties.



 TOC 


15.2. 
Message Payloads

Message payloads are only sent to Backplane Clients at
Privileged Access Level (Privileged Access).
This is in order to allow sensitive data to be exchanged
among server-side Backplane Clients, while not allowing it to
reach the less secure context of web browser.

It is therefore important that
Privileged Access Level (Privileged Access)
credentials are not provisioned to Backplane Clients that run
in a web browser.



 TOC 

16. Normative References

[OAuth.Dynamic.Client.Registration] Hardjono, T., Machulak, M., Maler, E., and C. Scholz, “OAuth Dynamic Client Registration Protocol,” Oct 2011.
[OAuth2] Habber-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” May 2011.
[OAuth2.token.bearer] Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 2011.
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol — HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” RFC 2617, June 1999 (TXT, HTML, XML).
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, “Randomness Requirements for Security,” BCP 106, RFC 4086, June 2005 (TXT).
[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[RFC4648.section5] Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.



 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/
   
  Johnny Bufu
  Janrain
Email:  jbufu@janrain.com
URI:  http://www.janrain.com/