content protection developer guide

CONTENT PROTECTIONDEVELOPER GUIDE

CONTENT PROTECTION DEVELOPER GUIDE | TOC | 2WWW.OOYALA.COM • [email protected] • 1-877-3-OOYALA

CONTENTS

CONTENT PROTECTION OVERVIEW 5Protecting Your Content 5Gauging The Necessary Protection 5Survey of Content Protection Technology 6

Protected Streams 7Playback Authorization, Including Token-based Authentication and Restrictions 8Digital Rights Management (DRM) Systems 9Content Protection Options By Device 9

Warning About Web Browser Third-party Cookies 11

AUTHENTICATION 12Ooyala Player Token 12

Warning About Web Browser Third-party Cookies 17Controlling Playback with the Ooyala Player Token 17Ooyala Player Token Expiration 18Setting the Ooyala Player Token 19Using Ooyala Player Token with Ooyala iOS and Android SDKs 20

Akamai Secure Token 22Integrating Adobe Pass with Ooyala Player 23Adobe Pass Integration Reference 25Ooyala Account Token API 28

AUTHORIZATION 31Player Authorization API for Player V3 31Player Authorization API for Player V4 35Limiting Concurrent Streams per Viewer 39Enforcing Per-Studio Limits on Concurrent Streams 45Stopping Unauthorized Streams 49

ACCESS CONTROL 51

RIGHTS MANAGEMENT 52Rights Locker 52

Prerequisites to Rights Locker 52Key Concepts 53Your Users, Your Accounts: Security 54How Authorization Works 54Backlot Setup 54Extended Example of Rights Locker 55

Binding Viewer Devices to Entitlements 56

DEVICE REGISTRATION 60Device Registration API 60

Properties for Device Registration 63

CONTENT PROTECTION DEVELOPER GUIDE | TOC | 3WWW.OOYALA.COM • [email protected] • 1-877-3-OOYALA

Device Management API for User Portals 65Device Registration API for Customer Support Portals 67

DIGITAL RIGHTS MANAGEMENT 71DRM Attributes for Remote Assets (Including Live Streams) 71Apple FairPlay 76Widevine Modular Content Protection 79PlayReady Content Protection 82

PlayReady Workflow 83PlayReady Example 85

Adobe Access DRM (Deprecated) 87Configurable DRM 88

Assigning DRM Policies 89Deleting DRM Policies 90

CONTENT PROTECTION DEVELOPER GUIDE | COPYRIGHT NOTICE | 4

COPYRIGHT NOTICE

Copyright Ooyala 2008-2017

Ooyala, Backlot, Ooyala Actionable Analytics, the Ooyala logo, and other Ooyala logos and product andservice names are trademarks of Ooyala, Inc. (“Ooyala Marks”). Company agrees not to remove anyOoyala Marks that are contained within and/or affixed to the Services as provided to Company. Exceptwith respect to the foregoing, Company agrees not to display or use in any manner the Ooyala Markswithout Ooyala’s prior written permission. All contents of the Ooyala website and Services are: Copyright2008-2017. Ooyala, Inc. All rights reserved. Ooyala and Backlot are registered trademarks of Ooyala, Inc.in the United States, Japan, and European Community. All rights reserved.

For complete information on terms of service, see: http://www.ooyala.com/tos

All other trademarks are the property of their respective companies.

This content was last updated on 2017-Jan-03

CONTENT PROTECTION DEVELOPER GUIDE | CONTENT PROTECTION OVERVIEW | 5

CONTENT PROTECTION OVERVIEW

Content Protection spans a range of strategies and technologies that are critical to the security ofproprietary content. Individual content owners need various levels of online video protection, and in someinstances those protections are a regulatory or contractual requirement for publishers and rights holders.Now more than ever, content protection is critical as users expand their video viewing across a multitude ofdevices.

Content providers should understand the technologies and capabilities needed to protect their valuablevideo assets, and they must consider security options that offer geographic, time-based or user-basedrestrictions. Publishers must focus on giving their users the highest quality video possible while alsoenforcing their business models. Protecting content is not about keeping people out. Instead, it’s amethodology that can both protect and enable content globally on just about any device.

WHY PROTECT YOUR CONTENT?

As the proliferation of digital streaming and download services provides more opportunities for viewers,it also expands the number of ways in which content needs to be protected. Content protection hasnecessarily become a complex art, and matching the right protection strategy to the nature of the contentis vital. A single approach is unlikely to work for premium VOD, linear TV streams, and pay-per-view liveevents, for example.

Content protection is not one-size-fits-all. Matching the right protection strategy to each type of contentis essential. Protection needs are based on the value of the publisher’s content, and matching the rightprotection strategy is critical in making premium video accessible.

And the same goes for consumers: What will work for some viewers and devices won’t work for others.The goal is to identify the best model for the publisher’s business that allows delivery of premium,protected content seamlessly across a multitude of devices.

PROTECTING YOUR CONTENTTo protect your content, consider the content itself and the available technologies.

In planning how to protect your content, there are two major considerations:

1. The nature of the content itself2. The suitability and cost of available protection technologies

GAUGING THE NECESSARY PROTECTIONThe protection you need depends on the nature of your content.

A wide variety of video content is distributed on the Internet, from extremely low-budget videos shot onsmartphones to Hollywood blockbusters. Here are a few questions to consider. Your company might haveother factors you need to consider, as well.

1. What is the value of content?2. Is the content ephemeral or long-lasting?3. What is your business's revenue model? Is the content monetized? If so, how? Is it through advertising,

Pay-Per-View, subscription?


The table below ranks revenue models and the types of associated content in order of increasingvalue. The requirements for content protection increase as content value increases.

Revenue model Examples of Content Type

Anonymous viewers, ad-funded Short-form content, video clips

Authenticated viewers, ad funded Longer form content, live video

Subscription High-value content

Transaction (rental or electronic sell-through) Studio-quality content

4. How great is the potential threat of hackers stealing your content?5. What is the sophistication of potential attackers?6. How important is usability and ease-of-access to the content? Making the content difficult to access

can reduce the number of viewers.7. How much money is your company willing to invest to protect the content?

You might require a hybrid solution: more costly protection for your highest valued content and less costlyprotection for less valuable content.

SURVEY OF CONTENT PROTECTION TECHNOLOGYThe types of content protection available today can be categorized into three groups.

Content protection can be imagined along two axes: the value of the content and the level of protection.

Thus, in increasing protection, the technology options for protecting your content with Ooyala are:

1. Protected streams2. Playback authorization, including token-based authentication3. Digital Rights Management (DRM) systems

PROTECTED STREAMS

There are several technologies that secure the actual stream of data to your customers.


Streaming protocols in general have encryption or other protections designed into them. See the detailsin Protected Streams on page 7. To implement these protections, you do not need to do anything.Ooyala provides this protection.

Limits on concurrent streams are another form of stream-level protection. See more details in Limits onConcurrent Streams on page 8.

PLAYBACK AUTHORIZATION

Playback authorization (a general term to cover various technologies) can be an additional security layeron top of protected streaming. Among these technologies are:

1. Token-based authentication. Required for RTMPE and ensures that encrypted content cannot bedownloaded until the client has been verified and prevents content from being played in a non-Ooyalaplayer. There are several kinds of token-based systems:

• User-authentication tokens, like the Ooyala Playback Token detailed in Ooyala Player Token onpage 12.

• CDN tokens, like Akamai Token-based Authentication. See Akamai Secure Token on page 22.2. Distribution systems, like Widevine. See Widevine Modular Content Protection on page 79.3. Adobe Pass. See Integrating Adobe Pass with Ooyala Player on page 23.

DIGITAL RIGHTS MANAGEMENT (DRM) SYSTEMS

Although there are many different DRM systems on the market, in general they all:

• Provide the highest level of protection• Include sophisticated tamper-resistance• Can be circumvented only by highly-skilled hackers with custom tools

For more details on various options, see Digital Rights Management (DRM) Systems on page 9

ACCESS CONTROL

• Publishing rules for restrictions on playback by geographic location, Internet domain, anonymous proxycontrols, and more. Ooyala's publishing rules are detailed in Publishing Rules.

Protected StreamsThere are several technologies that secure the actual stream of data to your customers.

Ooyala encrypted streaming prevents video streams from being ripped and recorded. Publishers canmonetize their video with ads right in the stream. This provides an additional level of protection on top ofplayback authorization.

Technology Description Comments

RTMPE RTMPE (Real Time Messaging Protocol, encrypted) encryptscontent on-the-fly using secure sockets layer (SSL) for deliveryto Flash devices.

Encrypted HTTPLive Streaming(HLS)

