REST API V2 Cookbook (Server-to-Server) rest-api-v2-cookbook-server-to-server
The purpose of this cookbook document is to detail best practices for implementing ÃÛ¶¹ÊÓƵ Pass Authentication using the REST API V2 in a Server-to-Server architecture. It provides basic requirements, step-by-step flow implementation and general considerations for production environments and operation.
Components components
In a working Server-to-Server solution, the following components are involved:
Additional terms used in the flow are defined in the Glossary.
The following diagram illustrates the entire flow:
Steps to implement the REST API V2 in server-to-server architecture steps-to-implement-the-rest-api-v2-in-server-to-server-infrastructure
To implement ÃÛ¶¹ÊÓƵ Pass REST API V2, you need to follow the steps below grouped into phases.
0. Prerequisites prerequisites
In Server-to-Server implementations, the Streaming App and Programmer Service needs to establish a protocol for Programmer Service to be able to:
- Uniquely identify the Streaming App on the device.
- Act on behalf of the Streaming App and communicate with ÃÛ¶¹ÊÓƵ Pass Service.
- Collect and store information about the Streaming App and the device like IP address, source port, device information to pass it to ÃÛ¶¹ÊÓƵ Pass.
- Return decisions and instructions to the Streaming App.
Parameters like device ID, client id, client secret (defined below) can be stored on either Streaming App or Programmer Service.
A. Registration phase registration-phase
Step 1: Register your application step-1-register-your-application
For the application to be able to call ÃÛ¶¹ÊÓƵ Pass REST API V2, it needs an access token required by the API security layer.
For Server-to-Server implementations, the Programmer Service can register on behalf of an application instance, yet the client credentials (client id and client secret) values need to be obtained for each streaming device.
To get the access token, the Programmer Service can act on behalf of a Streaming App and needs to follow steps as described in the Dynamic Client Registration documentation.
B. Authentication phase authentication-phase
Step 2: Check for existing authenticated profiles step-2-check-for-existing-authenticated-profiles
The Programmer Service checks on behalf of the Streaming App for existing authenticated profiles: /api/v2/{serviceProvider}/profiles (Retrieve authenticated profiles).
-
If no profile found and Streaming application implements a TempPass flow
- Follow documentation on how to implement Temporary access flows
-
If no profile found, Streaming application implements an Authentication flow
-
Step 2.a: the Programmer Service retrieve the list of MVPDs available for serviceProvider: /api/v2/{serviceProvider}/configuration
(Retrieve list of available MVPDs) -
The Programmer Service may implement filtering on the list of MVPDs and display only MVPDs intended while hiding others (TempPass, test MVPDs, MVPDs under development, etc.)
-
The Programmer Service should return a filtered MVPD list for the Streaming App to display picker, User selects the MVPD
-
With the MVPD selected from Streaming App, the Programmer Service creates a session: /api/v2/{serviceProvider}/sessions
(Create authentication session)- A CODE and URL to use for authentication is returned
- If a profile is found, the Programmer Service may proceed to C. Preauthorization phase
-
The Programmer Service should return the CODE and URL to the Streaming App
-
Step 3: Authenticate the user step-3-authenticate-the-user
Using a Browser or a Second Screen Web-based application:
- Option 1. Streaming App can open a browser or webview, load the URL to authenticate, and the user lands on MVPD login page where credentials need to be submitted
- User enters login/password, final redirect shows a success page
- Option 2. Streaming App can’t open a browser and just display the CODE. A separate web application, AuthN_APP, needs to be developed to ask the user to enter CODE, build and open URL: /api/v2/authenticate/{serviceProvider}/{CODE}
- User enters login/password, final redirect shows a success page
Step 4: Check for authenticated profiles step-4-check-for-authenticated-profiles
The Programmer Service checks for authentication with MVPD to complete in Browser or Second Screen
- Polling every 15 seconds is recommended on /api/v2/{serviceProvider}/profiles/{mvpd}
(Retrieve authenticated profiles for specific MVPD)- If MVPD selection is not made in the Streaming application as the MVPD picker is presented in the Second Screen application, the polling should happen with CODE /api/v2/{serviceProvider}/profiles/code/{CODE}
(Retrieve authenticated profiles for specific CODE)
- If MVPD selection is not made in the Streaming application as the MVPD picker is presented in the Second Screen application, the polling should happen with CODE /api/v2/{serviceProvider}/profiles/code/{CODE}
- Polling should not exceed 30 minutes, in case 30 minutes are reached, and the Streaming Application is still active, a new session needs to be initiated and a new CODE and URL will be returned
- When authentication is complete, the return is 200 with authenticated profile
- The Programmer Service may proceed to C. Preauthorization phase
C. Preauthorization phase preauthorization-phase
Step 5: Check for preauthorized resources step-5-check-for-preauthorized-resources
With a valid authentication profile for a user, the Programmer Service has the possibility to check the access to the videos available and pass the list to the Streaming Application to display.
- Step is optional and executed if the application wants to filter out the resources not available in the authenticated user package
- Call to /api/v2/{serviceProvider}/decisions/preauthorize/{mvpd}
(Retrieve preauthorization decision using specific MVPD)
D. Authorization phase authorization-phase
Step 6: Check for authorized resources step-6-check-for-authorized-resources
Streaming App prepares to play a video/asset/resource selected by the user.
-
Step is necessary for every play start
-
Streaming App passes this information to the Programmer Service
-
The Programmer Service on behalf of the Streaming App, call /api/v2/{serviceProvider}/decision/authorize/{mvpd}
(Retrieve authorization decision using specific MVPD)- decision = ‘Permit’, Programmer Service instructs the Streaming App to start streaming
- decision = ‘Deny’, Programmer Service instructs the Streaming App to inform the user that it does not have access to that video
- in the process, the Programmer Service may evaluate other business rules and return appropriate decision to the Streaming App
E. Logout phase logout-phase
Step 7: Logout step-7-logout
Streaming App: User wants to log out from the MVPD
- Streaming App informs the Programmer Service that it needs to log out from the MVPD for this specific App.
- The Programmer Service may clean up the information it stores about the authenticated user
- The Programmer Service call /api/v2/{serviceProvider}/logout/{mvpd}
(Initiate logout for specific MVPD) - If the response actionType=‘interactive’ and url is present, the Programmer Service will return to the Streaming App the url
- Based on existing capabilities, the Streaming App may open the url in the browser (usually the same one as used for authentication)
- If the Streaming App does not have a browser, or it is a different instance than the one at authentication, the flow can be stopped as the MVPD session was not persisted in the browser cache.
Environments and Functional Requirements environments
A Programmer should create at least two environments: one for production, and one or more for staging.
Production
The production environment should be highly available and scaled appropriately for large or unexpected spikes (e.g., live sports, breaking news).
The ÃÛ¶¹ÊÓƵ Pass Service runs on multiple data centers geographically dispersed throughout the US. To achieve the best response time (i.e., the lowest latency) from the ÃÛ¶¹ÊÓƵ Pass service, the Programmer should also create a similar geographically dispersed service infrastructure.
The Programmer Service should limit the DNS cache to a maximum of 30s in case ÃÛ¶¹ÊÓƵ needs to reroute traffic. This may occur if a data center becomes unavailable.
The Programmer should provide the public IP range of the production environment. These will be entered into an allowed-list of IPs in ÃÛ¶¹ÊÓƵ Pass infrastructure for access and managed by ÃÛ¶¹ÊÓƵ’s Fair API usage policies.
Staging
The staging environment can be minimal, but should include all system components and business logic. It should function similarly to production and allow for testing releases outside of production. Ideally, the staging environment can be connected to the ÃÛ¶¹ÊÓƵ Pass testing environments for use by the Programmer, and by ÃÛ¶¹ÊÓƵ when needed, so we can help in testing and troubleshooting.
Functional Requirements
The Programmer Service must pass along accurate device identification information for the device for which they are executing the flows. Additionally, the Programmer service must pass the IP of the device for which they are executing the flows (in an x-forwarded-for header) along with the connection source port (in the device info field):
The Programmer Service should send data and formating required by individual MVPDs or integrated apps (e.g., device IP, source port, device information, MRSS, optional data such as ECID). .
The Programmer Service must respect authentication profile and decisions validity when caching and invalidate the authentications or decisions when notified.
The Programmer Service must maintain certificates shared with ÃÛ¶¹ÊÓƵ (for encrypted user metadata).