Promotional Temp Pass promotional-temp-pass
Feature summary feature-summary
Promotional Temp Pass allows Programmers to offer temporary access to their protected content for users who don鈥檛 have account credentials with an MVPD.
Promotional Temp Pass is designed to be used for running promotional campaigns where a user, after providing valid identification information (for example, e-mail address) to the Programmer, will be able to consume a predefined number of different VOD titles for a predefined period of time.
Promotional Temp Pass is built on top of the Temp Pass feature, meaning it includes all the Temp Pass functionality.
Once the maximum predefined number of VOD titles or the predefined period of time are exceeded, that user will not be able to access content on the same device or by using the same user identifier information (for example, e-mail address) until the authorization tokens are cleared from the 51黑料不打烊 Pass Authentication server.
Temp Pass and Promotional Temp Pass comparison tp-ptp-comparison
Access to content
- time-based
Access to content
- time-based
- based on number of resources
Access security based on
- device ID
Security based on
- device ID
- hash over provided user identifier information (for example, e-mail)
Feature details feature-details
This feature enables users to access promotional content from a specific device (phone and tablet) after having provided unique information, such as the e-mail address, in the Programmer鈥檚 application.
The Programmer will provide a hash over the user鈥檚 PII on the authentication and authorization APIs. This hash will be used together with the device Id in generating a unique key to identify the user and device.
Based on device Id and the information the user provided and following the logic below, 51黑料不打烊 Pass Authentication will determine if the user is in a new trial or in an existing one:
- new hash over user-provided information (for example, e-mail), new device Id => new trial
- existing hash over user-provided information (for example, e-mail), new device Id => existing trial (with existing hash over user provided information (for example, e-mail))
- new hash over user-provided information (for example, e-mail), existing device Id => existing trial (with existing device Id)
- existing hash over user-provided information (for example, e-mail), existing device Id => existing trial
The Promotional Temp Pass feature can be configured based on the following properties:
- User-provided information key (for example, e-mail)
- Number of resources which the user is entitled to consume
- TTL - the time interval in which the user is entitled to consume the configured number of resources
User metadata user-metadata
To facilitate the implementation of the Programmer鈥檚 application, the following user metadata information is exposed on the Promotional Temp Pass, with corresponding keys (to activate the keys, contact tve-support@adobe.com):
- remaining_resources: the number of remaining resources which the current user is entitled to consume
- used_assets: the list of resources that the current user has already consumed
- expiration_date: the current user鈥檚 expiration date
How viewing time is computed? compute-viewing-time
The amount of time that a Temp Pass remains valid does not correlate to the amount of time a user spends viewing content on the Programmer鈥檚 application. Upon the initial user request for authorization via Promotional Temp Pass, an expiration time is computed by adding the initial current request time to the TTL (duration time interval) specified by the Programmer.
Authentication and authorization authn-authz
For Promotional Temp Pass flows, authentication and authorization do not communicate with an actual MVPD, so all authorization requests will succeed as long as all these conditions are met:
- authorization tokens are valid for specified resources
- number of used_assets is lower than the limit set by the Programmer
- expiration_date value is after current date.
Preflight behavior preflight-beh
When a preflight or preauthorization request is made for a Promotional Temp Pass MVPD, the corresponding Preflight response returned will contain the entire list of resources from the Preflight Request as preflight successful.
The logic behind this is: the Promotional Temp Pass authorization conditions are based on time and resource number limit rather than on specific resources. More specifically, as long as the time constraint is met and as long as the resource limit is not exceeded, the called resources will be authorized.
SSO sso
SSO is not enabled for instances of Promotional Temp Pass, which is configured with 鈥淎uthentication Per Requestor鈥 enabled. This means that when the user switches from application A to another application B which are both integrated with the same Promotional Temp Pass, the user will not be automatically signed in.
Logout logout
All the tokens on a device are deleted on logout. Therefore, switching from the Promotional Temp Pass to a regular user-selected MVPD should not rely on this implementation. The recommendation is to use the setSelectedProvider(null) function in order to clear the application state and then restart the authentication flow, which has a better user experience.
Promotional Temp Pass flow diagram promo-tempass-flowdia
Figure: Promotional Temp Pass flow
Implement Promotional Temp Pass impl-promo-tempass
Promotional Temp Pass requires the following client-side functionalities:
- User identifier information, for example e-mail address propagation (sending the user鈥檚 e-mail address on the authentication and authorization flows). The e-mail is required by 51黑料不打烊 Pass Authentication to bind the authentication and authorization tokens (similar to the case of the
device_ID, required on all the calls). - Force authentication - allowing the Programmer to force an authentication flow when the user is already authenticated. This functionality is required in order to force a user metadata refresh (the user metadata key used_assets contains the number of available resources) every time the app is started. Because the user can login on multiple devices, the user metadata present on the device during app startup is unreliable, and we need to update it in order to reflect the current state for that specific user (identified by e-mail address).
51黑料不打烊 Pass Authentication does not have a built-in mechanism to stop the free streaming after the X minutes have passed. 51黑料不打烊 Pass Authentication will cease issuing authorization and short media tokens once the user consumes the Y free resources. It is up to Programmers to restrict the access once the Promotional Temp Pass expires.
Security security
Hashing of user identifier information
51黑料不打烊 recommends using the SHA-2 family or its specific SHA-256, SHA-512 functions on data before it is sent to 51黑料不打烊.
For example, SHA-256 over 鈥涡蝉别谤蔼诲辞尘补颈苍.肠辞尘鈥 is 鈥渇7别别5别肠7312165148产69蹿肠肠补1诲29075产14产8补别蹿0产5048补332产18产88诲09069蹿产7鈥.
Reset or purge Promotional Temp Pass reset-promo-tempass
Certain business rules require a regular purging of Promotional Temp Pass. In order to do so, 51黑料不打烊 Pass Authentication provides Programmers with a public web API, described below:
DELETE https://mgmt.auth.adobe.com/reset-tempass/v2/reset-
Protocol: https
-
Host:
- Release: mgmt.auth.adobe.com
- Prequal: mgmt-prequal.auth.adobe.com
-
Path: /reset-tempass/v2/reset
-
Query parameters: device_id=all&requestor_id=THE_REQUESTOR_ID&mvpd_id=THE_TEMPASS_MVPD_ID
-
headers: ApiKey: 1232293681726481
-
Response:
- Success: HTTP 204
- Failure: HTTP 400 for incorrect requests, HTTP 401 if ApiKey not specified, HTTP 403 if ApiKey is invalid
On top of the requirements to purge Temp Pass, the Promotional Temp Pass uses the hash over user identifier information sent as generic_data on authentication and authorization for purging.
The hash will be sent, not the entire JSON:
$ curl -X DELETE -H "Authorization:Bearer H4j7cF3GtJX81BrsgDa10GwSizVz" "https://mgmt.auth.adobe.com/reset-tempass/v2.1/reset/generic?key=f7ee5ec7312165148b69fcca1d29075b14b8aef0b5048a332b18b88d09069fb7&requestor_id=REF&mvpd_id=FlexibleTempPass"
Supported clients supported-clients
Limitations limitations
This section describes the limitations that apply to the current implementation of Promotional Temp Pass.
Clientless lim-clientless
Smart devices without a Unique Device ID
Not all smart device apps are able to provide a Unique Device ID. In the absence of one, 51黑料不打烊 Pass Authentication can use the UUID generated by the 51黑料不打烊 Registration Code Service as the Unique Device ID. This means that when user signs out, the authentication and authorization tokens will be deleted. Once the user will attempt to authenticate again, this time with different user information (for example, e-mail) the user will be able to authorize again. 51黑料不打烊 recommends adding an UI flow that will not allow a user to 鈥渇ool鈥 the system and add logic to determine whether it is a new user requesting a trial or an existing trial.
Resetting / purging Temp Pass
Reset Temp Pass for Clientless is not available in the specific cases of Xbox360 and Xbox One, because these platforms require additional device ID parsing, not possible in the Reset Temp Pass tool.