To protect content on iOS (Apple's mobile operating system)and HTML5-based devices, Ooyala uses HTTP LiveStreaming (HLS) content protection. Content is transcodedand each segment of each stream is AES-128 encrypted witha randomly generated content encryption key.


Technology Description Comments

Encrypted HTTPDynamic Streaming(HDS)

Adobe’s version of HTTP streaming is a natural evolution forcustomers who are using RTMP/E today but want the cachingbenefits of HTTP.

Not yet supported

To implement these protections, you do not need to do anything. Ooyala provides this protectiondepending on the type of target devices.

LIMITS ON CONCURRENT STREAMSAnother kind of stream-related protection deals with limiting the number of concurrent streams for a viewerto protect against theft and ensure revenue.

Note: If you need to set concurrent stream limits for your Ooyala provider account, contact your OoyalaCustomer Success Manager.

More details on working with concurrent stream limits is in Limiting Concurrent Streams per Viewer onpage 39.

Playback Authorization, Including Token-based Authentication andRestrictions

Playback authorization, which includes token-based authentication, is an additional security layer on top ofprotected streaming. This category is broad and encompasses many different technologies.

TOKEN-BASED AUTHENTICATION

Token-based authentication, required for RTMPE, ensures that encrypted content cannot be downloadeduntil the client has been verified and prevents content from being played in a non-Ooyala player. There areseveral kinds of token-based authentication.

OOYALA PLAYBACK TOKENThe Ooyala Playback Token, which in general is for authenticating users, is foundational in many ofOoyala's content protection features. See details in Ooyala Player Token on page 12, includingintegrating with the iOS and Android SDKs from Ooyala.

CDN TOKEN

The purpose of the so-called "CDN token" is to protect the content on a Content Delivery Network (CDN).

One example is Akamai token-based authentication. See the details in Akamai Secure Token on page22.

WIDEVINE

A composite content protection system, Widevine Modular includes playback authorization and otherfeatures.

If you want to integrate Widevine Modular with Ooyala, contact your Ooyala Customer Success Manager.More details on integrating with Widevine Modular are in Widevine Modular Content Protection on page79.


ADOBE ACCESS

Note: Ooyala integration with Adobe Access DRM has been deprecated and is scheduled to be disabled.For details and alternatives, see the OVP Release Notes.

Adobe Access DRM technology enables a variety of business models that lets you protect premiumcontent across devices. More details on integrating with Adobe Access are in Adobe Access DRM(Deprecated) on page 87.

PLAYREADY

PlayReady is a DRM technology by Microsoft, used to protect premium content from beingviewed without avalid license. It is used in conjunction with Microsoft’s Smooth Streamingprotocol. Ooyala provides a set ofcomprehensive content protection features that work together to provide you with the ability to secure yourcontent. More details on integrating with PlayReady are in PlayReady Content Protection on page 82.

ADOBE PASS

Adobe Pass is categorized as playback authorization, not digital rights management (DRM). More detailson integrating with Adobe Pass are in Integrating Adobe Pass with Ooyala Player on page 23.

Digital Rights Management (DRM) SystemsThese DRM systems are can be integrated with Ooyala:

• Apple's FairPlay Streaming provides content protection for Apple devices. More details: Apple FairPlayon page 76.

• PlayReady from Microsoft, which is designed to protect content on mobile devices, such as iPhone,iPad, Android, and other consumer electronics. For PlayReady, DRM is enforced with Ooyalapublishing rules and PlayReady policies. More details: PlayReady Content Protection on page 82.

• The Widevine Modular multi-platform DRM provides the capability to license, securely distribute, andprotect playback of multimedia content on any customer device. Widevine utilizes user authenticationthrough token-based options such as the Ooyala Player Token. More details: Widevine ModularContent Protection

• Adobe Access DRM (Deprecated) on page 87 DRM technology enables a variety of businessmodels that lets you protect premium content across devices.

DRM POLICIES

• Configurable DRM, which lets your Customer Success Manager or Ooyala Support create multipleDRM policies. Once enabled, you can assign any policy to any asset after ingestion. More details:Configurable DRM on page 88.

Content Protection Options By DeviceTechnology options vary by type of target device, network, streaming protocol, and other factors.

OPTIONS PER DEVICE

The following table can help you decide which DRM system to use with your Ooyala deployment. The tableshows what content protection offerings are supported by device.


Desktop PC/Mac HTML5

AndroidAppMobile/Tablet

iOS AppMobile/Tablet

Chromecast XBOX Roku Apple TV(tvOS)

Stream HTTP LiveStreaming(HLS) andDASH

MPEG-DASH

HTTP LiveStreaming(HLS)

SmoothStreams

SmoothStreams

SmoothStreams

HTTPLiveStreaming(HLS)

DRM WidevineModular andPlayReady(DASH),AppleFairPlay(HLS)

WidevineModular

AppleFairPlay

MicrosoftPlayReady

MicrosoftPlayReady

MicrosoftPlayReady

AppleFairPlay

DRMPlayer

OoyalaHTML5Player

OoyalaAndroidSDK

Ooyala iOSSDK

OoyalaHTML5Player

Custom(non-Ooyala)

Custom(non-Ooyala)

OoyalaiOS SDK

EncryptedStream

encryptedHLS /AES-128




N/A N/A encryptedHLS /AES-128

EncryptedStreamPlayer

OoyalaHTML5Player

OoyalaAndroidSDK andHTML5Player

OoyalaAndroidSDK andHTML5Player

OoyalaHTML5Player

N/A N/A OoyalaiOS SDK

SUPPORTED BROWSERS USING MULTI-DRM ON OOYALA PLAYER V4

Browser Supports

Google Chrome version 51 or later onWindows 8 or later and Mac OS X 10.11 orlater

Widevine DASH

Microsoft Edge on Windows 10 PlayReady DASH

Mozilla Firefox version 48 or later on Mac OSX 10.11 or later

Note: Supported on stable, official releasebuilds from Mozilla. Non-Mozilla builds are notsupported.

Widevine DASH

Safari 9.x on Mac OS X 10.10 or later FairPlay HLS


WARNING ABOUT WEB BROWSER THIRD-PARTY COOKIESBy default, some browsers, such as Apple Safari, disallow third-party cookies, which can interfere with yourOPT or authorization requests.

UNBLOCK ALL COOKIES IN BROWSER SETTINGS

The Ooyala Player Token and the Player Authorization API rely on setting cookies in a viewer's browser onbehalf of the provider (you). Such cookies are called "third-party cookies".

In your viewers' web browser settings, be sure to unblock all restrictions against cookies.

In Apple Safari, for example, in the Safari > Preferences dialog, set Block cookies to Never:

CONTENT PROTECTION DEVELOPER GUIDE | AUTHENTICATION | 12

AUTHENTICATION

Identifying each unique viewer is a critical part of managing rights and authorizing playback. The OoyalaPlayer Token makes integration easy with a publisher’s subscriber management system. For broadcastersin the US, Adobe Pass can also provide specific authentication for TV Everywhere viewing. To authenticateusers for Ooyala APIs such as Watchlist and eCommerce, Ooyala Account Token programmaticallycreates an Ooyala Account Token.

OOYALA PLAYER TOKENOoyala provides the ability to secure content with the Ooyala Player Token.

Ooyala provides content publishers and providers with the ability to secure digital content with the OoyalaPlayer Token, which is one of Ooyala's content protection solutions.

You can use the Ooyala Player Token to protect you from users who may try to make unauthorized useof your digital content. For example, a user may take the embedded player Javascript (.js) script taggenerated in Backlot and distribute it without permission to others for replay, or attempt other similar replayattacks.

To prevent such unauthorized usage, Ooyala has introduced the Ooyala Player Token feature, which helpsyou protect your content from these types of risks. You can use this feature to secure your monetizedcontent and prevent unauthorized distribution.

The Ooyala Player Token feature provides you with a secure process that authenticates the player beforeit allowing it to replay your digital content. Token-based authentication ensures that your digital contentcannot be downloaded or played until the client player has been authenticated. Once the client player isauthenticated, the containing browser receives a cookie authorizing the client player to play the requestedcontent.

USING THE OOYALA PLAYER TOKEN

The following steps describe how to use the Ooyala Player Token in a basic web application:

• Step 1: Set up the Ooyala Player Token in Backlot on page 12• Step 2: Create a Basic HTML Page on page 13• Step 3: Specify the embedToken Embedded Parameter on page 14• Step 4: Construct and Assign the Token Request Value on page 14• Complete Web Example: Authorize Playback and Obtain a Token on page 16

Note: A cookie authorizing playback will be returned to the end user's browser. For this reason, be sureto advise end users to enable cookies in their browsers. See Warning About Web Browser Third-partyCookies on page 11for more information.

For more information on how to build web applications with the Ooyala Player JavaScript API, seeDeveloping with the Player V3 JavaScript API (Deprecated).s

STEP 1: SET UP THE OOYALA PLAYER TOKEN IN BACKLOT

The Backlot UI provides you with an option to secure your content by setting a Syndication group flagadding your content assets to this syndication group. This will enable you to set up your web page to runyour player(s), and send the authorization token in the form of a cookie to the browser. Follow these stepsto secure your content in Backlot:

SECURING PLAYBACK CONTENT WITH THE OOYALA PLAYER TOKEN

1. Log in to your Backlot account.2. Click the PUBLISH tab, and select the Syndication Controls tab.3. Select a video from a syndication group, or set up a syndication group and then select your video.4. In the Syndication Controls pane, click the Require Ooyala Player Token checkbox.5. Set the expiration time for the viewing session by specifying a time in seconds in the Expiration: field.

If you do not specify a time, the recommended default of ten minutes is used. The field only acceptsnumeric entries (e.g. 600). You may set a longer expiration time for the cookie if you prefer, since theSame Origin Policy protects its distribution. For more information about the expiration time, see OoyalaPlayer Token Expiration on page 18.

6. Click the MANAGE tab, and select the Embed tab.7. Click the Copy button to conveniently retrieve the player JavaScript <script> tag to paste into your

web page. Note that this content must be in the syndication group in which you specified the OoyalaPlayer Token as a required option.

STEP 2: CREATE A BASIC HTML PAGE

Create a basic HTML page that includes a call to OO.Player.create(). For a complete tutorial, seeBasic Tutorial for the HTML5 Player V3 (Deprecated).

<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>My Test Player V3 Web Page</title>  <script src="http://player.ooyala.com/v3/f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"> </script>  </head> <body> My Player V3 Content:<br/><br/>  <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> OO.ready(function() { OO.Player.create( 'ooyalaplayer', "A5eXRtcjpb6AEKizxldiaThNBmL9GWGU", { } ); }); </script> </body></html>

Note: While this basic example illustrates the token request value on a web page, it is recommendedthat you do not actually store such information on static web pages since token requests contain sensitiveinformation.

STEP 3: SPECIFY THE EMBEDTOKEN EMBEDDED PARAMETER

In the call to OO.Player.create(), specify embedToken as an embedded parameter:

OO.Player.create( 'ooyalaplayer', "A5eXRtcjpb6AEKizxldiaThNBmL9GWGU", { embedToken : 'token value to be added here' } );

You can see this in the code shown below :

<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>My Test Player V3 Web Page</title>  <script src="http://player.ooyala.com/v3/f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"> </script>  </head> <body> My Player V3 Content:<br/><br/>  <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> OO.ready(function() { OO.Player.create( 'ooyalaplayer', "A5eXRtcjpb6AEKizxldiaThNBmL9GWGU", { embedToken : 'token value to be added here' } ); }); </script> </body></html>

STEP 4: CONSTRUCT AND ASSIGN THE TOKEN REQUEST VALUE

Now you are ready to construct the token request value and assign it to the embedToken embeddedparameter. The value is specified in the form of a URL that has the segments shown in the table below:

URL Segment Description

Protocol anddomain

http://player.ooyala.com

Request path /sas/embed_token/{pcode}/{comma-separated embed codes}

Query stringparameters

?account_id={optional account ID}&api_key={apikey} &expires={expiration time} &return_json=1


URL Segment Description&signature={computed signature}

You will learn how to specify all the required values shown in the table.

In this example, the following values are used (see below for detailed instructions on how to constructthese values):

• pcode: F0Y2E6qDLc1XS9yvdR48ulAQ2t1• embed code: A5eXRtcjpb6AEKizxldiaThNBmL9GWGU• apikey: F0Y2E6qDLc1XS9yvdR48ulAQ2t1.yRIJm• expiration time: 1483688253• computed signature: sp4Cew3qqX1iBrlKSfjlryuPlbHIaLMzLh7/f39IBM4

Note: The return_json query parameter is optional. Set this parameter to 1 if you would like theauthentication token to be returned in the JSON response.

Here is the call to OO.Player.create() that includes the token request value:

OO.Player.create('ooyalaplayer', "A5eXRtcjpb6AEKizxldiaThNBmL9GWGU", { embedToken : 'http://player.ooyala.com/sas/embed_token/F0Y2E6qDLc1XS9yvdR48ulAQ2t1/A5eXRtcjpb6AEKizxldiaThNBmL9GWGU?api_key=F0Y2E6qDLc1XS9yvdR48ulAQ2t1.yRIJm&expires=1483688253&signature=sp4Cew3qqX1iBrlKSfjlryuPlbHIaLMzLh7/f39IBM4'});

See Complete Web Example: Authorize Playback and Obtain a Token on page 16.

You will need the values described above. To retrieve these, follow the directions shown in this table:

Value Description

apikey If API access is enabled for your account, Ooyalaprovides you with an API Key. This is a requiredfield. For more information about the API Key, seeGeneral Algorithm for Signing Requests.

pcode You can get this partner code (pcode) informationfor a particular provider from your Ooyala BacklotWeb Account. Select the Account tab and clickDevelopers. The API Key contains two sets ofcharacters separated by a period (.). The set ofcharacters to the left of the period is the pcode.This is a required field.

comma-separated embed codes You supply one or more embed codes thatrepresent the players that will be embedded on thepage. You can use up to 50 embed codes. You mayspecify a value of all if you would like to create theplayback token for use with multiple assets (over50 embed codes). This is useful when using therights locker with applications that want to createthe playback token for multiple assets.

expirationTime The POSIX time at which point the token expires.Use a short expiration time on the URL snippet sothat the snippet cannot be replicated across otherdomains (more precisely, it can be embedded, butwill become nonfunctional).

Value Description

account_id (Optional) Your account or user identifier. Whilenot always necessary in the Ooyala PlayerToken, the account_id is required for working withentitlements (such as eCommerce), concurrentstream limits, cross-device resume, or deviceregistration. Use this parameter in conjunctionwith Rights Locker on page 52 and DeviceRegistration API on page 60.

computedSignature (This must be the lastparameter.)

Generate this signature on the server by followingthe instructions provided in General Algorithm forSigning Requests.

COMPLETE WEB EXAMPLE: AUTHORIZE PLAYBACK AND OBTAIN A TOKEN

In the following example, when the embedded player is loaded, the event triggers the communication ofthe token request URL to the player. The player then requests authorization and a token from the Ooyalaauthorization server, using the token request. Depending on whether the request made justifies playback,either a valid cookie and authorized response is returned, or an invalid cookie and an unauthorizedresponse is returned.

<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>My Test Player V3 Web Page</title>  <script src="http://player.ooyala.com/v3/f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"> </script>  </head> <body> My Player V3 Content:<br/><br/>  <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> OO.ready(function() { OO.Player.create('ooyalaplayer', "A5eXRtcjpb6AEKizxldiaThNBmL9GWGU", { embedToken : 'http://player.ooyala.com/sas/embed_token/F0Y2E6qDLc1XS9yvdR48ulAQ2t1/A5eXRtcjpb6AEKizxldiaThNBmL9GWGU?api_key=F0Y2E6qDLc1XS9yvdR48ulAQ2t1.yRIJm&expires=1483688253&signature=sp4Cew3qqX1iBrlKSfjlryuPlbHIaLMzLh7/f39IBM4' }); }); </script> </body></html>


Warning About Web Browser Third-party CookiesBy default, some browsers, such as Apple Safari, disallow third-party cookies, which can interfere with yourOPT or authorization requests.

UNBLOCK ALL COOKIES IN BROWSER SETTINGS

The Ooyala Player Token and the Player Authorization API rely on setting cookies in a viewer's browser onbehalf of the provider (you). Such cookies are called "third-party cookies".

In your viewers' web browser settings, be sure to unblock all restrictions against cookies.

In Apple Safari, for example, in the Safari > Preferences dialog, set Block cookies to Never:

Controlling Playback with the Ooyala Player TokenYou can authorize playback using the Ooyala Player Token.

Limiting playback exclusively to authorized users and exclusively on your page requires the communicationof the token request URL to the player, so that the player can utilize this URL throughout authorization.This is accomplished with the following steps:

• Generate a Token Request and Authorization URL. You generate the signed token request URLon the server-side, specifying a short expiration time as one of the query-string parameters. You mustalso include your provider code and a comma separated list of embed codes. This URL is passed toour player via a JavaScript callback; its short expiration time prevents it from being lifted from your pageand used elsewhere.

• Set the Token Expiration Time. You need to set an expiration time for the Playback Token in yourBacklot Syndication tab. Note that this expiration time is independent of the token request expirationtime. Its function is to specify how long the token (client-side cookie, issued by Ooyala) will be valid, andit controls the viewer’s access to authorized players for the specified interval. space.

• Embed the URL to Issue Authorization. When the crafted token request URL is forwarded to theplayer, Ooyala’s authorization response will do the following:

1. Set a unique cookie on the user’s browser containing the token object.2. Send an authorization/no-authorization decision.

Once the client receives an affirmative authorization response (and simultaneously receives the cookieobject), video playback is enabled.


• Playback Authorization. Before the video starts playing, the Ooyala player sends the authenticationrequest and receives the token. When the authorization server validates the URL, it authorizes playingthe content. The authorization is in effect until the session expires. If the session expires, the viewerneeds to refresh the browser.

Note: If the URL is not valid, it will display an error message. For more information about the error, see the"Error Types" topic in this document.

TWO TYPES OF EXPIRATION TIMES

With this design, you should note the difference between the two expiration times. You need to set:

• One expiration time on the token request (the URL that will be embedded on the page—adjustableby the provider’s server-side implementation). Use a short expiration time on the URL snippet sothat the snippet cannot be replicated across other domains (it can be embedded, but will becomenonfunctional).

• The other expiration time on the token object itself (a secure cookie, with its expiry time adjustablethrough your Backlot account). A longer expiration time may be set (if desirable) on the cookie object,since the Same Origin Policy protects its distribution.

COMBINING THE OOYALA TOKEN WITH OTHER CONTENT AUTHORIZATION TYPES

The Ooyala Player Token works either singly or in conjunction with other types Digital Rights Management(DRM) solutions that Ooyala provides (or supports) to ensure that users can have access to authorizedcontent. You can also use the Ooyala Player Token in conjunction with:

• Ooyala's Rights Locker entitlement enforcement system• Ooyala's device registration system• A CDN token to prevent unauthorized sharing of a direct link to an Real Time Messaging Protocol

(RTMP) stream.• Encrypted delivery (such as RTMPE or HLS AES Encryption) to prevent recording of a stream.• DRM Technologies (such as Flash Access) to enforce usage rights on content.

Ooyala Player Token ExpirationThe token is a session cookie, so it expires when the browser is closed.

The Ooyala Player Token (cookie) is valid for the ooyala domain: player.ooyala.com. The token is asession cookie, so it expires when the browser is closed. When using the Ooyala Player Token, you needto be aware of the various types of session expiration:

• URL Token Request Expiration - Shorter in duration than the expiration time you set in Backlot, thisexpiration is selected by the provider on the server-side and included in the token request URL directly.

• Set Token Expiration - This expiration time is set by the content provider in Backlot. Information aboutsetting this type of expiration is described in the topic, Setting the Ooyala Player Token on page 19,in this document.

• Interaction Token Expiration - This type of token expiration originates from user actions that close theplayer.

To clear the Ooyala Player Token cookie set in player.ooyala.com, call the player.ooyala.com/sas/revoke_embed_token/:pcode API where :pcode is substituted with your provider pcode.

Note: When the Ooyala Player Token has been created using the "all" embed code parameter, there is nosyndication group associated with it, so you cannot configure the expiration time in a Backlot syndicationgroup. Instead you must create a provider attribute called "wildcard_opt_expiration_time" and give it avalue in seconds. If you do not create this attribute, then a default expiration time of 10 minutes will beused for the token.

http://www.w3.org/Security/wiki/Same_Origin_Policy

http://player.ooyala.com/


TOKEN REQUEST URL EXPIRATION TIME

The token request URL has an expiration that is separate from the token’s expiration time that you setin Backlot (or via the API). Per the discussion at the bottom in the prior topic, “How Does It Work” werecommend that you use short expiration time. You set the Token Request URL expiration time within theURL itself. The format is similar to the following example:

expires={expiredTimeInPOSIXTime}

Note: For more information about constructing the Token Request URL, see the topic ControllingPlayback with the Ooyala Player Token on page 17 in this document.

SETTING TOKEN EXPIRATION TIME IN BACKLOT

When Ooyala authorizes playback and responds to the token request with a token object (the cookie),the user is authorized to play the video or audio content until token expiration time occurs. Followingexpiration, the user no longer has playback authorization and must reload the page to playback thecontent. If a user was authorized initially, and mid-playback the cookie expires, playback does not cease.Once authorized for playback, this mechanism does not revoke access unless a user reloads the page (ornavigates away and returns). For more information about setting the expiration time in Backlot, see step 5in the following topic, Setting the Ooyala Player Token on page 19 later in this document.

INTERACTION TOKEN EXPIRATION TIME

The token remains on the browser even if the user navigates away from the page or stops playback,though it can certainly expire in the meanwhile. Users can trigger token flushing only by closing thebrowser or deleting all cookies. To get another token object, the user would then have to reload the page,re-triggering the pathway discussed in Controlling Playback with the Ooyala Player Token on page 17earlier in this document.

Setting the Ooyala Player TokenThe Backlot UI provides you with an option to secure your content by setting a Syndication group flagadding your content assets to this syndication group. This will enable you to set up your web page to runyour player(s), and send the authorization token in the form of a cookie to the browser. Follow these stepsto secure your content in Backlot:

SECURING PLAYBACK CONTENT WITH THE OOYALA PLAYER TOKEN

1. Log in to your Backlot account.2. Click the PUBLISH tab, and select the Syndication Controls tab.3. Select a video from a syndication group, or set up a syndication group and then select your video.4. In the Syndication Controls pane, click the Require Ooyala Player Token checkbox.5. Set the expiration time for the viewing session by specifying a time in seconds in the Expiration: field.

If you do not specify a time, the recommended default of ten minutes is used. The field only acceptsnumeric entries (e.g. 600). You may set a longer expiration time for the cookie if you prefer, since theSame Origin Policy protects its distribution. For more information about the expiration time, see OoyalaPlayer Token Expiration on page 18.

6. Click the MANAGE tab, and select the Embed tab.7. Click the Copy button to conveniently retrieve the player JavaScript <script> tag to paste into your

web page. Note that this content must be in the syndication group in which you specified the OoyalaPlayer Token as a required option.


Using Ooyala Player Token with Ooyala iOS and Android SDKsYou can use the Ooyala Player Token for user authorization with Ooyala iOS and Android SDKs.

Using the Ooyala Player Token with an implementation of our iOS or Android SDKs works essentially thesame as standard implementations with some small differences:

1. Create a class that implements an EmbedTokenGenerator. See the following topics for instructionson implementing an OOEmbedTokenGenerator for iOS and Android.

2. Pass a reference from your created class to the player constructor.3. Add the following getTokenForEmbedCodes method:

public void getTokenForEmbedCodes(List<String> embedCodes, EmbedTokenGeneratorCallback callback)

4. Inside the getTokenForEmbedCode method, call the callback .setEmbedToken(token), wheretoken is a valid Ooyala player token for the list of embed codes.

Implementing an iOS OOEmbedTokenGeneratorTo use the Ooyala Player Token for user authorization your iOS app must implementOOEmbedTokenGenerator.

Click here to view the example used in this tutorial, and use the following steps to implement theOOEmbedTokenGenerator in your project.

1. Open the project ViewController.h file and add the following import statement:

#import "OOEmbedTokenGenerator.h"

2. Implement OOEmbedTokenGenerator in the UIViewController. The syntax is shown in thefollowing example:

@interface ViewController : UIViewController <OOEmbedTokenGenerator>

3. Open the project ViewController.m file and create or edit the ooyalaPlayerViewControllerto call the method overload that takes embedTokenGenerator. The syntax is shown in the followingexample:

/ Create the Ooyala ViewController, with self as the embed token generatorOOOoyalaPlayer *player = [ [OOOoyalaPlayer alloc] initWithPcode:self.pcode domain:[[OOPlayerDomain alloc]initWithString:self.playerDomain] embedTokenGenerator:self];

self.ooyalaPlayerViewController = [[OOOoyalaPlayerViewController alloc] initWithPlayer:player];

4. A server-side generated token can only be created by the customer so content is authorized forplayback on authorized sites. The client receives it and submits it to embedTokenGenerator().These tokens should not be created on the client. The API secret should only be on the server andshould not be publicly visible. This example is only useful for debugging but should not be used inproduction. Implement tokenForEmbedCodes in the ViewController.m file. The syntax is shownin the following example:

/* * Get the Ooyala Player Token to play the embed code. * This should contact your servers to generate the OPT server-side. * For debugging, you can use Ooyala's EmbeddedSecureURLGenerator to create local embed tokens

https://github.com/ooyala/ios-sample-apps/blob/stable/ContentProtectionSampleApp/ContentProtectionSampleApp/Players/OoyalaPlayerTokenPlayerViewController.m


*/- (void)tokenForEmbedCodes:(NSArray *)embedCodes callback:(OOEmbedTokenCallback)callback { NSMutableDictionary* params = [NSMutableDictionary dictionary];

params[@"account_id"] = self.accountId; NSString* uri = [NSString stringWithFormat:@"/sas/embed_token/%@/%@", self.pcode, [embedCodes componentsJoinedByString:@","]];

OOEmbeddedSecureURLGenerator* urlGen = [[OOEmbeddedSecureURLGenerator alloc] initWithAPIKey:self.apiKey secret:self.secret]; NSURL* embedTokenUrl = [urlGen secureURL:self.authorizeHost uri:uri params:params]; callback([embedTokenUrl absoluteString]); }}

The iOS Mobile SDK Sample Apps folder includes a complete working sample app withOOEmbedTokenGenerator implemented. From the SDK archive, navigate to:

OoyalaSDK-iOS/SampleApps/DeviceManagementSampleApp

Implementing EmbedTokenGenerator for AndroidTo use the Ooyala Player Token for user authorization implement OOEmbedTokenGenerator in theAndroid app main activity.

Use the following steps to implement an EmbedTokenGenerator in the Android project main activity.

1. Open the Android app main activity and add the following import statements:

import com.ooyala.android.EmbedTokenGenerator;import com.ooyala.android.EmbedTokenGeneratorCallback;

2. Extend the main activity class with the EmbedTokenGenerator interface. The syntax is shown in thefollowing example:

public class MainActivity extends Activity implements EmbedTokenGenerator, Observer{...

3. Create an OoyalaPlayerLayoutController instance with the constructor that takes anembedTokenGenerator parameter. Use the player.setEmbedCode and player.play functions.This is shown in the following example:

...public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); OoyalaPlayerLayout playerLayout = (OoyalaPlayerLayout) findViewById(R.id.ooyalaPlayer); OoyalaPlayerLayoutController playerLayoutController = new OoyalaPlayerLayoutController(playerLayout, PCODE, new PlayerDomain(DOMAIN), this); player = playerLayoutController.getPlayer(); player.addObserver(this); if (player.setEmbedCode(EMBED)) { player.play(); } else { Log.d(this.getClass().getName(), "Something Went Wrong!"); } }


4. A server-side generated token can only be created by the customer so content isauthorized for playback on authorized sites. The client receives it and submits it toEmbedTokenGeneratorCallback(). These tokens should not be created on the client. The APIsecret should only be on the server and should not be publicly visible. This example is only useful fordebugging but should not be used in production. Implement the getTokenForEmbedCodes methodwith an EmbedTokenGeneratorCallback interface. Add the .setEmbedToken callback, wheretoken is a valid Ooyala player token for the list of embed codes. This is shown in the following example:

