(Legacy) REST API Cookbook (Client-to-Server) rest-api-cookbook-client-to-server
Overview overview
This document provides step-by-step instructions for a Programmer’s engineering team to integrate a “smart device” (game console, smart TV app, set top box, etc.) with Adobe Pass Authentication using REST API services. This Client-to-Server approach, which uses REST APIs rather than a client SDK, allows for broader support of different platforms for which developing a significant number of unique SDKs would not be feasible. For a broad technical overview of how the Clientless solution works, see the Clientless Technical Overview.
This approach requires two components (streaming app and AuthN app) to complete the required flows: start-up, registration, authorization, and view-media flows in the streaming app, and the authentication flow in your AuthN app.
Throttling mechanism
The Adobe Pass Authentication REST API is governed by a Throttling mechanism.
Components components
In a working Client-to-Server solution the following components are involved:
Flows flows
Dynamic Client Registration (DCR)
Adobe Pass uses DCR to secure client communications between a programmer application or server and the Adobe Pass services. The DCR flow is separate and is described in the Dynamic Client Registration Overview documentation.
Streaming (Smart Device) App Flows
Startup Flow
-
Your app starts and loads its initial UI.
-
Obtain / generate a device ID.
-
Issue a Check-authentication call to see if the device is already authenticated. For example:
<SP_FQDN>/api/v1/checkauthn [device ID] -
If the
checkauthncall succeeds, proceed to the Authorization Flow from Step 2 onwards. If it fails, start the Registration Flow.
Registration Flow
-
Get a registration code and URL for your user to use to access your 2nd screen login app, and present these to the user:
a. Send a POST request to the Adobe Registration Code Service, passing a hashed device ID and a “Registration URL”. For example:
<REGGIE_FQDN>/reggie/v1/[requestorId]/regcode [device ID]b. Present the returned registration code and URL to the user.
c. Instruct the user to switch to a web-capable device, navigate to the URL, and then enter the registration code.
Authorization Flow
-
The user returns from the 2nd screen app and presses the “Continue” button on your device. Alternatively, you could implement a polling mechanism to check the authentication status, but the Adobe Pass Authentication recommends the Continue button method over polling. For example: <SP_FQDN>/api/v1/tokens/authn
-
Send a GET request to the Adobe Pass Authentication authorization service to initiate authorization. For example:
<SP_FQDN>/api/v1/authorize [device ID, Requestor ID, Resource ID]
-
If the response indicates success: The user has a valid AuthN token AND the user is authorized to watch the requested media (there is a valid AuthZ token for this user).
-
If the response indicates failure: Examine the Exception thrown to determine its type (AuthN, AuthZ, or something else):
-
If it was an AuthN error then re-start the Registration Flow.
-
If it was an AuthZ error then the user is not authorized to watch the requested media and some kind of error message should be displayed to the user.
-
If there was some other error (connection error, network error, etc.) then display an appropriate error message to the user.
-
View Media Flow
-
Present media choices. The user selects the media to view.
-
Is the media protected?
a. Your app checks if the media is protected.
b. If the media is protected, your app starts the Authorization
(AuthZ) Flow above.c. If the media is not protected, then playback the media for the
user. -
Playback the media.
AuthN (2nd Screen) App Flow
-
Get a list of MVPDs for this user. For example:
<SP_FQDN>/api/v1/config/[requestorID] -
Initiate the authentication flow. For example:
<SP_FQDN>/api/v1/authenticate [requestorID, MVPD ID, Redirect URL, Domain name, Registration Code, "noflash=true"] -
Check whether the authentication was successful. For example:
<SP_FQDN>/api/v1/checkauthn/[registration code][requestor ID] -
Send the user back to your Smart Device app to complete the authorization flow.
Partner Single Sign-On partner-sso
Some devices provide dedicated support for Partner Single Sign-On (SSO):
Platform Single Sign-On platform-sso
Some devices provide dedicated support for Platform Single Sign-On (SSO):
TempPass and Promotional TempPass for REST API temppass
For TempPass and Promotional TempPass implementations where the user is not required to enter credentials, authentication can be implemented directly in the Streaming App.
In order to use this API the Streaming App needs to make sure of the uniqueness of the device ID as this is being used for identifying the token, along with the optional extra data.
