The programmer entitlement flow prog-entitlement-flow

Overview overview

This document describes the basic entitlement flow from the Programmer’s perspective. For information on features and use cases beyond the basic TVE integration covered here, see Programmer use cases.

Adobe Pass Authentication mediates the entitlement flow between Programmers and MVPDs by providing secure, consistent interfaces for both parties. On the Programmer’s side, Adobe Pass Authentication provides two general types of entitlement interface:

In addition to the platform-neutral overview presented here, there is a Clientless API-specific overview here: Clientless API documentation. The AccessEnabler runs natively on supported platforms (AS / JS on Web, Objective-C on iOS, and Java on Android). The AccessEnabler APIs are consistent across the supported platforms. All of the platforms that do not support AccessEnabler use the same Clientless API.

For both types of interface, Adobe Pass Authentication securely mediates the entitlement flow between the Programmer’s app and the user’s MVPD:

Figure: Adobe Pass Authentication Ecosystem

Entitlement Flow entitlement-flow

There are four distinct sub-flows that make up the basic entitlement
flow:

On a user’s initial visit to a Programmer’s site the entitlement flow proceeds in the order above. However, on subsequent visits, depending upon whether authentication and authorization tokens have expired or not, or depending upon viewing policies, a user might only go through one or two of the sub-flows.

Startup Flow startup

Establishes the identity of the Programmer and the device, performs initialization tasks. This is a prerequisite for all subsequent entitlement calls.

AccessEnabler

Clientless API

Authentication Flow authentication

Successful authentication generates an AuthN token tied to the device and requestor. Successful authentication is a prerequisite for Authorization.

AccessEnabler

Clientless API

An AuthN token is considered valid if the following two points are true:

Generic AccessEnabler Initial Authentication Workflow generic-ae-initial-authn-flow

Authorization Flow authorization

Authorization is a prerequisite for viewing protected content. Successful authorization generates an AuthZ token, along with a short-lived Media Token that is provided to the Programmer’s app for security purposes. Note that, to support the authorization workflow, you must have previously performed the necessary requestor setup and have integrated the Media Token Verifier. With these completed, you can initiate authorization.

Your app initiates authorization when a user requests access to a protected resource. You pass a resource ID specifying the requested resource (for example , a channel, episode, etc.). Your app first checks for a stored authentication token. If one is not found, you initiate the authentication process.

AccessEnabler

You provide the following callback functions to handle the results of
the authorization call:

Clientless API

Generic AccessEnabler Authorization Workflow generic-ae-authr-wf

Logout flow logout

Clears tokens and other data associated with the current user’s entitlement flow.

AccessEnabler

Clientless API

Understand AccessEnabler behavior ae-behavior

All AccessEnabler API calls are asynchronous (with one exception, noted in the API references). You can call an API an arbitrary number of times, however there is no strong guarantee that the actions triggered
by the calls will be completed in the same order that the calls were made. (An exception to this is the current Flash Player runtime; not being multi-threaded it will ensure calls do complete in the order
they are called.)

In order to distinguish between responses, and be able to pair responses with calls, all callbacks echo back their input parameters. This includes setToken() andtokenRequestFailed(), which are triggered ultimately by checkAuthorization(). (For checkAuthorization() callbacks, the resource used is echoed back.) Taking advantage of this feature, you can distinguish which response corresponds to which call. To use this feature you could code something like the following:

    for each (resource in ["TNT", "CNN", "TBS", "AdultSwim"] ) {
         ae.checkAuthorization(resource);
    }

    // Success callback
    function setToken(resource, token) {
         // Use "resource" to figure
         // out which checkAuthorization
         // call triggered this response
    }

    // Old error callback
    function tokenRequestFailed(resource, error, details) {
         // use "resource" to figure
         // out in response to which
         // checkAuthorization call
         // this was triggered
    }

    // Error callback using new error api
    ae.bind("errorEvent',"errorHandler");

    function errorHandler(error) {
         if(error.resource) {
              // Use error.resource to figure
              // which checkAuthorization call
              // triggered this response
         }
    }

AE Behavior FAQ ae-beh-faq

Question. What happens if I make a second AccessEnabler call before the first call finishes?

The first call continues to execute as the second call executes (asynchronous communications).

Question. Is there a maximum number of simultaneous calls that AccessEnabler can support?

No limit is set explicitly in the AccessEnabler code, so you are limited only by your available system resources, as well as by the MVPD’s capacity.