@Override public void getTokenForEmbedCodes(List<String> embedCodes, EmbedTokenGeneratorCallback callback) { //add embed token/OPT in the setEmbedToken() example below // HTTP_SAS + "/embed_token/pcode/embed_code?account_id=account&api_key=apikey&expires=expires&signature=signature" callback.setEmbedToken("fill me in"); }

The Android Mobile SDK Sample Apps folder includes a complete working sample app withEmbedTokenGenerator implemented. From the SDK archive, navigate to:

OoyalaSDK-Android/SampleApps/DeviceManagementSampleApp

AKAMAI SECURE TOKENYou do not need to write any programs to make use of this authentication.

The Akamai secure token is a basic protection solution for video and audio content hosted by Akamai.Contact your Customer Support Manager to set up an Akamai token. The Akamai token provides abasic level of protection and allows content (video and audio) to be played from an authorized account.The policy information in the token determines what account checks are performed. The authorizationmechanism grants or denies playback of video or audio content based on any one of the following factors:

• Presence or absence of a valid token• Viewer’s IP address• Source URL of the video• Token expiration time

Note: Ooyala supports Akamai Secure Tokens only for Live (remote assets) streams and does notsupport VOD with our default Content Delivery Service.

Ooyala generates a short-lived token that is then sent to Akamai to unlock an asset for streaming. Thisprocess is conducted entirely by Ooyala; no programming is required.

The following steps describe the how Akamai secure token authorization works:


1. The Akamai token authentication process is started when a viewer goes to a website and clicks aplayback button for an asset in an Ooyala player.

2. The player sends a token request to the Ooyala server.3. The Ooyala server determines if the provider has an Akamai account set up through Ooyala.4. If the account is set up and enabled, the Akamai authorization token is appended to the stream

connection and returned to the player. The viewer is now able to playback the video or audio file.5. If the Akamai token is not returned, then the user receives an error message indicating that lack of

authorization for playback.

TOKEN EXPIRATION TIME

The generated token is valid for 90 seconds (30 seconds + an assumed 60 second clock skew). Thisduration is based on standard Akamai recommendations.

SYSTEM REQUIREMENTS

Ooyala Player supports the Akamai token, with the same supported browsers as those supported by theOoyala player, including Flash-based players (Akamai token authorization works with ActionScript forFlash).

INTEGRATING ADOBE PASS WITH OOYALA PLAYERAdobe Pass can be integrated with all of Ooyala’s players and supported browsers.

Adobe Pass is an authentication and authorization (AuthN/AuthZ) service that Ooyala uses to allow loggingin and rights management for TV Providers and other Video Multichannel Video Programming Distributors(MVPDs). Adobe Pass allows Ooyala’s customers to restrict their content to paying customers of MVPDs.

GENERAL USAGE FLOW

Here is the general usage flow:

1. When a player with the Adobe Pass module is created on a page, it passes a “requestorId” to AdobeServer.

2. Adobe Server acknowledges that the “requestorId” is registered and returns the list of MVPDsassociated with that “requestorId”.

3. An end user logs in through Adobe Pass, attempting to authenticate themselves as a valid user of anMVPD by providing their end user credential and a “staticResourceId”.

4. If Adobe Pass authenticates the end user, Adobe Pass returns a “media token”.5. A request for the desired video, along with the media token, is sent as an authorization request to

access (SAS) to the Media Token Verifier (an Adobe component) running on an Ooyala server.6. If the Adobe Media Token Verifier determines that the media token retrieved earlier from the Adobe

Pass server is valid, then the verified consumer can play the video. At this point, the end user isauthorized.

TERMINOLOGY

Here are definitions to terms used in this document.

Term Definition

authentication TV Provider login authenticates the end user.


Term Definition

authorization Adobe Pass and Backlot authorize the end user toplayback the video content.

requestorId Adobe Pass identifier. Obtained when the customerregistered with Adobe. Associated with a list ofMVPDs on Adobe Pass.

resourceId Ooyala Backlot identifier. Associated with the user’sauthorization rights on Adobe Pass (as configuredin Backlot: pass:resourceId).

staticResourceId Player parameter. Maps to resourceId (video’s labelin Backlot).

STEPS TO INTEGRATE VIA ADOBE PASS

Prior to configuring with Adobe Pass, you must have:

• a business account with Adobe Pass• a “requestorId” with the list of MVPDs registered with Adobe Pass

To integrate with Adobe Pass and Ooyala, complete the following steps:

1. Add Adobe Pass to a player. Ask Ooyala Technical Support to add the "adobe-pass" module to thedesired player via support-tools > Add third-party-module > "adobe pass".

2. Set up an MVPD picker that allows the end user to login with Cable credentials.3. Ask Ooyala Technical Support to add "requestorId" with the Adobe Pass identifier (which was assigned

when you registered with Adobe) to the player configured for Adobe Pass in the previous step.4. In Backlot, create a label with name = “pass:resourceId” and add it to your videos.5. In Backlot, enable “Ooyala Player Token” to the player using the Publish tab. Create a syndication set,

and click (check) the “Require Ooyala Player Token” checkbox.6. Load a sample Adobe Pass HTML page. A player that has the Adobe Pass module instantiates the

OO.Pass object. The page also must have the staticResourceId equal to the resourceId that yourorganization configured on the video’s label in Backlot.

7. To handle success/failure for authentication and errors, call OO.Pass.login().8. To detect a success or error upon login, listen to OO.EVENTS.ADOBE_PASS_AUTH_STATUS or

"setAuthenticationStatus" via the message bus.9. To log out, call OO.Pass.logout().

For reference material on integrating with Adobe Pass, see Adobe Pass Integration Reference on page25.

Note: Adobe Pass is no longer supported in the Ooyala iOS and Android Mobile SDKs.


ADOBE PASS INTEGRATION REFERENCEPlayer parameters, the APIs, and events associated with Adobe Pass integration.

PLAYER PARAMETERS

Parameter Description

staticResourceId Player parameter that is passed to Adobe PassServer. Match with the resourceId on the Backlotlabel.

showLoginAtStart Whether to show the login at startup.

TRUE - If the end user is not yet authenticated,automatically show MVPD to login.

FALSE (default) - Do not show MPVD to login.

API REFERENCEOO.Pass API

API Call Description

OO.Pass.login() Check authentication and login. You can listen toOO.EVENTS.ADOBE_PASS_AUTH_STATUS ifyou're already logged in. Otherwise it will showlogin dialog.

OO.Pass.logout() Attempt to logout the current user.

OO.Pass.checkAuthentication() Will do a full check if authenticated. You can listento OO.EVENTS.ADOBE_PASS_AUTH_STATUSwith the current auth status.

OO.Pass.isAuthenticated() Returns true if authenticated.

OO.Pass.selectProvider(event) See useProviderDialog(). You can use this functionto parse out the provider and to tell Adobe Passyour MVPD choice.

OO.Pass.getSelectedProvider() Returns the provider that you are currently loggedinto.

OO.Pass.useProviderDialog(dialog) Use custom MVPD dialog callback function. Seethe Sample Web Page.

OO.Pass.checkAuthorization(resourceId) If the end user is authenticated, check whether theyhave authorization with the given resourceId.

Success: PublishesOO.EVENTS.ADOBE_PASS_TOKEN_FETCHEDand setToken (specific within Adobe Pass).

Failure : PublishesOO.ERROR.ADOBE_PASS_TOKEN andtokenRequestFailed (specific within Adobe Pass).



OO.Pass.getAuthorization(resourceId) Attempt to get authorization for the providedresourceId. If the end user is not authenticated, itwill attempt to login first.

Success: PublishesOO.EVENTS.ADOBE_PASS_TOKEN_FETCHEDand setToken (specific within Adobe Pass).

Failure: PublishesOO.ERROR.ADOBE_PASS_TOKEN andtokenRequestFailed (specific within Adobe Pass).

OO.Pass.isEntitlementLoaded() Returns true if the Access Enabler is loaded andinitialized.

OO.PASS CALLBACK API


OO.Pass.onSetToken(func) Takes a function in the form of function func(event,resId, token) to callback when Adobe Passdispatches a setToken event.

OO.Pass.onTokenRequestFailed(func) Takes a function in the form of function func(event,stat, errorCode) to callback when Adobe Passdispatches a tokenRequestFailed event.

OO.Pass.onSetAuthenticationStatus(func) Takes a function in the form of function func (event,stat, errorCode) to callback when Adobe Passdispatches the setAuthenticationStatus event.

OO.Pass.onEntitlementLoaded(func) Takes a function in the form of function func(event,stat, errorCode) to callback when Adobe Passdispatches the entitlementLoaded event.

EVENT REFERENCE

Event Description

OO.EVENTS.ADOBE_PASS_AUTH_STATUS When someone checks for authentication.

OO.EVENTS.ADOBE_PASS_TOKEN_FETCHED When a successful token is fetched forauthorization.

OO.EVENTS.ERROR When an error is produced. Adobe Pass hasadditional parameters passed to listeners for someAdobe Pass errors.

Note: More detailed errors from MVPD will be inparams.passDetails.

Most Common Adobe Pass Events

The following list includes the most common Adobe Pass events.

• setToken• tokenRequestFailed• setAuthenticationStatus• entitlementLoaded


Consult your Adobe Pass documentation for more information about these events.

EXAMPLE IMPLEMENTATIONSSample Web Page Integration

<html> <head> <script src="http://player.ooyala.com/v3/[your_player_branding_id]"> </script> <script> OO.ready(function() { window.pp = OO.Player.create("video-container", "[your_embed_code]", { width: '400px', height: '300px', staticResourceId: '[your_resource_id]', }); }); </script> </head> <body> <div class="video-container" id="video-container"></div>

<a href="#" onclick="javascript:OO.Pass.login();return false;">Log In</a>

<a href="#" onclick="javascript:OO.Pass.logout();return false;">Log Out</a><br /> </body></html> </codeblock> <b>Sample Web Page Integration</b> <p>In the following example:</p> <ul> <li>In order to authenticate, the code must contain mvpd_id.</li> <li>The name ooyalaMvpdPickerContainer is fixed and cannot be changed.</li> </ul> <codeblock ><html> <head> <script src='http://code.jquery.com/jquery-1.8.2.min.js'></script> <script src="http://player.ooyala.com/v3/[your_player_branding_id]"> </script> <script> // Custom Display Provider Dialog function customDisplayProviderDialog(event, providers) { var selectTitle = "This is my custom display for providers"; $('#ooyalaMvpdPickerContainer').remove();

// build provider list. var loginContainerDiv = $('<div id="ooyalaMvpdPickerContainer"/>'); $('body').append(loginContainerDiv); var cancelButton = $("<div class='cancelDiv'/>"); cancelButton.html(' '); var titleBar = $("<div class='titleBar'/>"); titleBar.html(selectTitle); var providerList = $("<div class='providerList'/>"); var bottomList = $("<div class='bottomList'/>"); var innerDiv = $("<div class='innerDiv'/>"); loginContainerDiv.append(innerDiv);


innerDiv.append(cancelButton); innerDiv.append(titleBar); innerDiv.append(providerList); innerDiv.append(bottomList); var list = $("<ul>");

providerList.append(list); //Note the use of list elements and their attribute of mvpd_id. $.each(providers, function(index, item){ var li = $("<li>"); li.attr("mvpd_id", item.ID); li.append("<img src='" + item.logoURL + "' onclick='function(){return false;}'> " + item.displayName); list.append(li); });

$("#ooyalaMvpdPickerContainer li").click(OO.Pass.selectProvider); cancelButton.click(function() { $('#ooyalaMvpdPickerContainer').remove(); }); }// end custom Display Provider Dialog </script> </head> <body> <div class="video-container" id="video-container"></div>

<a href="#" onclick="javascript:OO.Pass.login();return false;">Log In</a>

<a href="#" onclick="javascript:OO.Pass.logout();return false;">Log Out</a><br /> </body></html>

OOYALA ACCOUNT TOKEN APIAccess to certain Ooyala services, such as eCommerce and Watchlist, is controlled using an OoyalaAccount Token. The Ooyala Account Token API generates an account token to authenticate a user.When calling these APIs, the client is required to provide the account token for authentication. After yourapplication has logged in a user, it calls the Ooyala Account Token API route to get the account token. Theaccount token is valid for a specific amount of time, 15 minutes by default.

API ROUTE

The following route retrieves the account token:

POST https://player.ooyala.com/authentication/v1/providers/pcode/gigya?uid=user_id&signatureTimestamp=timestamp&UIDSignature=signature

PARAMETERS

The following variables must be substituted with their actual values.

Note: If you use Gigya for identity management, the values for user_id, timestamp and signaturecan be obtained using Gigya's API. Contact your Ooyala Customer Support Manager for information onintegration with Gigya.


Parameter Description

pcode The provider code for your Ooyala account.

user_id The unique identifier you use to identify your end user.

timestamp The UNIX timestamp (seconds since epoch) in UTC time at whichthe request expires. The request is rejected if this timestamp is in thepast or more than 3 minutes into the future.

signature The URI escaped, base64 encoded signature computed using thealgorithm described below.

The JSON response returns the account token and its expiration time:

{ “account_token” : “an opaque string”, “expires” : “time at which the token expires”}

Example:

POST https://player.ooyala.com/authentication/v1/providers/mypcode/gigya?uid=1234abcde&signatureTimestamp=1457727984&UIDSignature=d%2FN%FP0wMSel7ptE%3D

Response:

{ “account_token” : “Xvrw4qxPYCidlM”, “expires” : “2014-03-02T23:20:19+00:00”}

If the request fails, a non-200 status code is returned. The body of the response contains only the errormessage, which will be the specific reason why the request failed such as Invalid signature.

BEFORE GENERATING A SECRET KEY AND SIGNATURE

If you are using Gigya for identity management, please contact your Ooyala Customer Support Manager toguide you on how to get the secret key and signature.

Note: If you are NOT using Gigya, follow the following procedures for generating a secret key and asignature.

GENERATE A SECRET KEY

Constructing the signature requires a secret key. This secret key should be the base64-encoded version ofa 32-byte value.

Example secret key: Khs41aqNVOcfZRLViNajqvIDDirO2fn3VhhWGKgBT8g=. This exact value shouldnever be used in an your implementation since this is publicly documented here. You are required togenerate your own.

To create a secret key for use in the signature, use the following command on a UNIX or Mac machine:

openssl rand -base64 32


Before you share a secret key with Ooyala, you must setup email encryption and send your public keycertificate to Ooyala. You can then send the secret key for the signature to Ooyala via a PGP-encryptedemail. See https://ssd.eff.org/en/module/how-use-pgp-mac-os-x.

GENERATE A SIGNATURE

To create the base64 signature, work on the server side so your secret key can be used safely.

1. Create a base string of timestamp_uid. Replace timestamp and uid (user_id) with theircorresponding values.

2. Convert this string into a binary array using UTF-8 encoding.3. Convert the base64 secret key into a binary array.4. Using your converted base string and converted secret key, calculate the cryptographic signature with

the HMAC-SHA1 algorithm. The response is a binary array containing the signature.5. Convert the signature array into a base64 string.

Example Ruby code:

def generate_signature(uid, secret, timestamp) base_string = "#{timestamp}_#{uid}" key = secret.unpack("m0").first signature = OpenSSL::HMAC.digest("sha1", key, base_string) [signature].pack("m0")end

CONTENT PROTECTION DEVELOPER GUIDE | AUTHORIZATION | 31

AUTHORIZATION

Publishers use playback authorization to ensure that videos can be played only from an authorizedaccount. The Ooyala Player Token helps ensure that only authorized viewers can view content. Forinstance, viewers are prevented from sharing content with friends who don’t have accounts. In addition,Ooyala is integrated with Adobe Pass so American Pay TV subscribers can get access to online versionsof their favorite channels.

Concurrent stream limits let publishers limit the number of simultaneous streams being played by oneparticular user account. This protects a publisher’s revenue streams by limiting paying subscriberswho share login information with friends. It also meets stringent studio license agreements that specifyconcurrent stream limit enforcement in addition to using industry-accepted DRM technologies.

PLAYER AUTHORIZATION API FOR PLAYER V3The Authorization API request is a key element of Ooyala's content protection features.

Note: This API applies to Player V3. For information on the Player Authorization API for Player V4, seePlayer Authorization API for Player V4 on page 35.

A request to the Authorization API has the following syntax:

[GET]/sas/player_api/v1/authorization/embed_code/pcode/ListOfCommaSeparatedEmbedCodes?query_string_paramters

Example:

http://player.ooyala.com/sas/player_api/v1/authorization/embed_code/R0Y3Y6HtBEQtRUoC55GY8DTF4pGA/44azdwNDpSWUvfd8F30d55tXY0YH9njH?device=html5&domain=www.ooyala.com&supportedFormats=m3u8%2Cmp4

ROUTE ATTRIBUTES

The following table describes all attributes of the route.

Attribute Description

pcode Your provider code

ListOfCommaSeparatedEmbedCodes Embed codes (content IDs or asset IDs) must beseparated by commas in this list.

QUERY STRING PARAMETERS

The following table describes the query string parameters of the routes. The request can have severaloptional query string parameters following in suit. The only required parameter is domain.

Parameter Description Required?

domain Domain of the player embed. Yes



timestamp Timestamp in which the requestwas made (epoch time).

Default: Time request received byserver

No

supported_formats List of comma-separated valuesindicating supported formats.The value of this parameter isnormally tightly coupled with thedevice type, since support forformats is limited by device.

Valid Values: Shown in tablebelow

No

device List of comma-separated devicesfor playback.

Valid Values: See table below

No

jsonp Value of this parameter will beused as the wrapper in returningJSONP.

Default: JSON

No

embed_token Discussed in section "OoyalaPlayer Token" in the PlayerDeveloper Guide.

No

auth_token Authorization token, discussed inLimiting Concurrent Streams perViewer on page 39

No

SUPPORTED FORMATS AND DEVICESThe supported_formats parameter can be a list of any of the following values, separated by commas.

Format Value

DASH dash

HDS hds

RTMP RTMP

HLS m3u8

MP4 mp4

Akamai HD akamai_hd

Fairplay HLS fps

Widevine HLS wv_hls

Widevine MP4 wv_mp4

Widevine WVM wv_wvm

Adobe Access HLS faxs_hls


Format Value

MicroSoft Smooth Streaming.

Note: For smooth streaming, device (see below)must be GENERIC.

smooth

The device parameter can be a list of any of the following values, separated by commas:

• IPHONE

• IPAD

• APPLE_TV

• ANDROID_SDK

• ANDROID_3PLUS_SDK

• ANDROID_HLS_SDK

• HTML5

• GENERIC_FLASH

• GENERIC

RESPONSE FROM THE AUTHORIZATION API

When the caller makes an authorization request, the Authorization API responds to the caller with a JSONarray indicating the authorization status for each of the embed codes included in the list in question. Thefollowing is a sample response from the Authorization API:

{ "debug_data":{ "server_latency":"21.919", "request_id":"domU-12-31-39-0B-D2-11_1346804527_57", "user_info":{ "ip_address":"204.124.203.201", "continent":"NORTH AMERICA", "country":"US", "request_timestamp":"1346804527", "language":"en-us", "device":"html5", "timezone":-7, "domain":"www.ooyala.com" } }, "signature":"0pobcTRSLoiSZchrMI7Aeoub05/OKRIavq36BgW74lU=\n", "authorization_data":{ "44azdwNDpSWUvfd8F30d55tXY0YH9njH":{ "authorized":true, "message":"authorized", "code":"0", "request_timestamp":"1346804527", "retry":null, "streams":[ { "delivery_type":"hls", "url":{ "data":"aHR0cDovL3BsYXllci5vb3lhbGEuY29tL3BsYXllci9pcGhvbmUvNDRhemR3TkRwU1dVdmZkOEYzMGQ1NXRYWTBZSDluakgubTN1OA==", "format":"encoded", "token_expire":"1460744544" } } ]


} }}

ELEMENTS OF THE RESPONSE

The significant portions of the response are in boldface type in the sample. These parts of the responseare:

1. debug_data is used only for debugging data. It can change at any time.2. signature in the response is used to ensure that the response has not been tampered with by a 3rd

party.3. streams are included if the embed code was authorized, including the base64 encoded url to access

those streams. Each stream can return with an authorization result of:

• "authorized"• “unauthorized parent"• "unauthorized domain"• "unauthorized location"• "unauthorized device"• “current time is before the flight start time" (before flight start time)• "current time is after the flight end time" (after flight end time)• "current time is outside any availability period" (outside recurring flight times)• "this is not a recognized embed code"• "invalid signature" (invalid signature in the request, potentially when using token based playback)• "missing parameters" (required parameters are missing)• "missing rule set" (when authorizing using a rule set rather than a syndication group)• “unauthorized” (this message rarely, if ever, used, in favor of more specific messages)• "missing pcode",• "invalid token" (error code for token based playback and Adobe Pass)

