Programmer integration guide programmer-integration-guide
This integration guide is intended for content providers (Programmers) who plan to integrate with ۶Ƶ® Pass Authentication.
In today’s digital landscape, viewers can access the Internet anytime, anywhere, and request access to your protected content. They might be looking to watch a one-time event or seeking the rights to stream an entire television series you are airing.
Before granting access to protected content, you must determine whether the viewer is entitled to it. Key questions include:
- Does the viewer have an active subscription with a Multichannel Video Programming Distributor (MVPD)?
- Does that subscription include your programming?
۶Ƶ Pass Authentication for TV Everywhere adobe-pass-authentication-for-tv-everywhere
For Programmers, determining entitlement is not always straightforward. MVPDs are the custodians of their customers’ identifying data and access privileges. Complicating matters further, Programmers viewers may subscribe to a wide variety of MVPDs, each operating with unique systems. These complexities make verifying entitlement both technically challenging and resource-intensive.
User Entitlement Determined Directly By Programmer
۶Ƶ Pass Authentication securely facilitates entitlement transactions between Programmers and MVPDs, making it quick, easy, and secure to provide protected content to eligible viewers.
User Entitlement Mediated by ۶Ƶ Pass Authentication
۶Ƶ Pass Authentication acts as a proxy and facilitates the entitlement flow between Programmers and MVPDs by offering secure and consistent interfaces for both parties.
For Programmers, ۶Ƶ Pass Authentication provides APIs as part of a Standard or a Premium tier:
-
Standard ۶Ƶ Pass Authentication APIs:
-
Premium ۶Ƶ Pass Authentication APIs:
Use Cases use-cases
This section outlines further the Programmer integration use cases supported by ۶Ƶ Pass Authentication:
-
Programmer (TVE) application with a single channel network
This enables the Programmer to provide viewers with access to the content from a single-branded channel network within a TVE application.
-
Programmer (TVE) application with multiple channel networks
This enables the Programmer to provide viewers with access to the content from multiple channel networks within a single TVE application.
-
Programmer (TVE) application for special events
This enables the Programmer to provide viewers with access to the content of special events that may not be resources that are in the MVPD entitlement database like normal channels.
Entitlement Flow entitlement-flow
The entitlement flow is a series of steps that a Programmer (TVE) application must complete to stream protected content. The flow consists of the following phases:
On a user’s initial visit to a Programmer (TVE) application, the entitlement flow follows the outlined sequence. However, on subsequent visits, the application may bypass certain steps based on the status of the registration or authentication and the applicable viewing policies.
For a detailed exploration of the entitlement flow and its phases, continue reading this document, and after refer to the accompanying cookbook guides for additional insights:
Registration Phase registration-phase
The purpose of the Registration Phase is to register the client application against ۶Ƶ Pass Authentication through the Dynamic Client Registration (DCR) process.
The Dynamic Client Registration (DCR) process requires the client application to obtain a pair of client credentials and retrieve an access token as the end goal of the Registration Phase.
APIs
Flows
FAQs
Configuration Phase configuration-phase
The purpose of the Configuration Phase is to provide the client application the list of MVPDs with which it is actively integrated along with configuration details saved by ۶Ƶ Pass Authentication for each MVPD.
The Configuration Phase acts as a prerequisite step for the Authentication Phase when the client application needs to ask the user to select their TV Provider.
APIs
FAQs
Authentication Phase authentication-phase
The purpose of the Authentication Phase is to provide the client application the capability to verify the user’s identity with the MVPD and obtain user metadata information.
The Authentication Phase acts as a prerequisite step for the Preauthorization Phase or Authorization Phase when the client application needs to play content.
Successful authentication generates a profile tied to the application, device and service provider, containing also user metadata information.
High-level Steps
The following steps outline the high-level steps in case of a SAML integration:
-
Programmer’s Application (Website) Load
The user navigates to the Programmer’s application (website), which integrates ۶Ƶ Pass Authentication REST API V2. -
Protected Content Request
When the user attempts to access protected content, the Programmer’s application displays a list of MVPDs for the user to select from. -
Authentication Request Initialization
Upon MVPD selection, the user is redirected to an ۶Ƶ Pass Authentication server. Here, an encrypted SAML authentication request for the selected MVPD is generated, in case of a SAML integration. This request is sent on behalf of the Programmer to the MVPD. Depending on the MVPD’s system, the user’s browser is either redirected to the MVPD’s login page or a login iFrame is embedded within the Programmer’s application. -
MVPD Login
The MVPD accepts the request and presents its login interface, either via redirect or iFrame. -
User Login and Validation
The user logs in with their MVPD credentials. The MVPD validates the user’s subscription status and establishes its own HTTP session. -
MVPD Response to ۶Ƶ Pass Authentication
Once validation is complete, the MVPD generates a SAML response (encrypted) and sends it back to ۶Ƶ Pass Authentication. -
Profile Generation
۶Ƶ Pass Authentication verifies the SAML response, generates a user profile that gets cached, and redirects the user back to the Programmer’s application (website).
APIs
Flows
FAQs
Single Sign-On (SSO) single-sign-on
APIs
Flows
(Optional) Preauthorization Phase preauthorization-phase
The purpose of the Preauthorization Phase is to provide the client application the capability to present a subset of resources from its catalog that the user would be entitled to access.
The Preauthorization Phase can enhance the user experience when the user opens the client application for the first time or navigates to a new section.
APIs
Flows
FAQs
Authorization Phase authorization-phase
The purpose of the Authorization Phase is to provide the client application the capability to play resources the user requests after validating their rights with the MVPD.
Successful authorization generates a decision, containing also a media token that is provided to the Programmer (TVE) application for security purposes.
High-level Steps
The following steps outline the high-level steps:
-
Resource Identifier Handling
The protected content is identified by a resource identifier, which may be a simple string or a more complex structure. This identifier is predefined and agreed upon by the Programmer and the MVPD. The Programmer’s application sends the resource identifier to the ۶Ƶ Pass Authentication REST API V2. -
MVPD Authorization Check
۶Ƶ Pass Authentication server communicates with the MVPD’s authorization endpoint using standardized protocols. -
MVPD Response to ۶Ƶ Pass Authentication
Once validation is complete, the MVPD confirms the user is entitled (or not) to access the content and sends a response back to ۶Ƶ Pass Authentication. -
Decision and Media Token Generation
۶Ƶ Pass Authentication verifies the response, generates a decision that gets cached, and returns the decision containing a media token back to the Programmer’s application (website). -
Content Access Verification
The Programmer’s application uses the Media Token Verifier to confirm that the correct user is accessing the correct content. Once validated, the user is granted access to view the protected content.
APIs
Flows
FAQs
Logout Phase logout-phase
The purpose of the Logout Phase is to provide the client application the capability to terminate the user’s authenticated profile within ۶Ƶ Pass Authentication upon user request.
APIs
Flows
FAQs
Single Logout (SLO) single-logout
Flows
Understanding Entitlements understanding-entitlements
The ۶Ƶ Pass Authentication solution revolves around the creation of entitlements—specific pieces of data generated upon the successful completion of authentication and authorization workflows. These entitlements grant access to protected content but have a limited lifespan. Once an entitlement expires, it must be renewed by re-initiating the authentication or authorization processes.
For more details about entitlements, refer to the following documents:
-
Profiles
Upon successful authentication, ۶Ƶ Pass Authentication creates an authenticated profile (“long-lived”) associated with the requesting application, device and service provider identifier (requestor identifier).
-
Upon successful authentication (and in some cases after authorization too), ۶Ƶ Pass Authentication receives user metadata from the MVPD that can expose it to the requesting application.
-
Upon successful authorization, ۶Ƶ Pass Authentication creates an authorization decision (“long-lived”) associated with the requesting application, device, service provider identifier (requestor identifier) and a specific protected resource (resource identifier).
-
Upon successful authorization, ۶Ƶ Pass Authentication creates a media token (“short-lived”) that is associated with a successful play request and provides support for industry best practices for mitigating fraud (e.g., stream ripping).
The time-to-live (“TTL”) values for profiles and decisions are set based on agreements between Programmers and Pay TV providers, who agree on a value that best serves everyone involved.