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/