For response that includes a Widevine stream, the additional property widevine_server_path isreturned. This value should be passed along with the stream URL to the playback SDKs for obtaining theWidevine license and decrypting the token.

{ "authorization_data":{ "huNWp2NjoCaCKrsV_wqBdcSw9P1XmlwW":{ ... "streams":[ { "delivery_type":"wv_wvm", "url":{ ... }, "widevine_server_path":"http://player.ooyala.com/sas/drm2/lvcjAxOj82_rjlIAJ6Jr8ZZqGP-s/huNWp2NjoCaCKrsV_wqBdcSw9P1XmlwW/widevine/ooyala" } ] } }, "debug_data":..., "signature":"Fo6ewzq2tTrLJrFmjo5eQpeKUOoLvhSen7KLjrFU1YQ=\n"}


For per-viewer concurrent stream limits, additional properties are returned, as detailed in LimitingConcurrent Streams per Viewer on page 39.

PLAYER AUTHORIZATION API FOR PLAYER V4The Authorization API request is a key element in Ooyala's content protection features.

Note: This API applies to Player V4. For more information on the Player Authorization API for Player V3,see Player Authorization API for Player V3 (Deprecated).

A request to the Authorization API has the following syntax:

[GET]/sas/player_api/v2/authorization/embed_code/pcode/ListOfCommaSeparatedEmbedCodes?query_string_paramters

Example:

http://player.ooyala.com/sas/player_api/v2/authorization/embed_code/R0Y3Y6HtBEQtRUoC55GY8DTF4pGA/44azdwNDpSWUvfd8F30d55tXY0YH9njH?device=html5&domain=www.ooyala.com&supportedFormats=m3u8%2Cmp4

ROUTE ATTRIBUTES

The following table describes all attributes of the route.

Attribute Description

pcode Your provider code

ListOfCommaSeparatedEmbedCodes Embed codes (content IDs or asset IDs) must beseparated by commas in this list.

QUERY STRING PARAMETERS

The following table describes the query string parameters of the routes. The request can have severaloptional query string parameters following in suit. The only required parameter is domain.


domain Domain of the player embed. Yes

timestamp Timestamp in which the requestwas made (epoch time).

Default: Time request received byserver

No

supported_formats List of comma-separated valuesindicating supported formats.The value of this parameter isnormally tightly coupled with thedevice type, since support forformats is limited by device.

No



Valid Values: Shown in tablebelow

jsonp Value of this parameter will beused as the wrapper in returningJSONP.

Default: JSON

No

embed_token Discussed in section "OoyalaPlayer Token" in the PlayerDeveloper Guide.

No

auth_token Authorization token, discussed inLimiting Concurrent Streams perViewer on page 39

No

SUPPORTED FORMATS AND DEVICESThe supported_formats parameter can be a list of any of the following values, separated bycommas. A stream for each format specified in the supported_formats parameter is returned. If thesupported_formats parameter is blank, streams for all available formats are returned.

Format Value

DASH dash

HDS hds

RTMP RTMP

HLS m3u8

MP4 mp4

Akamai HD akamai_hd

Fairplay HLS fps

Widevine WVM wv_wvm

Adobe Access HLS faxs_hls

MicroSoft Smooth Streaming smooth

RESPONSE FROM THE AUTHORIZATION API

When the caller makes an authorization request, the Authorization API responds to the caller with a JSONarray indicating the authorization status for each of the embed codes. The following is a sample responsefrom the Authorization API:

{ "authorization_data":{ "NiMmNsODprSK3Uo3-EIBA5bbhuThv0Rn":{ "authorized":true, "code":"0", "message":"authorized", "request_timestamp":"1460678999", "retry":null, "synd_rule_failures":null, "require_heartbeat":false,


"restrict_devices":false, "streams":[ { "delivery_type":"dash", "url":{ "format":"encoded", "data":"aHR0cDovL3NzLmMub295YWxhLmNvbS9vbmRlbWFuZC9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi8xLmlzbS9NYW5pZmVzdA==" } , "drm": { "widevine" :{ "la_url":"https://player.ooyala.com/sas" } , "playready":{ } } } }, { "delivery_type":"hls", "url":{ "format":"encoded", "data":"aHR0cDovL3BsYXllci5vb3lhbGEuY29tL3BsYXllci9pcGhvbmUvTmlNbU5zT0RwclNLM1VvMy1FSUJBNWJiaHVUaHYwUm4ubTN1OD9zZWN1cmVfaW9zX3Rva2VuPU5sUlZRVmxyVTBRemVIUTFaakpCUkhoWFVHcFpkMUpPVjJGaVRXdDBVbTVLUlhoa2NGTkhRbGhYV1RKWFowSjVkV2NyVVdkR2FqRjZRaXRwQ2pGaFVWRk5Va3RaVm1aSmIwTldUbVp3UmxwR016VllTMFJuUFQwSw==", "ios_token_expire":1460679000 }, "drm": { "fairplay" :{ "la_url":"https://player.ooyala.com/sas","certificate_url":"https://blah" } } },{ "delivery_type":"smooth", "url":{ "format":"encoded", "data":"aHR0cDovL3NzLmMub295YWxhLmNvbS9vbmRlbWFuZC9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi8xLmlzbS9NYW5pZmVzdA==" } }, { "delivery_type":"hds", "url":{ "format":"encoded", "data":"aHR0cDovL2FrLmMub295YWxhLmNvbS9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbl8xLmY0bQ==" } },{ "video_bitrate":4500, "profile":"baseline", "width":1280, "height":960, "framerate":"30.0", "video_codec":"h264", "audio_bitrate":128, "delivery_type":"rtmp", "url":{ "format":"encoded", "data":"cnRtcDovL2NwNzY2NzcuZWRnZWZjcy5uZXQvb25kZW1hbmQvcy9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi9ET2NKLUZ4YUZyUmc0Z3RERXdPalEwWXpvd09ERTdKOA==" } },{ "video_bitrate":4500, "profile":"baseline", "width":1280, "height":960, "framerate":"30.0", "video_codec":"h264", "audio_bitrate":128, "delivery_type":"mp4",


"url":{ "format":"encoded", "data":"aHR0cDovL2FrLmMub295YWxhLmNvbS9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi9ET2NKLUZ4YUZyUmc0Z3RERXdPalEwWXpvd09ERTdKOA==" } } ] } }, "user_info":{ "ip_address":"198.38.13.132", "domain":"test.com", "request_timestamp":"1460678999", "country":"US", "timezone":-7.0, "continent":"NORTH AMERICA" }, "debug_data":{ "server_latency":"43.505105", "request_id":"54e3b3c4933120b8b7d6fb6382c5edb9", "user_info":{ "request_timestamp":"1460678999" } }, "auth_token":"c1hIVDBBK3hKNVRYV01vZVowNnNLZmJJQWcxa2FhMDc4SXBZektGVXFjdnI2VGVOeFNVTjZPV1Y4ZmJNCmxXTTNQdVo1NUhIZnlYbmN6TDduM1RGSFNqUGhDTHdscnUxbG9iK3JzWGRsT21JWFRCUnRDVzBuTjU1RQp1cEYvMXd6aGhvSlJ0TllSZFlTSHZZd2RqN1BxV0MzSEY4L25DOW9WS3JZOStKTGxoQmVHN0lidFV0QkQKcDBrSkVieFUwcHZuV2tNM1ZBNEF3ZXRYNWh6Nzd3ekFwSm5LRlNFWUJ3SWVlVmZ3ODA3MGZSamQ3czZlCmx3amxVR1FwNVhEbzAyK0wK", "auth_token_expires":1460684999, "heartbeat_data":{}, "signature":"HBZJC39psbeF30Do6WHQJQRIkA2qRWzcT3gUcKGGnXg="}

ELEMENTS OF THE RESPONSE

The significant portions of the response are in boldface type in the sample. These parts of the responseare:

1. debug_data is used only for debugging data. It can change at any time.2. signature in the response is used to ensure that the response has not been tampered with by a 3rd

party.3. streams are included if the embed code was authorized, including the base64 encoded url to access

those streams. Each stream can return with an authorization result of:

• "authorized"• “unauthorized parent"• "unauthorized domain"• "unauthorized location"• "unauthorized device"• “current time is before the flight start time" (before flight start time)• "current time is after the flight end time" (after flight end time)• "current time is outside any availability period" (outside recurring flight times)• "this is not a recognized embed code"• "invalid signature" (invalid signature in the request, potentially when using token based playback)• "missing parameters" (required parameters are missing)• "missing rule set" (when authorizing using a rule set rather than a syndication group)• “unauthorized” (this message rarely, if ever, used, in favor of more specific messages)• "missing pcode",• "invalid token" (error code for token based playback and Adobe Pass)

For per-viewer concurrent stream limits, additional properties are returned, as detailed in LimitingConcurrent Streams per Viewer on page 39.


LIMITING CONCURRENT STREAMS PER VIEWERBy default, your Ooyala Backlot provider account limits each viewer account to 2 concurrent streams. Thisfeature discourages viewers from sharing their credentials with friends who don’t have accounts. If theviewer, or someone with their account credentials, tries to open an additional stream while the maximumnumber of streams is open, the player displays a message and refuses to open the stream. This defaultlimit applies across all of the syndication groups (aka publishing rules) within your provider account. Youchange this limit, and you can enable or disable the limit on a per-group basis. You can also enable ordisable this setting for the default group. You can change your Ooyala Backlot provider account limit.You can also set this type of limit at the asset level. For example, your provider account limit could be 3,and your asset-level limit could be 1. In this case, three friends or family members could log in using thesame credentials and watch three different assets concurrently, but would be blocked from watching anyparticular asset concurrently.

CHANGE THE LIMIT FOR YOUR PROVIDER ACCOUNT

To change the provider account limit, ask your contact person at Ooyala to set the new limit. Also enablethis limit using the Backlot UI or a Backlot API call. This approach is intended to prevent the limit frombeing changed accidentally.

In the Backlot UI

1. Log in to Backlot UI.2. Click the PUBLISH tab.3. Click the Syndication Controls subtab.4. On the left, select the appropriate Syndication Group or Default Group.5. On the right, verify that the checkbox for Require Ooyala Player Token is checked.6. Under Require Ooyala Player Token, check Limit per-user concurrent streams. You have now

enabled the restriction of concurrent streams for your account, but you have not set the limit.7. Contact your Ooyala contact person to set the provider level limit.

With the Backlot API

1. Add the restrict_concurrent_streams property to the publishing rules and set its value totrue. For example, add this property to a previously created publishing rule by making a call to https://api.ooyala.com:

[PATCH]/v2/publishing_rules/9b70a34a67881c7a291d8b{ “restrict_concurrent_streams” : “true”}

2. Ask your Ooyala contact to set the provider level limit.

ENABLING AN ASSET LIMITYou can enable a concurrent stream limit at the asset level and set it yourself with a Backlot API call.

With the Backlot API

1. Set the asset limit by adding the property max_concurrent_streams to the appropriate publishing rules.Include an integer that represents the asset limit. In the following example, this property is added to apreviously created publishing rule by making a call to https://api.ooyala.com:

[PATCH]/v2/publishing_rules/9b70a34a67881c7a291d8b{ “restrict_concurrent_streams” : “true”, “max_concurrent_streams” : “1”}


USING PUBLISHING RULES AND ENTITLEMENTS TO APPLY AN ASSET LIMIT

You can apply limits to an asset using three different approaches:

• You can use Rights Locker to create an entitlement that contains an asset limit, and then use Backlot toapply that entitlement to an asset (using Require user entitlement).

• You can use Backlot create a syndication group (aka publishing rule) that contains an asset limit, andassociate an group with an asset (using the Publish or Manage tab).

• You can do both: Apply an entitlement to an asset and associate that asset with a group. In this case,the entitlement's limit overrides the groups' limit.

Note: To take down an unauthorized stream, delete an asset's entitlement, as described in StoppingUnauthorized Streams on page 49

Provider Level Limit Asset Limit Resulting Limits

- - No more than 2 (default) per useraccount per provider.

3 - No more than 3 per user account perprovider.

3 1 1 per asset. No more than 3 per useraccount per provider.

1 3 1 per asset and 1 per user account perprovider.

ASSET LIMIT USE CASE

The scenario requiring an asset limit:

• A publisher named "Movie Provider" wants to sell the movie Ooyala Movie as an Electronic SellThrough (EST) asset.

• Ooyala Movie must have an asset limit of 3.• User "Fan" purchases Ooyala Movie from Movie Provider.

To restrict Fan from watching Ooyala Movie on more than 3 concurrent streams, Movie Provider couldperform one of the following actions:

• Create a publishing rule in Backlot ("EST" publishing rule, for example) with restrict_concurrent_streamset to true and max_concurrent_stream set to 3.

• Associate Ooyala Movie with a "default" publishing rule in the Backlot UI by enabling Require userentitlement.

• Using Ooyala Rights Locker API, create an entitlement for the user, Fan, that allows him to watchOoyala Movie, and associate the "EST publishing rule" with this entitlement. See Rights Locker APIReference.

HOW IT WORKS

Concurrent stream limits can be enforced on HTML5 players, Flash players, Google Android, and AppleiOS.

To enforce the concurrent stream limits, the player has to keep sending the heartbeat requests to Ooyalasystems. Sending of heartbeat requests is already implemented on the Ooyala Flash player, HTML5player, Chromecast, iOS and Android SDKs. On these platforms, you don't need to write any code forsending the heartbeat requests. Using any other player will require that you implement the heartbeat. Youcan configure the heartbeat by contacting your Ooyala contact person.


The Ooyala service keeps a count of the active streams for each of your viewers (customer accounts).When a viewer attempts to access your content, your client application program calls Ooyala’sAuthorization API. The system returns:

• An indication that a heartbeat is required: require_heartbeat• An authorization token: auth_token• A heartbeat interval in seconds: heartbeat_interval

As long as the client maintains the heartbeat, the count of concurrent streams is maintained. After theviewer leaves the page or exits the mobile application, the client no longer sends the heartbeat, and theservice lowers the count.

Please note that the account_id is needed to create a token for concurrent streams.

The table below shows the sequence of actions, from left to right and downward.

Viewer The client application Ooyala

Access content First GET to Authorization API Increment concurrent streamcount by one.

Return:

• require_heartbeat set totrue

• auth_token

• heartbeat_interval inseconds

Immediately send auth_token toOoyala as heartbeat

Begin and continue playback Send auth_token as heartbeatevery heartbeat_intervalseconds

Respond “OK”

Maintain concurrent stream count

End playback Stop sending heartbeat Decrement the counter by one

When the viewer closes the player in the web page or client application, the service stops receiving aheartbeat. After a period, the service stops the stream, invalidates the auth_token, and decreases thecount of concurrent streams by one.

For security reasons, Ooyala does not disclose the precise length of time before the service invalidates theauth_token.

SYNTAX OF HEARTBEAT HTTP REQUEST AND RESPONSE

The syntax of the GET request to maintain the heartbeat is as follows:

[GET]/sas/player_api/v1/auth_heartbeat/pcode/pcode/auth_token/auth_token

where pcode is your provider code and auth_token is the value of the auth_token property returned bythe Ooyala service.

Note: To enforce content protection, when the client receives the first response that includes theauth_token, it immediately sends a heartbeat. It does not wait for heartbeat_interval secondsbefore sending the first heartbeat.

After that, the client GETs the heartbeat continually at heartbeat_interval seconds until the viewerexits the player web page or application.


To use the asset limits feature, send embed_code as a query parameter:

[GET]/sas/player_api/v1/auth_heartbeat/pcode/pcode/auth_token/auth_token?embed_code=embed_code

The response to a successful heartbeat request looks like this:

{ "auth_token"=>"ABC", "message"=>"OK", "expires"=>1360877041, "signature"=>"2sBWFegOi+hqvz4ektiHM/VzO3cUoQ2c+5/YOgyldtw="}

Any message other than “OK” indicates failure. In that case, the client application should stop playback.

FULL EXAMPLE WITH ALL PROPERTIES

The following example shows a first-time GET to the Authorization API. The response in this examplehighlights the following properties: require_heartbeat, auth_token, and heartbeat_interval.The service uses these properties to enforce the concurrent stream limit. Note that the actual valuesreturned are much longer. The strings than is shown here have been shortened for ease of reading. Thenfollows the request/response sequence to maintain the heartbeat.

First Request

[GET]http://player.ooyala.com/sas/player_api/v1/authorization/embed_code/FoeGbkH9m/VxMDhwFbICE7ojQ9jZM? domain=gnarly.com&embedToken=http%3A%2F%2Fplayer.ooyala.com%2Fsas%2Fembed_token%FoeGbkH9%3Faccount_id%3DTest_Account%26 api_key%3xxx%26expires%3Dyyy%26signature%3zzz

Response

{ "authorization_data" => { "VxMDhwNzoq2j8qfyiG6FbICE7ojQ9jZM" => { "authorized" =>true, "code" =>"0", "message" =>"authorized", "request_timestamp" =>"1360878715", "retry" =>nil, "synd_rule_failures" =>nil, "require_heartbeat" =>true, "streams" => [ { "delivery_type" =>"hds", "url" => { "format" =>"encoded", "data" => "aHR0cDovLmY0bQ==" } } ] } }, "user_info" => { "ip_address" =>"192.168.1.1", "domain" =>"gnarly.com", "request_timestamp" =>"1360878715", "account_id" =>"johnsmith", "country" =>"UNKNOWN",


"timezone" =>-8.0, "continent" =>"NA" }, "debug_data" => { "server_latency" =>"58.778999999999996", "request_id" =>"4f397d7f6091ce8e7d43354c424095fe", "user_info" => { "request_timestamp" =>"1360878715" } }, "auth_token" => "WGd5uZ29WTFBpeDlnPT0K", "heartbeat_data" => { "heartbeat_interval" =>300 }, "signature" =>"b09xu7UxL/uFRJ9MOkmhISpRSF21zcOK+7iv1LfcNVA="}

Immediately Send Heartbeat

[GET]http://player.ooyala.com/sas/player_api/v1/auth_heartbeat/pcode/FoeGbkH9m/auth_token/WGd5uZ29WTFBpeDlnPT0K

Response

{ "auth_token"=>"ABC", "message"=>"OK”, "expires"=>1360877041, "signature"=>"2sBWFegOi+hqvz4ektiHM/VzO3cUoQ2c+5/YOgyldtw="}

Heartbeat Interval

By default, this value is 300 seconds. This limit is configurable at the provider level, which will overridethe default value. The lower limit of the heartbeat interval is capped at 30 seconds. Please contact youraccount manager to configure this limit.

[GET]http://player.ooyala.com/sas/player_api/v1/auth_heartbeat/pcode/FoeGbkH9m/auth_token/WGd5uZ29WTFBpeDlnPT0K

Response

{ "auth_token"=>"ABC", "message"=>"OK", "expires"=>1360877046, "signature"=>"2sBWFegOi+hqvz4ektiHM/VzO3cUoQ2c+5/YOgyldtw="}

CONFIGURABLE PADDING (HEARTBEAT LATENCY)

Configurable padding determines the lifetime of a stream. If this attribute is not set, a default latency of30 seconds will be used. We recommend setting a default latency greater or equal to 10 seconds. Pleasecontact your account manager to configure this limit.


WHEN THE LIMIT IS REACHED

When the limit is reached the viewer fails authorization. The response body, under the authorized failuremessage, includes code set to 18 and an explanatory message.

. . .{ "authorized" =>false, "code" =>"18", "message" =>"Too many open videos. Close other videos on this account and try again in a few minutes.", "request_timestamp" =>"1361401545", "retry" =>nil, "synd_rule_failures" =>nil, "require_heartbeat" =>true} . . .

Ooyala’s HTML5 and Flash players catch this error message and display a pop-up message to the viewer.

EXCEPTIONS YOU MUST CATCH ON MOBILE APPLICATIONS

On mobile client applications (Google Android and Apple iOS), when authorization fails or a heartbeat fails,the following exceptions are thrown.

Google Android Apple iOS When Thrown

ERROR_AUTHORIZATION_

FAILED

OOOoyalaErrorCodeAuthorizationFailed Concurrent streamlimit reached

ERROR_AUTHORIZATION_

HEARTBEAT_FAILED

OOOoyalaErrorCodeHeartbeatFail Failure in heartbeatrequest

When these exceptions are thrown, your client applications must catch them to display an appropriatemessage. For instance, on Android in Java, enclose your GETs for authorization and for a heartbeatin a try/catch structure. For iOS use whatever mechanism is standard for your company to accomplish“exception handling.”

OTHER BEHAVIORAL RECOMMENDATIONS ON MOBILE AND DESKTOP

In any application, if the viewer pauses a video, you should still send heartbeat requests.

On both desktops and mobile devices, a viewer can suspend an application into the background:

• Your mobile application should save a timestamp before backgrounding and then cease sendingheartbeats. When the viewer resumes the application, check the saved timestamp. If the elapsedtime is less than heartbeat_interval, simply resume playback. Otherwise, you should requirereauthorization, get a fresh auth_token and start a new heartbeat.

• A suspended desktop application cannot continue sending heartbeats. This increases the likelihood thatan auth_token will expire before activity resumes.

To stop heartbeats completely:


• On a desktop browser, the viewer has to exit the page.• On a mobile application, the viewer has to exit the application.

ABOUT CHANNEL CHANGING

For viewers who are channel changing, your program can pass previous auth_tokens for authorizationso the count is not incremented against the limit. In this case, the viewer can quickly switch videos withoutraising the concurrent stream count.

ENFORCING PER-STUDIO LIMITS ON CONCURRENT STREAMSThe Category API allows you to group assets into categories according to the concurrent stream limitsrequired by a studio or other content owner. A concurrent stream limit is the maximum number of uniquemovie titles a user can watch simultaneously. You create a category for a studio, set the limit of concurrentstreams allowed by that studio, then assign specific assets to the category. Actions taken on categoriesdo not change any of the attributes associated with the assets within the category, it only changes theircategorization. Use the Backlot API to work with categories of movies. Use the Rights Locker API to setlimits on the categories for a specific user. All category routes are authenicated prior to allowing access.

HOW TYPES OF LIMITS INTERACT

The concurrent stream limit for a studio is a limit on the number of unique movie titles belonging to thatstudio (category) that a user can watch at a given time. This is different from the concurrent streamlimit that you specify globally for your provider account, per viewer or per asset as described in LimitingConcurrent Streams per Viewer on page 39. The limit for a studio takes precedence over the othertypes of limits, but only within the other limits.

For example, suppose you have set your provider account to a global limit of 3 movies. This means noneof your viewers can watch more than 3 movies at once. Then you add 2 categories, one for each studioyou are working with:

• Studio DEF - Supermovie A, Supermovie B, Supermovie C• Studio XYZ - Ooyala Movie 1, Ooyala Movie 2, Ooyala Movie 3

Suppose you set both studio limits at 2 titles. When the studio limit of 2 is combined with the provider limitof 3, the result is each user can watch up to 3 streams at a time, out of which only 2 titles can be from thesame studio. When watching more than 2 titles, one title must be from the other studio. So, a user cannotwatch Ooyala Movie 1, Ooyala Movie 2 and Ooyala Movie 3 at the same time because it would breach thestudio limit of 2 titles for Studio XYZ, even though the total number of video streams is under the providerlimit of 3.

A user can watch Supermovie A on 3 different streams without exceeding any limit because it is only onetitle. Similarly a user can watch Ooyala Movie 1, Ooyala Movie 3, plus another Ooyala Movie 3 on anotherstream because this does not breach the limit of 2 titles for Studio XYZ. In this case the viewer is watchingonly 2 titles in total, with 1 title being repeated on 2 different streams. This also does not breach yourprovider limit of 3 streams.

Likewise, a user can watch Supermovie A, Supermovie B and Ooyala Movie 1 at the same time becausethis is within your global provider limit of 3 streams and also within the limit of 2 movie titles per studio. Inthis case the user is watching 2 titles from Studio DEF and just 1 title from Studio XYZ.

API SERVER: HTTPS://API.OOYALA.COM

The Backlot API is used to create, retrieve and delete categories of movies for a studio.


Note: GET requests for the Backlot API are made to the server https://cdn-api.ooyala.com. Otherrequests are made to http://api.ooyala.com or https://api.ooyala.com.

SET MOVIE CATEGORIES

Create new categories of movies for a studio:

POST https://api.ooyala.com/v2/assets/asset_id/concurrent_streams_categories

Example request body:

{ "categories" : [ "cat1", "cat2", "cat3" ] }

Any existing categories will be replaced by the provided categories. To delete the contents of allcategories, send an empty array.

Upon success, the value 200 Success is returned. Upon failure, the code 404 Not Found is returned.

GET MOVIE CATEGORIES

Retrieve movies by category for a studio:

GET https://cdn-api.ooyala.com/v2/assets/asset_id/concurrent_streams_categories

Upon success, the response is a list of categories.

Example response:


Upon failure, the code 404 Not Found is returned.

DELETE MOVIE CATEGORIES

Delete a category of movies for a studio:

DELETE https://api.ooyala.com/v2/assets/asset_id/concurrent_streams_categories

Upon success, the categories being deleted are listed.

Example response:


Upon failure, the code 404 Not Found is returned.


SET LIMITS ON CATEGORIES

Set a limit on the number of movie categories for your account for a studio:

POST https://api.ooyala.com/v2/concurrent_streams_categories


{ "cat1" : 1, "cat2" : 5, "cat3" : 8}

Example response:

{ "cat1" : 1, "cat2" : 5, "cat3" : 8}

Upon success, each existing category listed is replaced by its corresponding category. To edit a subset oflimits use a PATCH route. To delete all limits use a DELETE route.

EDIT LIMITS ON CATEGORIES

Edit the limits for the provided categories. Any other categories will remain unchanged.

PATCH https://api.ooyala.com/v2/concurrent_streams_categories


{ "cat1" : 3, "cat3" : 2}

Example response:

{ "cat1" : 3, "cat3" : 2}

GET LIMITS ON CATEGORIES

Get concurrent stream limit for each category at the provider level:

GET https://cdn-api.ooyala.com/v2/concurrent_streams_categories

Example response:

{ "cat1" : 3,


"cat3" : 2}

DELETE LIMITS ON CATEGORIES

To delete all limits on all categories:

DELETE https://api.ooyala.com/v2/concurrent_streams_categories

Example response:

{ "cat1" : 3, "cat3" : 2}

API SERVER: HTTPS://RL.OOYALA.COM

The Rights Locker API is used to set limits on categories for specific users.

Note: GET requests for the Rights Locker API are made to the server https://cdn-api.ooyala.com.Other requests for the Rights Locker API must be made to the server https://rl.ooyala.com, not http://api.ooyala.com or https://api.ooyala.com.

SET CATEGORY LIMITS FOR A USER

Replace existing categories with the provided categories for a specific user:

POST https://rl.ooyala.com/concurrent_streams_categories/pcode/pcode/account_id/account_id


{ "cat1" : 3, "cat2" : 2, "cat3" : 5}

To edit a subset of the limits use the PATCH route. To delete all limits use the DELETE route.

Example response:

{ "cat1" : 3, "cat2" : 2, "cat3" : 5}

EDIT CATEGORY LIMITS FOR A USER

Update the limits for existing categories for a specific user. Any other categories remain unchanged.

PATCH https://rl.ooyala.com/concurrent_streams_categories/pcode/pcode/account_id/account_id



{ "cat1" : 3, "cat2" : 2, "cat3" : 5}

GET CATEGORY LIMITS FOR A USER

Retrieve the list of limits for every category associated with a specific user:

GET https://cdn-api.ooyala.com/concurrent_streams_categories/pcode/pcode/account_id/account_id

Example body:

{ "cat1" : 3, "cat2" : 2, "cat3" : 5}

Example response:

{ "cat1" : 3, "cat2" : 2, "cat3" : 5}

DELETE CATEGORY LIMITS FOR A USER

Delete the limits for every category for a specific user:

DELETE https://rl.ooyala.com/concurrent_streams_categories/pcode/pcode/account_id/account_id

Example response:

{ "cat1" : 3, "cat2" : 2, "cat3" : 5}

STOPPING UNAUTHORIZED STREAMSYour Ooyala Backlot provider account can be configured to allow you to stop unauthorized streaming inrealtime. Then, to stop unauthorized access to an asset as it is streaming, use Rights Locker to deletethe entitlement or contact your Ooyala Customer Support Manager to do it for you. The deletion of theentitlement causes stream takedown to occur immediately.


CONFIGURING YOUR ACCOUNT FOR STREAM TAKEDOWN

To takedown an unauthorized stream, you need to take these steps.

1. Contact your Customer Success Manager to configure your account's provider attribute for streamtakedown.

2. Associate an asset with a publishing rule that is enabled for stream takedown.3. Delete the entitlement for the unauthorized asset as it is streaming.

PREPARING FOR STREAM TAKEDOWN IN BACKLOT

You configure your account using the Backlot UI to prepare for stopping an unauthorized stream.

In the Backlot UI

1. Login to Backlot UI.2. Go to the PUBLISH tab.3. Go to the Syndication Controls subtab.4. On the left select the appropriate asset and examine its publishing rule.5. On the right, make sure the publishing rule checked Require Ooyala Player Token. If not, do so.6. Under Require Ooyala Player Token, make sure both Require user entitlement and Limit per-user

concurrent streams are checked. If not, do so.

DELETING THE ENTITLEMENT TO STOP THE STREAM

Use the Rights Locker API to delete the entitlement for the unauthorized stream or contact your CustomerSuccess Manager to delete it for you. Deleting the entitlement will interrupt the stream's heartbeat, so theasset will be prevented from playing at the next heartbeat.

CONTENT PROTECTION DEVELOPER GUIDE | ACCESS CONTROL | 51

ACCESS CONTROL

Publishing rules give publishers complete control over their content by enabling control of where andwhen contents can be viewed. It also allows or restricts website domains that can show content byeither specifying a list of domains that are allowed to embed the publisher’s content or specifying a list ofdomains that cannot embed content.

Please see the following topics for more information about access control:

• Enable Publishing Rules with the Backlot UI• Enable Syndication Controls with the Backlot UI• Enable Publishing Rules with the Backlot API• Backlot API Reference - Publishing Rules• Enable Syndication Controls with the Backlot API• Enable Access Keys

CONTENT PROTECTION DEVELOPER GUIDE | RIGHTS MANAGEMENT | 52

RIGHTS MANAGEMENT

The Ooyala Rights Locker is a highly scalable authorization system that enforces granular access controlto VOD/live/linear content, based on rights (entitlements) that publishers assign to each consumer.Publishers can update the rights locker through APIs to grant and remove rights to either an individualasset or a “bundle” (collection) of assets; assets can be discrete movies, live events, linear channels oreven specific virtual assets within a given channel. When added to other content protection capabilities(such as multi-DRM, encrypted streaming, and authentication), Rights Locker also gives publishersbetter visibility into usage patterns and revenue streams, such as the numbers of active subscribers,authenticated users and rentals or purchases.

If binding viewer devices to entitlements is enabled via Rights Locker Entitlement APIs, this bindsentitlements to viewer devices. Mostly used for higher value (purchase or rental window) assets. As withDevice Management, required by studios to go with a robust DRM deployment to open devices. This is arestriction with which users will not have an option to share their login credentials.

RIGHTS LOCKER

Rights Locker is a set of application programming interfaces (APIs) for defining and managing entitlementsto digital assets. As a whole Rights Locker consists of three sets of APIs and Ooyala services.

API Location Description

Backlot API Backlot REST API • Manages assets (videos)• Manages labels• Manages publishing rules

Rights Locker API Rights Locker API Reference • Creates and managesentitlements for customer-defined accounts, usingassets, labels and publishingrules defined in the BacklotAPI

Player Authorization API Player Authorization API forPlayer V3 (Deprecated)

• Run-time check ofauthorization and entitlements

Using Rights Locker has three parts:

1. With Backlot API methods (documented in the Backlot API Reference), create assets (videos), labels,and publishing rules. (The Backlot UI can also be used.)

2. With the Rights Locker API described here, combine the predefined assets, labels, and publishing rulesto create and group entitlements for individual users.

3. With the player, verify the authorization to entitlements at playback and when required issue licenses orother credentials for Digital Rights Management (DRM) systems. In the majority of cases, authorizationsimply occurs, without any programming.

Prerequisites to Rights Locker

To use Rights Locker, you need to have the following:


1. Assets and publishing rules in Backlot. Labels are optional for Rights Locker.2. All video players, custom or otherwise, must use the Ooyala Player Token (including a viewer's

account_id in the token) and Authorization API.

Key ConceptsSome essential terms are introduced to help define concepts that are key to Rights Locker.

Term Definition/Description

Asset In Backlot, your materials (videos and the like) are called “assets” and are identifiedby an asset identifier or asset_id (also called “embed code”).

Note: You cannot use external identifiers with Rights Locker. The values passedmust be real embed codes (asset IDs).

Label In Backlot, you can associate your assets with labels you define to categorize yourassets. Labels are identified by label_id.

Provider A provider is the entity that owns the assets to which you assign entitlements.The provider is identified by a provider_id, which is displayed in the Backlot UI'sACCOUNT tab, Developers subtab and is called "Partner Code." You need thisprovider ID to make calls to the Rights Locker API.

Account An account identifies one of your video consumers to whom you grant entitlementto assets. The account is identified by an account_id, which should be secured ina manner recommended in Your Users, Your Accounts: Security on page 54.Rights Locker uses your account IDs only to create the entitlement and for no otherreason. Account IDs are unique by provider.

Publishing Rule A publishing rule is a set of restrictions on content, such as geographic or timelimitations. In Backlot and Rights Locker, there are two kinds of publishing rules:

1. Asset publishing rules intrinsic to the asset itself, such as licensing or globalrestrictions for a piece of content

2. Entitlement publishing rules, which are per user, per label (content-group) formodeling business restrictions around particular transactions or products sold tothe user.

Entitlement An entitlement is a single combination of provider, account, and single content(asset or label) tied to a publishing rule. It is a reflection of the statement:

User X is allowed to watch content Y under the conditions Z.

For every tuple of label_id, user_id, external_product_id, there can be only oneentitlement. Any updates with the same three values will overwrite the previousentitlement. A user can have multiple entitlements to the same label, as long as theyare under different external_product_ids.

Product One or more entitlements together reflect a user's "ownership" (using the termloosely) of a product offered by the provider. These products are grouped byexternal_product_id.

For example, a user might subscribe to the "silver" package and therefore haveaccess to back catalog sitcoms (which are group by a label) on all devices, sportschannels (a label) only on desktops.

A user can "own" different products, and so they can have many differententitlements, grouped under different external_product_ids. For instance, continuingthe above example, the user could own both the silver package that grants access


Term Definition/Description

to sports channels on desktop and also own the mobile package that grants accessto the sports channel on mobile phones.

Your Users, Your Accounts: SecurityUser account ids are distinct per provider. Two different providers can have a user with the same name,but these are treated as distinct users. The account_id you use with Ooyala APIs must be unique inyour own systems. For privacy, Ooyala encourages that the value of account_id be some sort of GUID(global unique identifier), rather than a plain-text username or email address. For example, an acceptableaccount_id is to use a base64, URl-encoded, Secure-hash-algorithm-(SHA)-256 digest of the usernameor email address, salted with some secret string that only you know. This salt must not be reused for any ofyour vendors other than Ooyala. This ensures that neither Ooyala nor a "man-in-the-middle" hacker sniffingnetwork traffic can translate back from your GUIDs to real usernames or passwords. The account_idmust be less than 255 characters and must not contain reserved URL characters such as [/, &, |, or ].In most cases, you do not need to explicitly create an account with Ooyala APIs; you simply refer to anaccount wherever an API request requires it.

How Authorization WorksAuthorization is based on the types of publishing rules described in Publishing Rules.

An asset's authorization is given if its publishing rule passes EITHER of the following conditions for a validuser. This also applies to a label that includes the asset.

CONDITION 1: The asset's publishing rule is valid but user entitlement is not set.

In the Backlot UI this means the asset's publishing rule does not have "Require user entitlement" checked.In the API this means the publishing rule's property require_user_entitlement was set to false.

OR

CONDITION 2: If a valid user tries to stream an asset with a valid publishing rule that has "Require userentitlement" checked or set to true, and at least one entitlement remains unused for the asset.

Multiple entitlements can relate to the same asset, but as long as one of the entitlements passes for theuser, authorization is given and access allowed.

Backlot Setup

Rights Locker relies on Backlot API calls for creating and managing assets (videos), labels, and publishingrules. In addition, Rights Locker authorization relies on the Ooyala Playback Token.

LABELS

Entitlements can be by asset or by label. The Backlot API /v2/labels Backlot API calls create andmanage labels. After creating labels and associating them with assets, with Rights Locker you makecombinations of labels and publishing rules to define entitlements.

Note: Tip on Label Design: The shallower the hierarchy of labels, the better performance, even thoughdeep “trees” of labels are supported.

PUBLISHING RULES

Backlot’s publishing rules are also a prerequisite part of Rights Locker.


Note: Rights Locker requires certain properties in publishing rules:

• The “Require user entitlement” field, require_user_entitlement.• The “Require Ooyala Playback Token” container secure_playback_token and its properties

If you have existing publishing rules you want to use with Rights Locker, be sure to update the appropriaterules with these field. See the example PATCH in Extended Example of Rights Locker on page 55 .

REQUIRE OOYALA PLAYBACK TOKEN

To ensure that all requests for an asset are subjected to authorization, you need to enable the OoyalaPlayer Token under PUBLISH tab, Syndication Controls in the Backlot UI, as shown below.

For a step-by-step process to configure this requirement, see Ooyala Player Token on page 12.

Programmatically, you can add the secure_playback_token properties to publishing rules to requirethe token. See the example PATCH in Extended Example of Rights Locker on page 55.

Extended Example of Rights LockerThis scenario illustrates a complete, end-to-end example of how Rights Locker works in operation,including two of the APIs that are part of Rights Locker.

The idea is to manage entitlements for a Video on Demand (VOD) asset. A viewer account can then begranted access to the content (with Rights Locker API). At the time of playback, the system checks if theauthenticated user account is authorized to access a given piece of content.

In the example below, the asset is my_asset_id. Similarly, with the Backlot API, you can either createa publishing rule or use an existing one. In this example, the user decides to reuse the publishing rule IDmy_publishing_rule_id.

1. Update the publishing rule my_publishing_rule to set the require_user_entitlement field totrue.

Make a request to the Backlot API server at https://api.ooyala.com.

[PATCH]/v2/publishing_rules/my_publishing_rule_id{ "secure_playback_token":{ "enabled":true, // expiration time is in seconds "expiration":600, "require_user_entitlement":"true" }}

2. Add an entitlement for the viewer account identified as gz7XwF_1p2qYM to the asset using thecreation route for Rights Locker detailed in Rights Locker API Reference. (The account ID is actually


constructed with something like the algorithm described in Your Users, Your Accounts: Security onpage 54 so that only the provider knows who the actual viewer is.)

Make a request to the Rights Locker API server at http://rl.ooyala.com:

[POST]/v2/entitlements/providers/932nf90r3mkoewfmungedID/accounts/my_account_id/content{ { “assets”:[ { “content_id”:“my_asset_id”, “publishing_rule_id”:“my_publishing_rule”, “external_product_id”:“12345”, “start_time”:20130902, “end_time”:20140902 } ] }}

The viewer with account my_account_id has now be given an entitlement to asset my_asset_id,according to the rules specified by the my_publishing_rule_id publishing rule.

3. At playback, send a request for authorization to Ooyala’s authorization servers.

The example below (split across several lines for readability) shows an authorization request with anembedded, URL-encoded Ooyala Player Token (OPT), including the user's account ID (account_id%3Dmy_account_id).

Make a request to the http://player.ooyala.com authorization service:

[GET] http://player.ooyala.com/sas/player_api/v1/authorization/embed_code/my_asset_id?domain=test.com& supported_formats=smooth&embedToken=http%3A%2F%2Fplayer.ooyala.com%2Fsas%2Fembed_token%2FFoeG1Q2jqbkH9m%2FU5MHg0YTHZIPHGNsr%3F account_id%3Dmy_account_id%26api_key%3DFo%26expires%3D1376069474%26signature%3DnSYMwiVFzbGE5O%252BWhEbXvm1M

The system retrieves the asset and assigned publishing rules. The system then checks if the useraccount is authorized based on those rules, as described in How Authorization Works on page 54.

In the majority of cases (based on the Ooyala Player without customization), verification of entitlementoccurs automatically with your calls to the Player Authorization API; no additional programming isrequired, as long as you have setup the prerequisite configuration for Rights Locker described inPrerequisites to Rights Locker on page 52.

BINDING VIEWER DEVICES TO ENTITLEMENTSTo protect your assets and ensure that you realize all possible revenue, with Rights Locker in conjunctionwith the Device Registration API on page 60, you can programmatically bind the entitlements yourviewers purchase to the viewers' devices. This binding can prevent your customers from accessing contentthat they have not purchased.

RELATIONSHIP OF DEVICE LIMITS AND DEVICE BINDING

There are several different limits associated with devices and device binding that interact with each other.

• With the Device Registration API on page 60 you can build a portal for your users or customersupport to manage registered devices. An essential parameter is the device_limit: the upper bound


on the number of devices each of your viewers can register. This setting is at the provider level andprevents multiple viewers from sharing the same account.

• Rights Locker gives you the ability to "bind", or associate, the viewer's devices to your contentvia entitlements. The essential parameter is the allowable number of devices that can be bound:num_devices_to_bind. This setting is at the viewer level. For example, after a viewer purchases avideo, once a viewer starts watching a purchased video on a particular device, the video is restricted tothat specific device.

You can bind as many devices as is limited by the device registration device_limit.

These limits are shown graphically below.

• On the left ("A") is the normal relationship: number of devices to bind is a subset of the overall devicelimit.

• The right ("B") shows a case that is possible but that you should make sure to prevent.

When you create a device-bound entitlement, Ooyala does not check the number of bindable devicesagainst the upper limit of devices per provider. This is both for speed of performance and for separationof concern. Most logically, a device-bound entitlement is part of your checkout or purchasing process onyour site. Ooyala has made the creation of entitlements simple to fit in with your checkout, but it is upto you to ensure that "Case B" shown above does not occur, because at playback time, in "Case B", aviewer is denied authorization to access the asset.

Thus, in the design of your device registration portals and your checkout, you need to keep track of thecounts of viewers' device such that "Case B" is avoided.

CREATING A DEVICE-BOUND ENTITLEMENT

When you create an entitlement, include num_devices_to_bind in the body of the request, for eitherassets or labels as described in Rights Locker API Reference and highlighted below.

{ “assets” : [ { “content_id” : “an_embed_code”, “publishing_rule_id” : “publishing_rule_id”, “external_product_id” : “your_product_id”, “start_time” : YYYYMMDD, “end_time” : YYYYMMDD, "num_devices_to_bind" = upper limit number of devices to bind to content },


{ “content_id” : “another_embed_code”, . . . }, . . . ], “labels” : [ { “content_id” : “a_label_id”, “publishing_rule_id” : “publishing_rule”, “external_product_id” : “your_product_id”, “start_time” : YYYYMMDD, “end_time” : YYYYMMDD "num_devices_to_bind" = upper limit number of devices to bind to content }, { “content_id” : “another_label_id”, . . . }, . . . ]}

Note: Ooyala recommends that you create device-bound entitlements only for assets, not for labels. Alabel-based device-bound entitlement means that the viewer must access all assets under the label onlyfrom the same device, which is a bad user experience.

MODIFYING AN ENTITLEMENT'S NUM_DEVICES_TO_BIND: CREATE NEW ENTITLEMENT

You cannot change the value of an existing entitlement's num_devices_to_bind.

Instead, delete the outdated entitlement, and create a new entitlement with the desired value ofnum_devices_to_bind.

BASIC WORKFLOW WITH DEVICE REGISTRATION AND BINDING

The following use case illustrates a basic pattern in device binding. (As detailed in the Device RegistrationAPI on page 60, actual device registration is automatic. You do not need to make any explicit request.)

Note: Not included in this workflow is any necessary interaction with the device registration portal or withyour checkout process.

1. A viewer purchases a single-device movie.2. You create an entitlement for that viewer, including num_devices_to_bind = 1.3. The viewer starts watching the movie on an iPhone.4. The player application makes a request to Ooyala services for authorization, using the Player

Authorization API for Player V3 on page 31.5. Ooyala services determine that the single-use entitlement has not yet been used and registers the

iPhone for that entitlement.6. The viewer tries to watch the same movie on a laptop.7. The player application makes the authorization request, using the Player Authorization API for Player

V3 on page 31.


8. Ooyala services determine that the single-use entitlement has already been used and playback is notauthorized.

SOME BEHAVIOR TO CONSIDER

Discussed below are some basic behaviors of device binding and some possible "corner cases" to takeinto consideration, including programmatic action (if any) you need to take.

• Context: The viewer has two entitlements:

1. Asset-based entitlement restricting access to a single device2. Label-based entitlement (that includes the asset in (1) using the viewer-level device restriction

The viewer has already registered the device for (2).

Behavior or Result: When the viewer tries to watch the asset on the same device, playback isauthorized but Ooyala does not re-register the device for entitlement (1).

• Context: A viewer has two entitlements:

1. Asset-based entitlement that restricts access to a single device for this asset2. Label-based entitlement (that includes the asset in (1) that uses the viewer-level device restriction

The viewer is using a new, different device that has not been bound to either entitlement.

Behavior or Result: Ooyala binds the new device randomly to one and only one of the entitlements.

• Context: Single-device entitlements created based on a label

Behavior or Result: Because this restriction will require the viewer to use the same device to watch allthe assets in that label, this usage is not recommended because it is a bad user experience.

• Context: Purchasing the same movie for two different single-device entitlements

A viewer buys a single-device movie and watches it on his T-box. He also wants to watch this on hismobile phone, so he buys the movie a second time.

Your action: The first purchase results in num_devices_to_bind = 1. With the second purchase,you need to increase the viewer's existing entitlement. You first need to delete the existing entitlementand then create a new one with num_devices_to_bind = 2. This means that you must keep trackof how many devices a viewer can register for an entitlement., as discussed in the introduction.

CONTENT PROTECTION DEVELOPER GUIDE | DEVICE REGISTRATION | 60

DEVICE REGISTRATION

Device management, if enabled in Backlot, is the automatic registration of devices in Ooyala Rights Lockerupon playback of DRM protected content. This is required for robust DRM deployment to open devices,in which users can simply share their login credentials. To enable device management in Backlot, pleasecontact your CSM.

DEVICE REGISTRATION APIWith Ooyala's device registration APIs, which are integrated with Ooyala Rights Locker, providers cancomply with content owners’ requirements to limit the number of devices associated with a single viewer. Asingle consumer account (called a "viewer") can be limited to no more than a specific number of registereddevices, after which limit has been reached, devices must be "de-registered" before other devices can beadded. Only devices registered to the viewer are able to play videos published with the device limits policy.

Note: Player V4 does not support device registration for Widevine Modular.

The device registration API comes in two forms.

1. An API for client application programs to register, delete, and update of lists of viewers' devices. Theendpoint for these API calls is player.ooyala.com. This interface is suitable for you to create aviewer self-service "portal" through which the viewers themselves can manage their own registereddevices, including creating easy-to-remember nicknames for their devices.

2. An API suitable for use by your customer support group to manage and view their viewers' specificaccounts device history and modify device rules or settings not permitted by client application APIdescribed above. The endpoint for these API calls is rl.ooyala.com. These calls must be signed byyour provider secret key, as described at Your API Credentials.

Supported Devices, Digital Rights Management (DRM) Systems, and Content

• Devices: All Ooyala premium content, DRM-supported devices

• Desktop browser and applications• Android applications• iOS applications• Connected TV applications• Xbox applications• Set-Top-Box (STB) applications

• DRM technologies:

• Adobe Access• Google Widevine Modular• Microsoft PlayReady• Apple FairPlay

• Types of Content

• Only DRM-protected assets• Ooyala-hosted assets• Remote assets• On-demand, linear, and live assets

There are two limits associated with device registration:


1. Device limits: upper limit for the number of devices associated with a consumer account.This limit is provider-wide and applies to all of the provider's assets with the publishing rulelimit_devices_per_viewer. For any one specific provider, all assets subject to device limits havethe same limit.

2. Deregistration rule: limit consumer account to deregister X devices in Y time interval. Ooyala enforcesa limit on the number of deletions that can happen in a given time period. Applies provider-wide to allassets.

For each asset, settings are required:

1. The publishing rule "Require Ooyala Player Token" is required.2. The publishing rule limit_devices_per_viewer sets whether the asset is restricted to registered

devices.

These settings can be made in the Backlot UI under Syndication Controls (which is for publishing rules),as shown below, or via the Backlot API for publishing rules.

Some other considerations:

• Ooyala does not provide an authentication service; it is assumed that your application has its ownauthentication model and service.

• There is no explicit call to register a device.

HIGH-LEVEL FLOWCHART FOR PROGRAMMING THE USER PORTAL

The logical flow of actions by the device registration application you write for the viewer self-service portalis described below.


1. After authentication is complete, the provider’s identity service needs to create an Ooyala Player Token(OPT). The OPT is passed as part of the authorization request to obtain an account_id.


2. Application requests a DRM license for the DRM-protected stream. The license request is proxied viayour authorization service to the license server; the authorization service attaches the account_idand request_id to the license request.

3. As part of the license request for the DRM-protected asset, when a user tries to play an assetpublished with a “require user entitlement” policy, the entitlements for that specific user are checkedagainst the Ooyala Rights Locker. If the asset’s policy includes device limits, Ooyala’s authorizationservice ensures that the current device is in the registered domain of devices for that user beforegranting the license. The DRM license servers generate a unique device id. The device id is encryptedand cannot be read by the client application.

4. As part of entitlement validation, Ooyala Rights Locker checks the device limits, based on theaccount_id and device_id. A successful check is necessary before a DRM license. DeviceRegistration depends on the Ooyala Player Token for secure authentication (account_id) and DRMfor robust, secure device ID.

If all entitlement checks pass, the license is cryptographically bound to the device. Device registrationwill fail if the browser privacy settings/history/cache are cleared or if the browser is uninstalled orreinstalled. If any of these events occur, the widevine and device_id cached in the browser areremoved. This could cause the device limit to be exceeded because the same device would then havea new device_id and be tracked as a new device.

5. If the device has not been registered, the provider can configure his service so that the device is auto-registered. If the user has not exceeded the device limits, auto-registration adds the device to theuser’s device domain. (The user-agent string of the device is recorded automatically.) The user isauthorized to proceed.

For the Ooyala Flash Player, when an authorization token is issued or modified, the eventauthTokenChanged is triggered. With the player message bus, you can listen for this event. For anexample, see Listening To a Message Bus Event.

At this point, you can optional automatically prompt the user for a device nickname. Of course, youruser can also add a device nickname later, either via your user portal or your customer support portal.

6. If the user’s device limit has been exceeded, the system returns an error.

The provider’s application can use APIs to retrieve error information and the user’s device nicknamesto create a user experience that appropriately communicates the device limit restriction. The providercan use APIs to create a self-service portal and/or create a customer service capability to (de-) registerdevices.

7. When authorization fails, the client needs to make a request to user Portal API as defined below to getthe reason for failure, and trigger the appropriate user experience for remedying the error.

For the case where the number of devices has been reached, the user experience for deregistering adevice can be triggered.

8. If the deregistration limit has not been reached, then the user can deregister device.

The application should try again to get a license.9. The user might have to wait for the deregistration time limit before successfully obtaining the license.10. Otherwise, the user must talk to the provider's customer support, who can use Device Registration

APIs to override restrictions.

Properties for Device RegistrationThese properties and their definitions apply to both the user portal and the customer support portal.

account_id Provider's specific users.

actor and actor_type For certain PATCH or DELETE requests, theusername of the administrator must be specified inthe request body.

../reference/player_v3_dev_listenevent.xml


auth_token An encrypted string returned to the client in theauthorization response. However, in places like adevice registration portal you would not do videoauthorization. To get the auth_token in thesecases use the embed token API and specify anadditional query parameter return_json=1to get the response {“auth_token”:“sample_auth_token”}.

device_limit The maximum number of devices that can beregistered with the viewer.

next_delete_time The next time a registered device may be deletedfrom this viewer. ISO 8601 format.

nickname A user friendly name for a device. There are norestrictions on what characters are allowed and themaximum length of a nickname is 255 characters.

pcode Provider code. For details, see Your APICredentials.

public_device_id A random string generated by Ooyala that identifiesthe device. (This is not the actual ID generated bythe Digital Rights Management (DRM) system. TheDRM device ID is never exposed.)

See the note below about how the behavior ofthe Chrome browser can affect the value of thepublic_device_id.

registration_time The time at which registration was attempted. ISO8601 format.

result Returned in the response, a specific result of anattempt to register a device. The HTTP responsecode for most of these messages is 200; be sureto check the response body for specific errormessages.

• 200: new device registered• 200: device binding failed• 200: device limit reached• 200: no device registration action• 404: device registration last result not found

user_agent The client’s user agent when the registrationattempt was made.

ABOUT GOOGLE CHROME AND DEVICE IDS

Due to restrictions imposed by the Google Chrome browser's architecture for security, your users mightexperience difficulty with multiple device IDs and device registration. There are two cases:

• A user who uses two different browsers (one of them Chrome) to register the same physical device willbe assigned two different device IDs.

• Users who reset their Adobe Access DRM licenses in Chrome will lose their device IDs. The IDs willbe regenerated the next time DRM content is accessed. Because the user thus has a new device ID,Ooyala's Device Management flow considers it a separate device.


This condition is best handled by a good design of your user portal and clear information for yourcustomer support group, allowing the user to remove the old device IDs and register the "new" ones.

Device Management API for User PortalsPart of Ooyala Player API family, these APIs can be called from either the client application itself or from auser self-service portal portal, and forms.

Note: The endpoint for these calls is player.ooyala.com.

GET REASON FOR REGISTRATION FAILURE

Use this request to get a fuller explanation of why the license request might have failed.

Note: The auth_token returned in the failed registration response must be used to get the last result. Theresponse applies only to the playback session associated with the supplied auth_token.

Device registration is tied to the issuing of the license by the DRM client, because it is the DRM client thatsupplies the required device ID. Unfortunately, if a license request fails, an Ooyala-specific error responsecannot be returned because the DRM clients require a response in a particular, non-Ooyala format.

Therefore, use this GET request to obtain more detailed information about a possible licensing/registrationfailure.

This request returns error messages if either the device limit or the entitlement limit is reached, in additionto other error conditions. The request also returns a list of previously registered devices, so the user candetermine if they are correct.

[GET]player.ooyala.com/sas/api/v1/device_management/auth_token/auth_token/last_result

Example Response

{ "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:23.0) Gecko/20100101 Firefox/23.0", "registration_time":"2013-09-09 12:41:40 -0700", "result":"device binding failed", "public_device_id":null, "devices":[ { "public_device_id":"aadf73a0-54ec-424d-9666-c70d17bc8f8b", "nickname":null, "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:23.0) Gecko/20100101 Firefox/23.0" } ]}

• 200 result : Either success or a specific error message about why the registration failed. Thefollowing are possible results:

• new device registered• device binding failed. This message is returned if the entitlement-level device limit has been

reached. The devices array contains only the device IDs that are already bound to the entitlement.• no device registration action• device limit reached

• 404 device registration last result not found


GET LIST OF REGISTERED DEVICES FOR A VIEWER

[GET]player.ooyala.com/sas/api/v1/device_management/auth_token/auth_token/devices

Response

The array devices includes the following fields for each device registered with the viewer.

{ “device_limit”:“maximum number of devices allowed”, “next_delete_time”:“The time at which the device can be deleted (ISO 8601)”, “devices”:[ { "public_device_id":“sample_device_id”, "user_agent":”sample_user_agent”, "registration_time":“time at which registered (ISO 8601)”, "nickname":“device_nickname” }, . . . ]}

UPDATE A DEVICE’S NICKNAME

[PUT]player.ooyala.com/sas/api/v1/device_management/auth_token/auth_token/devices/public_device_id{ "nickname":"someNickname"}

Responses

200 {"message": "OK"} - Request succeeded.

404 {"message": "Device Not Found"} - Returned if device with the given public_device_id was not found.

403 {"message": "Invalid Token"} - Returned if the auth_token was invalid.

DELETE DEVICES

This is checked against the provider's deletion limits.

[DELETE]player.ooyala.com/sas/api/v1/device_management/auth_token/auth_token/devices/public_device_id

Responses


404 {"message": "Device Not Found"} - Returned if device with the given public_device_id was not found.

403 {"message": "Invalid Token"} - Returned if the auth_token was invalid.

429 {"message": "Delete Limit Reached"} - Returned if deletion was not allowed because of recentattempts


Device Registration API for Customer Support PortalsPart of the Ooyala Rights Locker family of APIs, Ooyala's REST-based device registration API can be usedto construct customer support tools. The APIs are designed to be called from servers running provider'sthe administration portal that customer support uses. The APIs include the following features:

• Get history of deletes, adds, and errors of any customer specific accounts for up to a year• Override the device limit on any specific account• Update device information for any specific account• Delete devices without incrementing the delete limit.

Note: The endpoint for these calls is rl.ooyala.com.

ABOUT THE ACTOR FOR UPDATE/DELETEIn requests that rely on PUT and DELETE to update or remove settings, in addition to other properties thatmight be required for the operation, the body of the request must include the following properties, wherethe value of actor is the administrator's username:

{ . . . "actor" : "admin username" "actor_type" : "admin" . . .}

GET LIST OF REGISTERED DEVICES FOR A VIEWER

[GET]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/devices

Response

In the response, devices is an array containing the following fields for each device registered with theviewer.

{ “device_limit”:“maximum number of devices allowed”, “next_delete_time”:“time at which the device can be deleted (ISO 8601)” “devices”:[ { "public_device_id":“sample_device_id”, "user_agent":”sample_user_agent”, "registration_time":“time at which registered (ISO 8601)” "nickname":“device_nickname” }, . . . ]}


GET LAST RESULTS FOR AN ACCOUNT

The value of the results property in the response from the /last_result qualifier is a messageabout the success or failure of an account's recent attempts to register devices. This request is similarto /last_results qualifier for the user portal, except for customer support, it returns all results for allplayback sessions for the given account. (For user portals, /last_result returns information only for aspecific playback session associated with the passed-in auth_token.)

[GET]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/last_result

Example Response

The example below shows two device registrations, both successful.

[ { "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:23.0) Gecko/20100101 Firefox/23.0", "registration_time":"2013-09-09 13:15:01 -0700", "result":"new device registered", "public_device_id":"aadf73a0-54ec-424d-9666-c70d17bc8f8b" }, { "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:23.0) Gecko/20100101 Firefox/23.0", "registration_time":"2013-09-09 12:21:18 -0700", "result":"new device registered", "public_device_id":"48cf9f3f-71f6-4114-a544-a1c13d97a298"} }]

GET HISTORY OF ALL ACTIONS ON AN ACCOUNT

Account history can be used by Customer Support to diagnose problems with deleting, renaming, andadding devices to an account. The account history displays what action was taken, when it was taken, andby whom.

[GET]rl.ooyala.com/device_management/pcode/>pcode/account_id/account_id/history

Response

[ { “public_device_id”: “sample_device_id”, “user_agent”: “sample_user_agent”, “action_time”: “time at which action occurred (ISO 8601)”, “action”: “sample_action”, “nickname”: “”, "actor": “sample_actor” }, . . .]


• action_time: The time the action happened.• action: The action done which include device registration, device deletion, add device nickname.• actor: The user’s account id or admin support email if the customer support API called the action.

DELETE SINGLE DEVICE

[DELETE]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/devices/public_device_id{ "actor":"admin username" "actor_type":"admin"}

Responses

200 {"message": "OK"} - Request succeeded

404 {"message" "device does not exist"} - account_id under pcode not found

DELETE ALL DEVICES

[DELETE]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/devices{ "actor":"admin username" "actor_type":"admin"}

Responses



MODIFY DEVICE LIMIT

[PUT]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/device_limit{ "device_limit":device_limit}

Responses



GET DEVICE LIMIT

[GET]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/device_limit

Responses

{ “device_limit”:“actual limit”,}


UPDATE A DEVICE’S NICKNAME

[PUT]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/devices/public_device_id{ "nickname":"someNickname" "actor":"admin username" "actor_type":"admin"}

Responses



CONTENT PROTECTION DEVELOPER GUIDE | DIGITAL RIGHTS MANAGEMENT | 71

DIGITAL RIGHTS MANAGEMENT

Ooyala delivers premium content at the highest level of security provided by studio-approved DRMproviders - Adobe Access, Apple Fairplay, Google Widevine, and Microsoft PlayReady. This lets publishersmonetize their content on mobile devices and connected TVs, while distributors can meet their obligationsto rights holders.

Ooyala supports local packaging of VoD contents with the studio approved DRMs. For live streams,packaging will have to be facilitated by the live encoder. The process by which this is accomplished isdescribed in the section DRM Attributes for Remote Asset. Ooyala still maintains the DRM license serversfor live streams (treated as remote assets in Backlot), but the encoder is responsible for packaging andencryption.

DRM ATTRIBUTES FOR REMOTE ASSETS (INCLUDING LIVESTREAMS)

For remote assets protected by Digital Rights Management (DRM) systems, you need to associateinformation about that system.

Note: For more information about Backlot REST API commands, see the Backlot API Reference.

Note: These steps are applicable to live linear (assets not packaged by Ooyala).

Assets that are transcoded by and stored on the Ooyala system have the DRM attributes appliedautomatically, but remote assets do not pass through Ooyala transcoding and thus must be updated byyou. For example, for live encoders this has to be updated by someone configuring the encoder (such asyou or your vendor's technical support team).

For every remote asset that is protected by licenses issued from DRM systems operated by Ooyala, youneed to set some attributes pertinent to the type of DRM system in use (FairPlay Streaming, Widevine orPlayReady).

• FairPlay Streaming (FPS) requires a content key and iv. You can optionally set a lease or rentalduration.

• Widevine Modular is supported. If you are currently using Widevine Classic, please contact TechnicalSupport or your account manager to help you transition to Widevine Modular.

• PlayReady needs the license acquisition URL, content_key, and key_id (explained below).• To configure DRM with Adobe Access, contact your CSM to set up Adobe Access certificates for your

live encoders.

Note: Ooyala integration with Adobe Access DRM has been deprecated and is scheduled to bedisabled. For details and alternatives, see the OVP Release Notes.

Note: For PlayReady-protected remote assets (when drm_type is playready or playready_hls onthe request), you need to set these attributes before acquiring a license from PlayReady; otherwise, theremote asset under the protection of the DRM cannot be played.

Note: The DRM attributes used for PlayReady are key_id and content_key. The key id is an identifierassociated with the content. It can be any 16-byte value expressed in base64 or hex format. The contentkey should be a random 16-byte value that is used as the AES key to encrypt the content. This may alsobe stored in base64 or hex format. You must check if your encoder requires the key id and content key tobe in the base64 format or hex format. When you create a key for the first time, you don’t need to use aversion. In this case your content key field will be content_key and the license URL would be:

http://player.ooyala.com/sas/drm2/jqbkH9m/UPHGNsr/playready/ooyala.

http://apidocs.ooyala.com/backlot_api/index.html


Ooyala allows you to associate multiple content keys with an asset. You can do this by naming the contentkey field as content_key_version where version is a number that needs to match the version in the licenseURL. For example, if the content key field is content_key_2, then the license URL would need to end witha 2: .../playready/ooyala/version/2. You may associate multiple keys with an asset by using a differentversion number each time. See example below.

SET/REPLACE FPS ENCRYPTION KEY

Create a new FPS encryption key:

[POST] /v2/assets/asset_id/drm_attributes/fps

Response:

{ "drm_type": "fps", "fps_content_key": "base64 encoded content key", "fps_content_key_iv": "base64 encoded iv"}

The fps_content_key field contains a base64-encoded, 128-bit key that can be used for performingAES encryption on the video. The fps_content_key_iv field is a base64-encoded, 128-bit value to useas an initialization vector for encrypting the content.

Sample response:

{ "drm_type": "fps", "fps_content_key": "5HdVooYGEROm+LX2NJBDZg==", "fps_content_key_iv": "rOw7gQauk7RCGVi1aeP9QQ==" }

The first time you create a key, its value will be returned unmasked. Later on, if you create another key, thevalue of any existing key is returned masked.

To associate an existing FPS encryption key with an asset:

[PATCH] /v2/assets/asset_id/drm_attributes/fps

If you have multiple keys associated with the asset, include the version for this key in the body. Forexample, if this is the third key used for this asset, you will send the following JSON body with a key of2QCEebexS0G8+3jP/pM7TA== and a version number of 3:

{ "fps_content_key_3” : "2QCEebexS0G8+3jP/pM7TA==" }

The response indicates that key 3 was stored successfully and with the key value masked:

{ "fps_content_key_3": "*****", "drm_type": "fps"}

To create versioned keys, use the POST route.

[POST] /v2/assets/:asset_id/drm_attributes/fps?version=1


Sample response:

{ "fps_content_key" : "****", "fps_content_key_1" : "12s213" , "fps_content_key_iv_1" : "daiosd" }

PACKAGING WIDEVINE MODULAR MEDIA

For serving VOD content transcoded by Ooyala, the provider attributes needed are:

• widevine_aes_key - Just press enter after writing the attribute name and the default value will beautomatically populated for you.

• widevine_aes_iv - Just press enter after writing the attribute name and the default value will beautomatically populated for you.

• widevine_portal_id - Set the value to ooyala.

For serving live content not transcoded by Ooyala, the provider attributes needed are:

• widevine_aes_key_live - It is recommended that the customer get their own Widevine credentialsvia the Certified Widevine Certification Program (CWIP). Press enter after writing the attribute nameand the default value will be automatically populated for you.

• widevine_aes_iv_live - The customer might have their own iv that you will need to get from them.Press enter after writing the attribute name and the default value will be automatically populated for you.

• widevine_portal_id_live - If the customer is using their own key and iv, then get this value fromthe customer, otherwise set to ooyala.

SET/REPLACE PLAYREADY ATTRIBUTES FOR DRM PROTECTION OF REMOTE ASSET

If you need to use a non-Ooyala system to generate the content key, you may use the following route forPlayReady Smooth to associate the key and key id with the Ooyala asset.

Note: The API route you need to use is different when managing attributes for PlayReady HLS andPlayReady Smooth. For PlayReady Smooth use the endpoint /v2/assets/asset_id/drm_attributes/playready, as shown below. For PlayReady HLS use the endpoint /v2/assets/asset_id/drm_attributes/playready_hls.

[PATCH]/v2/assets/asset_id/drm_attributes/playready{ "key_id":"value1" "content_key":"value2"}

If you have multiple keys associated with the asset, include the version for this key in the body. Forexample, if this is the second key used for this asset, you will send the following body:

{ "key_id":"value1" "content_key_1":"value2"}

GENERATING A PLAYREADY KEY_ID AND CONTENT_KEY

This route generates a random key id and content key for the asset and associates them with the video.You do not need to call the PATCH route described above to store these attributes in Ooyala's datastoreif you get your key id and content key using this route. The JSON response contains the key id in base64


as well as guid/hex formats. The response also contains the content_key in base64 encoded format.drm_type can be specified as playready or playready_hls.

Note: This route will only work over https. API calls made over plain http will be rejected because theencryption key is sensitive information.

[POST] /v2/assets/asset_id/drm_attributes/drm_type

This will return:

{ "key_id":"base64 encoded key id", "key_id_guid":"hex version of the key id", "drm_type":"playready", "content_key":"base64 encoded content key"}

To create another key for the same asset, you can call the same route with the version set to any number.

[POST] /v2/assets/asset_id/drm_attributes/drm_type?version=2

This will return:

{ "key_id":"base64 encoded key id", "key_id_guid":"hex version of the key id", "drm_type":"playready", "content_key_2":"base64 encoded content key", "content_key":"***"}

Notice the old content_key is not returned. Its value is masked with ***. This is for security reasons.

GET DRM ATTRIBUTES

[GET] /v2/assets/asset_id/drm_attributes/drm_type

LICENSE ACQUISITION URL

You need to put the license acquisition URL into the encoder. If you are unable to do so, your CSM canwork with you to get this value configured in the encoder. Ooyala stores the license acquisition URL inOoyala systems.

https://player.ooyala.com/sas/drm2/pcode/asset_id/playready/ooyalahttps://player.ooyala.com/sas/drm2/pcode/asset_id/playready_hls/ooyala

EXAMPLE

This example creates DRM attributes for the IzNnoCi9B2rtWs asset for a live encoder. The licenseacquisition URL for this asset is as follows:

https://player.ooyala.com/sas/drm2/IzNnoCi9B2rtWs/asset_id/playready/ooyala


Backlot returns a response similar to the following:

{ "content_key":"*****", "drm_type":"playready", "key_id":"1234"}

Note:

Try out the code samples using your account credentials in the Ooyala Scratchpad. For information aboutusing the Scratchpad, see Practice Making Requests with the Scratchpad. To launch the scratchpad, go toOoyala API Scratchpad.

PROPERTIES

The following table describes the properties you need to set for each DRM type.

drm_type Property Description

fps fps_content_key_version The FairPlay Streaming identifierfor the asset.

playready key_id The key_id is an identifierassociated with the content. It canbe any 16-byte value expressedin base64 or hex format.

Type: String

Default: None

Example in base64 - V/YqH723UV48kjRlUzyqww==

Example in hex -1f2af657b7bd5e513c923465533caac3

playready content_key_version The PlayReady content key. Theversion of the parameter nameis an integer that matches theversion in the license acquisitionURL for the specific asset.

For example, if the licenseacquisition URL is:

https://player.ooyala.com/sas/drm2/jqbkH9m/UPHGNsr/playready/ooyala/version/3

Then the correspondingparameter name iscontent_key_3.

Type: String

Default: None

Example in base64 - V/YqH723UV48kjRlUzyqww==

https://api.ooyala.com/docs/api_scratchpad


drm_type Property Description

Example in hex -1f2af657b7bd5e513c923465533caac3

widevine widevine_modular_enabled When creating a remote assetthat has Widevine modularDRM, the movie attributewidevine_modular_enabledmust be set to 1. This movieattribute should not be added ifthe asset does not have Widevinemodular DRM.

PARAMETERS

The following table describes the parameters of the routes.


asset_id The unique identifier for an asset.

Type: String

Yes

pcode Your provider code. Yes

version The number identifying theversion to use if multiple versionsexist.

Type: Int

No

APPLE FAIRPLAYThe Ooyala Player API for Apple FairPlay provides server-side support for Apple's FairPlay Streaming(FPS) by processing an FPS key request and returning a key response (CKC). Once you send your FPScredentials to Ooyala, at runtime your asset gets its CKC using Player API routes.

Note: Apple FairPlay Streaming is supported in Mobile SDK for iOS v4.13.0, see Mobile SDK for iOS.

INFORMATION REQUIRED FOR KEY RETRIEVAL DURING PLAYBACK

You must request a deployment package from Apple to use Fairplay Streaming (FPS). This requires you tohave an Apple developer account belonging to your organization. See https://developer.apple.com/support/enrollment on how to get an Apple developer account. After you establish an Apple developer account, youcan request an FPS deployment package from this page https://developer.apple.com/streaming/fps.

After you obtain a deployment package from Apple, send these items to Ooyala to use Ooyala's server forFPS key retrieval during playback.

1. Your FPS application secret.2. Your FPS RSA private key in PEM (Privacy-enhanced Electronic Mail) format.3. Your FPS public key certificate in DER (Distinguished Encoding Rules) format.

Items 1 and 2 are confidential and must not be sent unencrypted via email or text. You must use PGPencryption to send the FPS application secret and FPS RSA private key to Ooyala. See https://ssd.eff.org/en/module/how-use-pgp-mac-os-x.


PLAYER API

The https://player.ooyala.com route is used for FPS support during playback.

To get your public certificate use the following route using your provider code as pcode:

[GET] /sas/fps/pcode/certificate

This API call needs to be signed in the same way as the calls to the Backlot API. Signing is explained atGeneral Algorithm for Signing Requests.

The response is JSON with the following structure:

{ "certificate" : "URL-safe base64 encoded certificate" }

If the request succeeds, the response status 200 is returned.

Upon the decoding of the URL-safe base64 decoding, the value of the certificate field will be yourpublic certificate in DER format. If an error occurs, the response will be the following JSON:

"error" : "error message"

The error message will be a specific reason why the request failed.

To request a CKC (Content Key Context):

POST /sas/fps/pcode/key

The body of the POST request must be JSON with the fields:

{ "asset_id" : "key id from manifest file", "spc" : "base64 encoded spc", "auth_token" : "auth token returned during authorization request"}

The m3u8 manifest file will have the following tags:

#EXT-X-KEY:METHOD=SAMPLE-AES,URI="skd://key65",KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1"

The asset_id is the portion after skd:// in the URI tag. In this case it is key65.

The response is JSON with the following structure:

{ "ckc" : "url safe base64 encoded ckc" }

If the request is successful, the status code 200 is returned.

If the request fails, a non-200 status code is returned.

{ "error": "error message" }

The error message will be a specific reason why the request failed.


PACKAGING

If you are also doing your own Fairplay video packaging, please see the following page for the setup youwill need DRM Attributes for Remote Assets (Including Live Streams) on page 71. You also need tomake sure that the value of the asset_id field in the m3u8 manifest files is set to the embed code for thatasset.

FIELDS

The following table describes the parameters of the routes.


pcode The provider code for youraccount.

Yes

asset_id The asset_id obtained from them3u8 manifest file for the asset.In the m3u8 manifest file theasset_id is the portion after skd://in the URI tag.

Yes

spc The SPC (Server PlaybackContext) generated by your app.The SPC must be generatedaccording to the specificationpublished by Apple. The SPCmust be URL-safe base64encoded. Making a base64encoded value URL safe involvessubstituting + with - and / with_. See more about this herehttps://en.wikipedia.org/wiki/Base64#URL_applications.

Yes

auth_token This is the token returned byOoyala’s playback AuthorizationAPI. The Authorization API isused by Ooyala's players toget the URL pointing to thecontent. The Authorization API isdescribed in Player AuthorizationAPI for Player V3 (Deprecated).This parameter is required only ifthe asset being played requiresthe Ooyala Player Token (OPT)restriction. Because FPS is usedfor premium content, you shoulduse OPT for those assets.

No

CONFIGURING AN IOS CLIENT TO PLAY FAIRPLAY CONTENT

To decrypt and play FairPlay content, your code must assign an OOEmbeddedSecureURLGeneratorobject to the OOOptions object used by the OOOoyalaPlayer.

1. Create an OOOptions object.


2. Create an OOEmbeddedSecureURLGenerator object and assign it to theOOOptions.secureURLGenerator property. The OOEmbeddedSecureURLGenerator objectcontains the API Key and secret generated on the server.

3. Pass the OOOptions object to the OOOoyalaPlayer object.

For example, the following code assigns the created OOEmbeddedSecureURLGenerator object to theOOOptions.secureURLGenerator property:

OOOptions *options = [OOOptions new]; options.secureURLGenerator = [ [OOEmbeddedSecureURLGenerator alloc] initWithAPIKey:self.apiKey secret:self.secret ];

// Create Ooyala ViewController, with self as the embed token generator OOOoyalaPlayer *player = [ [OOOoyalaPlayer alloc] initWithPcode:self.pcode domain:[ [OOPlayerDomain alloc] initWithString:self.playerDomain ] options:options ];

Note: For production environments, the API Key and Secret must be generated on the server anddynamically assigned to the fields contained in the OOEmbeddedSecureURLGenerator object. Theymust not be stored in your code as static values.

For a complete example, see the Content Protection Sample App.

WIDEVINE MODULAR CONTENT PROTECTIONOoyala provides support for Widevine Modular to meet the content protection requirements for high-qualitycontent online in on-demand and live streaming formats. Widevine’s multi-platform DRM provides thecapability to license, securely distribute and protect playback of multimedia content on any consumerdevice. Content owners and digital media providers can use Widevine’s solutions to ensure revenuegenerating services keep flowing to whatever device consumers desire.

Note: If you are currently using Widevine Classic, please contact Technical Support or your accountmanager to help you transition to Widevine Modular.

Note: Ooyala integration with Widevine Classic DRM has been deprecated and is scheduled to bedisabled. For details and alternatives, see the OVP Release Notes.

To give you the capacity to protect your content using Ooyala and Widevine, you need to understand howWidevine works and how to use Widevine with your Android or Connected TV device. This documentdescribes how to do this.

Widevine Modular is part of a set of comprehensive content protection features that work together toprovide you with the ability to secure your content. These features include:

• User Authentication through token-based options such as the Ooyala Player Token. For informationabout setting up and using this feature, see Ooyala Player Token on page 12.

• Content Authorization through mechanisms such as Widevine. Information about Widevine is providedin this document.

https://github.com/ooyala/ios-sample-apps/blob/stable/ContentProtectionSampleApp/ContentProtectionSampleApp/Players/FairplayPlayerViewController.m


• Authorization API which is a mechanism that handles all authorization requests. For more informationabout the Authorization API, see Player Authorization API for Player V4 on page 35.

The content protection that Ooyala offers work standalone or in combination to provide multiple levelsof content protection. Ooyala enables you to combine these features to create your content protectionstrategy. To learn about additional content protection features (such as Adobe Pass), contact Sales, yourCustomer Success Manager, or Technical Support.

SUPPORTED PLATFORMS AND FORMATSIf you want to have content that is DRM-protected with Widevine, you need to use the supported platformsformats appropriate for Android Apps, and Connected TVs.

Platform Supported Formats Notes

Android 4.3+ MPEG-DASH CENC

ConnectedTVs MPEG-DASH CENC

Mozilla Firefox 47+ MPEG-DASH CENC

OOYALA AND WIDEVINE DRM WORKFLOW

Customers who want Widevine need to work with Ooyala Customer Success Managers or professionalservices to enable Widevine Modular support. When you use Ooyala’s Widevine server, the licenses existin the Widevine cloud.

With the implementation of Widevine DRM, each content viewer needs an individual license as the contentis encrypted and is useless without license. Widevine does not perform the encryption, content from theCDN is already encrypted. Widevine just provides a secure cloud for license key storage and retrieval.

If you want to integrate with Widevine, you need to understand how securing your content works with thevarious parts of the Ooyala content protection features. The following diagram illustrates how Widevineis related to the Ooyala Player Token (an optional but recommended user authentication feature) and theOoyala Authorization API that handles the user authentication requests.

Widevine Content Protection Workflow


The following table describes the workflow steps for using Widevine for content protection.

Step Action Responsible Party AdditionalDocumentation

1. The video player App, authenticates the useragainst the content provider.

App developers andcontent provider’sservices

Ooyala Player Token onpage 12

2. The content provider provides an OoyalaPlayer Token to the app that indicates theauthentication status of the user.


Ooyala Player Token onpage 12

3. The video app makes an authorization requestto Ooyala that includes the Ooyala PlayerToken.

App developers Ooyala Player Tokenon page 12 and PlayerAuthorization API forPlayer V4 on page 35

4. Ooyala's authorization request returns astream url and the authorization cookie.

App developers Player Authorization APIfor Player V4 on page 35

5. Device native playback components willcontact Ooyala for DRM licenses.

Ooyala

6. Ooyala provides the license to playback DRMcontent.

Ooyala


USING WIDEVINE WITH OOYALA SDK-BASED APPSTo use Widevine with our Android player, you need to download and use our native SDKs to createthe client-side pages. To download the Ooyala Android SDK, go to Ooyala Downloads. To learn aboutimplementing Android, see Mobile SDK for Android . That’s all you need, as once you have the WidevineModular feature enabled, the Ooyala SDK-based apps should work seamlessly with Widevine.

USING WIDEVINE WITH CONNECTED TVSIf you want to use Widevine with connected TVs, you need to:

1. Implement Widevine Modular in accordance with the device specific SDKs. You pre-configure yourdevice SDK and Widevine setup according to the SDK instructions.

2. Initialize Widevine and the device SDK in the SDK-specific language (this will vary from device todevice). Set up your app in accordance with the applicable platform programming guide.

3. You will make a call to the Authorization API (this is a JSON RESTful API call).4. You will make the call to get the Widevine URL or stream data.5. You need to map the elements of the retrieved URL to the corresponding values of the Widevine fields.

Plug in the values described below.

For this segment... Provide...

video url the stream URL

portal, provider, or owner id ooyala

device id optional, unique identifier for the device, yougenerate the id

DEVICE REGISTRATION

When using Widevine Modular, the device_id that is cached in the browser might get removed in thefollowing situations:

1. clearing the browser privacy settings/history/cache2. uninstalling or reinstalling the browser

Device registration will fail if the device limit is exceeded because the same device would then have a newdevice_id and be tracked as a new device, see Device Registration API on page 60.

PLAYREADY CONTENT PROTECTIONOoyala provides support for PlayReady to meet the content protection requirements for high-qualitycontent online in on-demand and live streaming formats.

PlayReady is a DRM technology by Microsoft used to protect premium content from being viewed withouta valid license. It is used in conjunction with Microsoft’s Smooth Streaming protocol. Ooyala provides a setof comprehensive content protection features that work together to provide you with the ability to secureyour content. We integrate with additional content protection technologies alongside Microsoft PlayReadyto provide a full range of content security solutions. These content protection features include:

• Content Authorization through mechanisms such as our integration with PlayReady. Informationabout PlayReady is provided in this document.

• User Authentication through token-based options such as the Ooyala Secure Player Token. Forinformation about setting up and using this feature, see the Ooyala Secure Player Token Guide.

http://help.ooyala.com/downloads


• Authorization API which is a mechanism that handles all authorization requests. For more informationabout the Authorization API, see the Authorization API Guide.

To give you the capacity to protect your content using your own custom player with Ooyala services andPlayReady content protection, you need to have a PlayReady library for your platform and/or understandhow to use the Microsoft PlayReady SDK. This document describes how our systems work with PlayReadyand is designed for software developers who want to create a custom player and use Ooyala services andthe PlayReady content protection option.

SUPPORTED PLATFORMS

If you want to have content that is DRM-protected with PlayReady, you need to use the supportedplatform's formats appropriate for Microsoft PlayReady.

Platform Streaming Formats

Microsoft XBOX Smooth Streaming

Chromecast Smooth Streaming

Roku Smooth Streaming

Fire TV Smooth Streaming

Other Connected TV (CTV) and similar devices To get a list of the requirements necessary for yourCTV device to use PlayReady, check with youraccount manager.

PlayReady WorkflowThe PlayReady Workflow describes the process needed to implement and initialize PlayReady contentprotection.

If you want to use PlayReady, you need to:

• Implement PlayReady in accordance with the device specific SDKs that you are using to create yourcustom players. You pre-configure your device SDK and PlayReady set up according to the SDKinstructions.

• Initialize PlayReady and the device SDK in the SDK-specific language (this will vary from device todevice). Set up your app in accordance with the applicable platform programming guide.

• You will make a call the Authorization API (this is a JSON RESTFUL API call).• You will make a PlayReady license request that included the auth token from the authorization API.

To use PlayReady for DRM-protection of Smooth streaming, work with your Ooyala Customer SuccessManager or professional services to enable PlayReady support. With the implementation of PlayReadyDRM, each content viewer needs an individual license as the content is encrypted and is useless without alicense.

The following two diagrams illustrate how PlayReady is related to the Ooyala Player Token (an optionalbut recommended user authentication feature) and the Ooyala Authorization API that handles the userauthentication requests.

The following diagram shows how the player authenticates the user using the Ooyala Player Token.


The following diagram shows the continuation of the workflow showing the fetching of the PlayReadylicense.

The following table describes in greater detail the workflow steps, illustrated in the prior diagrams, that arenecessary for using PlayReady for content protection. Your app needs to perform the following workflow:

Step Activity Responsible Party AdditionalDocumentation

1 The video player app, authenticates the useragainst the content provider and requests anOoyala Player Token (OPT).


Ooyala Player TokenGuide

2 The content (identity) provider supplies anOoyala Player Token to the video player appthat indicates the authentication status of theuser.


Ooyala Player TokenGuide

3 The video player app makes an authorizationrequest to Ooyala that includes two key piecesof data:

• the embed code.• the Ooyala Player Token.

App developers Ooyala Player TokenGuide and AuthorizationAPI Guide

4 The video manifest is fetched using the streamURL. The response contains the stream URLfor the video (this will be the manifest whenusing smooth streaming).

App developers Authorization API Guide

5 The PlayReady license is requested usingthe acquisition URL from the manifest. Theauth_token must be included within the licenserequest.

App developers

6 Ooyala provides the license to playback DRMcontent.

Ooyala


PlayReady ExampleA PlayReady reference implementation shows example code needed to implement and initializePlayReady content protection.

To assist you in creating the code for PlayReady DRM, Ooyala provides a reference implementation in azip file that contains sample code in Silverlight. The sample contained in the PlayReady_SRC.zip filedemonstrates one way of making a license request. You can get the PlayReady_SRC.zip file from youraccount manger. When creating the code necessary to make the appropriate authorization requests, at ahigh-level, you need to:

• Make an authorization request to Ooyala (see step 3 in the PlayReady Workflow table).• Parse the stream url and auth_token from the auth_response.• Insert the auth_token into the PlayReady license request and then play the smooth stream (see step 5

in the previous PlayReady Workflow table).

ANATOMY OF AN AUTHORIZATION TOKEN

In step 3 of the PlayReady Workflow, an authorization request is made. When this authorization requestincludes a valid Ooyala Player Token, the response will include an auth_token. This authorization token willlook something like the following:

```{"authorization_data"=> ...,"debug_data"=>...,"auth_token" => "foo","signature"=> ...}

```

The auth_token needs to be included in the PlayReady license request as indicated in step 5 of thePlayReady Workflow.

USING THE SMOOTH STREAM CLIENT SDK

You can use PlayReady with the Smooth Stream Client SDK, which you can download at (http://www.iis.net/downloads/microsoft/smooth-streaming-client-sdk). A sample is available from your CustomerSuccess Manager that illustrates how to use the IIS (Smooth Stream Client SDK) to playback smoothstreams and make the license request. The following excerpt from the sample (written in C#), shows:

• how the stream url is obtained from the authorization request.• when the authorization response contains the auth_token, how to insert the auth_token into the license

request.

// Make an authorization request first, then get the manifest and auth token from the response. WebClient client = new WebClient(); client.DownloadStringCompleted += (target, eventData) => { try { OutputText.Text += "Authorization response received\n"; JsonObject response = (JsonObject)JsonObject.Load(new StringReader(eventData.Result));

// The stream url is obtained from the authz response.

http://www.iis.net/downloads/microsoft/smooth-streaming-client-sdk

http://www.iis.net/downloads/microsoft/smooth-streaming-client-sdk


Byte[] streamUrlArray = Convert.FromBase64String(((JsonObject) response["authorization_data"]).Values.First()["streams"][0]["url"]["data"]); String streamUrl = Encoding.UTF8.GetString(streamUrlArray, 0, streamUrlArray.Length);

// If the authz response includes an auth token, insert it into the license request. if(response.ContainsKey("auth_token")) { SmoothPlayer.LicenseAcquirer.ChallengeCustomData = "auth_token=" + response["auth_token"]; } SmoothPlayer.AutoPlay = true; SmoothPlayer.SmoothStreamingSource = new Uri(streamUrl); } catch (Exception exception) { OutputText.Text += "Error: " + exception.ToString() + "\n"; } };

// For the purpose of this sample, the authorization url is set by the user. See Authorization API docs for how to// construct the Authorization request, and Ooyala Player Tokens. OutputText.Text += "Making authorization Request\n"; client.DownloadStringAsync(new Uri(UrlText.Text)); }

USING OTHER CLIENT LIBRARIES

For other types of client libraries the auth_token must be included in the license request as CustomData inthe: '/soap:Envelop/soap:Body/AquireLicense/challenge/Challenge/LA/CustomData'The following example show how to include the auth_token in the license request for other clientlibraries:

```<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <AcquireLicense xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols"> <challenge> <Challenge xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols/messages"> <LA xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols" Id="SignedData" xml:space="preserve"> ... <CustomData>auth_token=foo</CustomData> </LA> </Challenge> </challenge> </AcquireLicense> </soap:Body></soap:Envelope> ```


ADOBE ACCESS DRM (DEPRECATED)Adobe Access DRM has been deprecated.

Note: Ooyala integration with Adobe Access DRM has been deprecated and is scheduled to be disabled.For details and alternatives, see the OVP Release Notes.

INTRODUCTION

Ooyala supports Adobe® Access™ DRM to deliver and protect premium video to Ooyala Flash-basedplayers across desktop devices. With Adobe Access DRM, publishers, broadcasters, and content ownerscan deliver video to a variety of desktop devices with the confidence of secure DRM delivery. Ooyalaincludes Adobe Access as one of a set of comprehensive content protection features that work together toprovide you with the ability to secure your premium content. The Adobe Access DRM solution allows you todeliver premium video content with persistent content protection for playback on desktop Flash players.

The Ooyala Transcoding Services (OTS) encodes and packages/encrypts video fragments prior todistribution. The DRM regime also employs configurable DRM policies to ensure your video contentis protected with restrictions in accordance to your security policies and compliance rules. Ooyalaalso integrates with supplemental content protection technologies from User Authorization throughauthentication mechanisms such as our integration with Adobe Pass. You also have the option of addingOoyala Secure Player Token (OPT). For detailed information about setting up and using this feature, seethe Ooyala Player Token on page 12.

SUPPORTED PLATFORMS AND FORMATS

• Flash Player for Web: For details, see Player V3 Functional Support Across Environments(Deprecated).

• Desktops: Windows®, Mac OS® or Linux operating systems. For details, see Player V3 Platform andBrowser Support (Deprecated) and Player V3 System Requirements by Platform (Deprecated).

• Streaming protocol: HTTP Dynamic Streaming.

OOYALA AND ADOBE ACCESS DRM WORKFLOW

For an overview of the content distribution workflow in Adobe Access, you can read the Adobe® LearnFlash Access Overview topic. At a high level, the general content workflow is as follows:

1. The video file is encrypted with a unique content encryption key and packaged locally at Ooyala usingTranscoding Services.

2. During playback, if client is authorized, there is a license acquisition request to the license server.3. The license server decrypts the license request and then assigns a policy to the license (for instance,

the video cannot be played if the device is connected to an external device) and returns the license tothe client.

4. If the client meets the policy requirements, the video starts playing.

CONFIGURING ADOBE ACCESS

Using Adobe Access to set up your provider/assets with Adobe Access DRM is very straightforward. Youjust need to have Adobe Access enabled for your account. Work with your Ooyala Customer SuccessManager or Customer Portal to enable Adobe Access for your account.

http://www.adobe.com/support/adobeaccess/pdfs/server/AdobeAccess_4_Overview.pdf

http://www.adobe.com/support/adobeaccess/pdfs/server/AdobeAccess_4_Overview.pdf

http://help.ooyala.com/contact


You also have the option of enabling the Ooyala Player Token (OPT) authentication with Adobe AccessDRM. For more information about using OPT, see the Ooyala Player Token documentation.

CONFIGURABLE DRMDigital Rights Management (DRM) enables you to control how viewers consume and access your highvalue content through DRM policies. DRM policies can be set at the account or asset level.

Ooyala DRM policies support these DRM technologies:

• Adobe Access, which is used to secure Flash playback.• Widevine Modular, which is used for mobile devices.• PlayReady is used when specifically set up for your account.• FairPlay Streaming is Apple's DRM for content protection.

With configurable DRM, your Customer Success Manager or Ooyala Support creates multiple DRMpolicies. Once enabled, you can assign any policy to any asset after ingestion. Then, you can change thepolicy for an asset at any time. For example, you might have new content to which you want to assign yourmost stringent DRM policy. After the content is no longer new and in high demand, you might choose toloosen the DRM protection by using a less restrictive policy.

In general, Ooyala gives you the ability to choose from multiple pre-defined policies. These policies aredetermined at license issuance time and can include policies issued on a package or more commonlyissued as policies enforced on output controls (such as enforcing no playback if HDCP is not present). Ingeneral these types of output control policies take the form:

1. no policy.2. use if available.3. required.4. no output.

The following is an example of a DRM policy:

{ { "id":"86ff97ae7c81495eacbd9a01feff0e10", "name":"HD Policy", "playready_policy":{ "analog_video_extension_guid":"guid_#", "expiration_date":"60", "compressed_digital_video":"500", "analog_video":"150", "uncompressed_digital_video":"300" }, "flashaccess_policy":{ "analog_output_protection":"use_if_available_all", "digital_output_protection":"required", "minimum_security_level":10000 }, "widevine_modular_policy":{ "can_play":true, "can persist":true, "can_renew":true, "rental_duration_seconds":0, "playback_duration_seconds":0, "license_duration_seconds":0, "renewal_recovery_duration_seconds":0, "renewal_server_url":"", "renewal_delay_seconds":0,


"renewal_retry_interval_seconds":0, "renew_with_usage":true }, "fairplay_policy":{ "airplay":true, "adapter":true } }}

Assigning DRM PoliciesOnce configured, you can assign a DRM policy at the account or asset level.

An Ooyala Customer Success Manager or Support Engineer must set up your policies before you canassign them to assets.

To assign a DRM policy to an asset:

1. Get the ID for the DRM policy.

[GET]/v2/drm_policies

Backlot returns a response similar to the following.

{ "items":[ 86ff97ae7c81495eacbd9a01feff0f21, 43ff97ae7c81495eacbd9a01feee0f38 ]}

Note:

Try out the code samples using your account credentials in the Ooyala Scratchpad. For informationabout using the Scratchpad, see Practice Making Requests with the Scratchpad. To launch thescratchpad, go to Ooyala API Scratchpad.

2. Assign the DRM policy to an asset.

[PUT] /v2/assets/IzNnllMjphu2XF3_UgPROoCi9B2rtWs/drm_policy/86ff97ae7c81495eacbd9a01feff0f21

Backlot returns a 200 response.

Note:


3. If you want to make a DRM policy the default for your account, you can assign the policy at the accountlevel.

[PUT] /v2/provider_drm_policy/86ff97ae7c81495eacbd9a01feff0f21


Note:






Deleting DRM PoliciesYou can quickly and easily remove DRM policies from an asset or your account.

To delete a DRM policy from an asset:

Note: If you want to replace an asset's DRM policy, simply assign a new policy to the asset.

1. Remove the DRM policy from an asset. For example:

[DELETE]/v2/assets/IzNnllMjphu2XF3_UgPROoCi9B2rtWs/drm_policy


Note:


2. If you want to make a DRM policy the default for your account, you can assign the policy at the accountlevel. For example:

[DELETE]/v2/provider_drm_policy


Note:




content protection developer guide

Documents