CONTENT PROTECTION DEVELOPER GUIDE

Transcription

1 CONTENT PROTECTION DEVELOPER GUIDE

2 CONTENTS CONTENT PROTECTION OVERVIEW 5 Protecting Your Content 5 Gauging The Necessary Protection 5 Survey of Content Protection Technology 6 Protected Streams 7 Playback Authorization, Including Token-based Authentication and Restrictions 8 Digital Rights Management (DRM) Systems 9 Content Protection Options By Device 9 Warning About Web Browser Third-party Cookies 10 AUTHENTICATION 12 Ooyala Player Token 12 Warning About Web Browser Third-party Cookies 17 Controlling Playback with the Ooyala Player Token 17 Ooyala Player Token Expiration 18 Setting the Ooyala Player Token 19 Using Ooyala Player Token with Ooyala ios and Android SDKs 20 Akamai Secure Token 22 Integrating Adobe Pass with Ooyala Player 23 Adobe Pass Integration Reference 24 AUTHORIZATION 29 Player Authorization API 29 Enforcing Per-Viewer Limits on Concurrent Streams 33 ACCESS CONTROL 39 RIGHTS MANAGEMENT 40 Rights Locker 40 Prerequisites to Rights Locker 40 Key Concepts 41 Your Users, Your Accounts: Security 42 How Authorization Works 42 Backlot Setup 42 Extended Example of Rights Locker 43 Binding Viewer Devices to Entitlements 44 DEVICE REGISTRATION 48 Device Registration API 48 Properties for Device Registration 51 Device Management API for User Portals 53 Device Registration API for Customer Support Portals 55 CONTENT PROTECTION DEVELOPER GUIDE TOC 2 [email protected] OOYALA

3 DIGITAL RIGHTS MANAGEMENT 59 DRM Attributes for Remote Assets (Including Live Streams) 59 Widevine Content Protection 63 PlayReady Content Protection 66 PlayReady Workflow 66 PlayReady Example 68 Adobe Access 70 Configurable DRM 71 Assigning DRM Policies 72 Deleting DRM Policies 73 CONTENT PROTECTION DEVELOPER GUIDE TOC 3 [email protected] OOYALA

4 COPYRIGHT NOTICE Copyright Ooyala Ooyala, Backlot, Ooyala Actionable Analytics, the Ooyala logo, and other Ooyala logos and product and service names are trademarks of Ooyala, Inc. ( Ooyala Marks ). Company agrees not to remove any Ooyala Marks that are contained within and/or affixed to the Services as provided to Company. Except with respect to the foregoing, Company agrees not to display or use in any manner the Ooyala Marks without Ooyala s prior written permission. All contents of the Ooyala website and Services are: Copyright 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: All other trademarks are the property of their respective companies. This content was last updated on CONTENT PROTECTION DEVELOPER GUIDE COPYRIGHT NOTICE 4

5 CONTENT PROTECTION OVERVIEW Content Protection spans a range of strategies and technologies that are critical to the security of proprietary content. Individual content owners need various levels of online video protection, and in some instances 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 of devices. Content providers should understand the technologies and capabilities needed to protect their valuable video assets, and they must consider security options that offer geographic, time-based or user-based restrictions. Publishers must focus on giving their users the highest quality video possible while also enforcing their business models. Protecting content is not about keeping people out. Instead, it s a methodology 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 has necessarily become a complex art, and matching the right protection strategy to the nature of the content is vital. A single approach is unlikely to work for premium VOD, linear TV streams, and pay-per-view live events, for example. Content protection is not one-size-fits-all. Matching the right protection strategy to each type of content is essential. Protection needs are based on the value of the publisher s content, and matching the right protection 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 CONTENT To 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 itself 2. The suitability and cost of available protection technologies GAUGING THE NECESSARY PROTECTION The 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 on smartphones to Hollywood blockbusters. Here are a few questions to consider. Your company might have other 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? CONTENT PROTECTION DEVELOPER GUIDE CONTENT PROTECTION OVERVIEW 5

6 The table below ranks revenue models and the types of associated content in order of increasing value. The requirements for content protection increase as content value increases. Revenue model Anonymous viewers, ad-funded Authenticated viewers, ad funded Subscription Transaction (rental or electronic sell-through) Examples of Content Type Short-form content, video clips Longer form content, live video High-value content 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 costly protection for less valuable content. SURVEY OF CONTENT PROTECTION TECHNOLOGY The 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 streams 2. Playback authorization, including token-based authentication 3. Digital Rights Management (DRM) systems PROTECTED STREAMS There are several technologies that secure the actual stream of data to your customers. CONTENT PROTECTION DEVELOPER GUIDE CONTENT PROTECTION OVERVIEW 6

7 Streaming protocols in general have encryption or other protections designed into them. See the details in 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 on Concurrent Streams on page 8. PLAYBACK AUTHORIZATION Playback authorization (a general term to cover various technologies) can be an additional security layer on top of protected streaming. Among these technologies are: 1. Token-based authentication. Required for RTMPE and ensures that encrypted content cannot be downloaded until the client has been verified and prevents content from being played in a non-ooyala player. There are several kinds of token-based systems: User-authentication tokens, like the Ooyala Playback Token detailed in Ooyala Player Token on page 12. CDN tokens, like Akamai Token-based Authentication. See Akamai Secure Token on page Distribution systems, like Widevine. See Widevine Content Protection on page 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 proxy controls, and more. Ooyala's publishing rules are detailed in developers/concepts/chapter_publishing_rules.html. Protected Streams There 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 can monetize their video with ads right in the stream. This provides an additional level of protection on top of playback authorization. Technology Description Comments RTMPE Encrypted HTTP Live Streaming (HLS) RTMPE (Real Time Messaging Protocol, encrypted) encrypts content on-the-fly using secure sockets layer (SSL) for delivery to Flash devices. To protect content on ios (Apple's mobile operating system) and HTML5-based devices, Ooyala uses HTTP Live Streaming (HLS) content protection. Content is transcoded and each segment of each stream is AES-128 encrypted with a randomly generated content encryption key. CONTENT PROTECTION DEVELOPER GUIDE CONTENT PROTECTION OVERVIEW 7

8 Technology Description Comments Encrypted HTTP Dynamic Streaming (HDS) Adobe s version of HTTP streaming is a natural evolution for customers who are using RTMP/E today but want the caching benefits of HTTP. Not yet supported To implement these protections, you do not need to do anything. Ooyala provides this protection depending on the type of target devices. LIMITS ON CONCURRENT STREAMS Another kind of stream-related protection deals with limiting the number of concurrent streams for a viewer to protect against theft and ensure revenue. Note: If you need to set concurrent stream limits for your Ooyala provider account, contact your Ooyala Customer Success Manager. More details on working with concurrent stream limits is in Enforcing Per-Viewer Limits on Concurrent Streams on page 33. Playback Authorization, Including Token-based Authentication and Restrictions Playback authorization, which includes token-based authentication, is an additional security layer on top of protected 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 downloaded until the client has been verified and prevents content from being played in a non-ooyala player. There are several kinds of token-based authentication. OOYALA PLAYBACK TOKEN The Ooyala Playback Token, which in general is for authenticating users, is foundational in many of Ooyala's content protection features. See details in Ooyala Player Token on page 12, including integrating 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 page 22. WIDEVINE A composite content protection system, Widevine includes playback authorization and other features. If you want to integrate Widevine with Ooyala, contact your Ooyala Customer Success Manager. More details on integrating with Widevine are in Widevine Content Protection on page 63. CONTENT PROTECTION DEVELOPER GUIDE CONTENT PROTECTION OVERVIEW 8

9 ADOBE ACCESS Adobe Access DRM technology enables a variety of business models that lets you protect premium content across devices. More details on integrating with Adobe Access are in Adobe Access on page 70. PLAYREADY PlayReady is a DRM technology by Microsoft, used to protect premium content from beingviewed without a valid license. It is used in conjunction with Microsoft s Smooth Streamingprotocol. Ooyala provides a set of comprehensive content protection features that work together to provide you with the ability to secure your content. More details on integrating with PlayReady are in PlayReady Content Protection on page 66. ADOBE PASS Adobe Pass is categorized as playback authorization, not digital rights management (DRM). More details on integrating with Adobe Pass are in Integrating Adobe Pass with Ooyala Player on page 23. Digital Rights Management (DRM) Systems Here are details on some representative DRM systems that are either Ooyala solutions or can be integrated with Ooyala: 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 Ooyala publishing rules and PlayReady policies. More details: PlayReady Content Protection on page 66. The Widevine multi-platform DRM provides the capability to license, securely distribute, and protect playback of multimedia content on any customer device. Widevine utilizes user authentication though token-based options such as the Ooyala Secure Player Token. More details: Widevine Content Protection Adobe Access on page 70 DRM technology enables a variety of business models that lets you protect premium content across devices. DRM POLICIES Configurable DRM, which lets your Customer Success Manager or Ooyala Support create multiple DRM policies. Once enabled, you can assign any policy to any asset after ingestion. More details: Configurable DRM on page 71. Content Protection Options By Device Technology options vary by type of target device, network, streaming protocol, and other factors. The following table can help you decide which DRM system to use with your Ooyala deployment. The table shows what content protection offerings are supported by device. Desktop PC/Mac Flash Desktop PC/Mac HTML5 Android App Mobile/ Tablet ios App Mobile/ Tablet ChromecastXBOX Roku Stream HTTP Dynamic HTTP Live HTTP Live HTTP Live Smooth Streams Smooth Streams Smooth Streams CONTENT PROTECTION DEVELOPER GUIDE CONTENT PROTECTION OVERVIEW 9

10 DRM DRM Player Encrypted Stream Encrypted Stream Player Desktop PC/Mac Flash Streaming (HDS) Adobe Access Flash Player Akamai HD2 HDS/ RTMPe Flash Player Desktop PC/Mac HTML5 Streaming (HLS) N/A N/A encrypted HLS / AES-128 Ooyala HTML5 Player Android App Mobile/ Tablet Streaming (HLS) ios App Mobile/ Tablet Streaming (HLS) Microsoft Microsoft PlayReady PlayReady Ooyala Android SDK encrypted HLS / AES-128 Ooyala Android SDK and HTML5 Player Ooyala ios SDK encrypted HLS / AES-128 Ooyala Android SDK and HTML5 Player ChromecastXBOX Microsoft PlayReady Ooyala HTML5 Player encrypted HLS / AES-128 Ooyala HTML5 Player Microsoft PlayReady Custom (non- Ooyala) N/A N/A Roku Microsoft PlayReady Custom (non- Ooyala) N/A N/A *PlayReady is supported in the Discretix variant and is only compatible with players that support this variant. WARNING ABOUT WEB BROWSER THIRD-PARTY COOKIES By default, some browsers, such as Apple Safari, disallow third-party cookies, which can interfere with your OPT 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 on behalf 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 CONTENT PROTECTION OVERVIEW 10

11 CONTENT PROTECTION DEVELOPER GUIDE CONTENT PROTECTION OVERVIEW 11

12 AUTHENTICATION Identifying each unique viewer is a critical part of managing rights and authorizing playback. The Ooyala Player Token makes integration easy with a publisher s subscriber management system. For broadcasters in the US, Adobe Pass can also provide specific authentication for TV Everywhere viewing. OOYALA PLAYER TOKEN Ooyala 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 Ooyala Player 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 use of your digital content. For example, a user may take the embedded player Javascript (.js) script tag generated in Backlot and distribute it without permission to others for replay, or attempt other similar replay attacks. To prevent such unauthorized usage, Ooyala has introduced the Ooyala Player Token feature, which helps you protect your content from these types of risks. You can use this feature to secure your monetized content and prevent unauthorized distribution. The Ooyala Player Token feature provides you with a secure process that authenticates the player before it allowing it to replay your digital content. Token-based authentication ensures that your digital content cannot be downloaded or played until the client player has been authenticated. Once the client player is authenticated, the containing browser receives a cookie authorizing the client player to play the requested content. 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 sure to advise end users to enable cookies in their browsers. See Warning About Web Browser Third-party Cookies on page 10for more information. For more information on how to build web applications with the Ooyala Player JavaScript API, see Developing with the Player JavaScript API.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 flag adding your content assets to this syndication group. This will enable you to set up your web page to run your player(s), and send the authorization token in the form of a cookie to the browser. Follow these steps to secure your content in Backlot: CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 12

13 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 accepts numeric entries (e.g. 600). You may set a longer expiration time for the cookie if you prefer, since the Same Origin Policy protects its distribution. For more information about the expiration time, see Ooyala Player Token Expiration on page 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 Ooyala Player 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, see Basic Tutorial for the HTML5 Player. <!DOCTYPE html> <html xmlns=" <head> <title>my Test Player V3 Web Page</title> <!-- Load Ooyala Player --> <script src=" f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"> </script> <!-- Load additional custom modules --> </head> <body> My Player V3 Content:<br/><br/> <!-- Player Placement --> <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 recommended that you do not actually store such information on static web pages since token requests contain sensitive information. CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 13

14 STEP 3: SPECIFY THE EMBEDTOKEN EMBEDDED PARAMETER In the call to OO.Player.create(), specify embedtoken as an embedded parameter: OO.Player.create( ); You can see this in the code shown below : 'ooyalaplayer', "A5eXRtcjpb6AEKizxldiaThNBmL9GWGU", embedtoken : 'token value to be added here' <!DOCTYPE html> <html xmlns=" <head> <title>my Test Player V3 Web Page</title> <!-- Load Ooyala Player --> <script src=" f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"> </script> <!-- Load additional custom modules --> </head> <body> My Player V3 Content:<br/><br/> <!-- Player Placement --> <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 c onstruct the token request value and assign it to the embedtoken embedded parameter. The value is specified in the form of a URL that has the segments shown in the table below: URL Segment Protocol and domain Request path Query string parameters Description /sas/embed_token/pcode/comma-separated embed codes?api_key=apikey &expires=expiration time &signature=computed signature CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 14

15 URL Segment Description &account_id=optional account ID 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 construct these values): pcode: F0Y2E6qDLc1XS9yvdR48ulAQ2t1 embed code: A5eXRtcjpb6AEKizxldiaThNBmL9GWGU apikey: F0Y2E6qDLc1XS9yvdR48ulAQ2t1.yRIJm expiration time: computed signature: sp4cew3qqx1ibrlksfjlryuplbhialmzlh7/f39ibm4 Here is the call to OO.Player.create() that includes the token request value: OO.Player.create('ooyalaplayer', "A5eXRtcjpb6AEKizxldiaThNBmL9GWGU", embedtoken : ' F0Y2E6qDLc1XS9yvdR48ulAQ2t1/A5eXRtcjpb6AEKizxldiaThNBmL9GWGU? api_key=f0y2e6qdlc1xs9yvdr48ulaq2t1.yrijm&expires= &signature=sp4cew3qqx1ibrlksf 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 apikey pcode comma-separated embed codes expirationtime computedsignature Description If API access is enabled for your account, Ooyala provides you with an API Key. This is a required field. For more information about the API Key, see General Algorithm for Signing Requests. You can get this partner code (pcode) information for a particular provider from your Ooyala Backlot Web Account. Select the Account tab and click Developers. The API Key contains two sets of characters separated by a period (.). The set of characters to the left of the period is the pcode. This is a required field. You supply one or more embed codes that represent the players that will be embedded on the page. You can use up to 50 embed codes. You may specify a value of all if you would like to create the playback token for use with multiple assets (over 50 embed codes). This is useful when using the rights locker with applications that want to create the playback token for multiple assets. The POSIX time at which point the token expires. Use a short expiration time on the URL snippet so that the snippet cannot be replicated across other domains (more precisely, it can be embedded, but will become nonfunctional). Generate this signature on the server by following the instructions provided in General Algorithm for Signing Requests. CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 15

16 Value account_id Description (Optional) Your account or user identifier. While not always necessary in the Ooyala Player Token, the account_id is required for working with entitlements (such as ecommerce), concurrent stream limits, cross-device resume, or device registration. Use this parameter in conjunction with Rights Locker on page 40 and Device Registration API on page 48. COMPLETE WEB EXAMPLE: AUTHORIZE PLAYBACK AND OBTAIN A TOKEN In the following example, when the embedded player is loaded, the event triggers the communication of the token request URL to the player. The player then requests authorization and a token from the Ooyala authorization 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 unauthorized response is returned. <!DOCTYPE html> <html xmlns=" <head> <title>my Test Player V3 Web Page</title> <!-- Load Ooyala Player --> <script src=" f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"> </script> <!-- Load additional custom modules --> </head> <body> My Player V3 Content:<br/><br/> <!-- Player Placement --> <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> OO.ready(function() OO.Player.create('ooyalaplayer', "A5eXRtcjpb6AEKizxldiaThNBmL9GWGU", embedtoken : ' embed_token/f0y2e6qdlc1xs9yvdr48ulaq2t1/a5exrtcjpb6aekizxldiathnbml9gwgu? api_key=f0y2e6qdlc1xs9yvdr48ulaq2t1.yrijm&expires= &signature=sp4cew3qqx1ibrlksf f39ibm4' ); ); </script> </body> </html> CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 16

17 Warning About Web Browser Third-party Cookies By default, some browsers, such as Apple Safari, disallow third-party cookies, which can interfere with your OPT 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 on behalf 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 Token You can authorize playback using the Ooyala Player Token. Limiting playback exclusively to authorized users and exclusively on your page requires the communication of 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 URL on the server-side, specifying a short expiration time as one of the query-string parameters. You must also include your provider code and a comma separated list of embed codes. This URL is passed to our player via a JavaScript callback; its short expiration time prevents it from being lifted from your page and used elsewhere. Set the Token Expiration Time. You need to set an expiration time for the Playback Token in your Backlot Syndication tab. Note that this expiration time is independent of the token request expiration time. Its function is to specify how long the token (client-side cookie, issued by Ooyala) will be valid, and it 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 the player, 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 cookie object), video playback is enabled. CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 17

18 Playback Authorization. Before the video starts playing, the Ooyala player sends the authentication request and receives the token. When the authorization server validates the URL, it authorizes playing the content. The authorization is in effect until the session expires. If the session expires, the viewer needs 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 adjustable by the provider s server-side implementation). Use a short expiration time on the URL snippet so that the snippet cannot be replicated across other domains (it can be embedded, but will become nonfunctional). The other expiration time on the token object itself (a secure cookie, with its expiry time adjustable through 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 authorized content. 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 Expiration The 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 a session cookie, so it expires when the browser is closed. When using the Ooyala Player Token, you need to be aware of the various types of session expiration: URL Token Request Expiration - Shorter in duration than the expiration time you set in Backlot, this expiration 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 about setting 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 the player. 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 no syndication group associated with it, so you cannot configure the expiration time in a Backlot syndication group. Instead you must create a provider attribute called "wildcard_opt_expiration_time" and give it a value in seconds. If you do not create this attribute, then a default expiration time of 10 minutes will be used for the token. CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 18

19 TOKEN REQUEST URL EXPIRATION TIME The token request URL has an expiration that is separate from the token s expiration time that you set in Backlot (or via the API). Per the discussion at the bottom in the prior topic, How Does It Work we recommend that you use short expiration time. You set the Token Request URL expiration time within the URL itself. The format is similar to the following example: expires=expiredtimeinposixtime Note: For more information about constructing the Token Request URL, see the topic Controlling Playback 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. Following expiration, the user no longer has playback authorization and must reload the page to playback the content. 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 (or navigates away and returns). For more information about setting the expiration time in Backlot, see step 5 in 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 the browser 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 17 earlier in this document. Setting the Ooyala Player Token The Backlot UI provides you with an option to secure your content by setting a Syndication group flag adding your content assets to this syndication group. This will enable you to set up your web page to run your player(s), and send the authorization token in the form of a cookie to the browser. Follow these steps to 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 accepts numeric entries (e.g. 600). You may set a longer expiration time for the cookie if you prefer, since the Same Origin Policy protects its distribution. For more information about the expiration time, see Ooyala Player Token Expiration on page 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 Ooyala Player Token as a required option. CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 19

20 Using Ooyala Player Token with Ooyala ios and Android SDKs You 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 the same as standard implementations with some small differences: 1. Create a class that implements an EmbedTokenGenerator. See the following topics for instructions on 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), where token is a valid Ooyala player token for the list of embed codes. Implementing an ios OOEmbedTokenGenerator To use the Ooyala Player Token for user authorization your ios app must implement OOEmbedTokenGenerator. Click here to view the example used in this tutorial, and use the following steps to implement the OOEmbedTokenGenerator in your project. 1. on 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 the following ViewController : UIViewController <OOEmbedTokenGenerator> 3. Open the project ViewController.m file and create or edit the ooyalaplayerviewcontroller to call the method overload that takes embedtokengenerator. The syntax is shown in the following example: / Create the Ooyala ViewController, with self as the embed token generator OOOoyalaPlayer *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 for playback 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 and should not be publicly visible. This example is only useful for debugging but should not be used in production. Implement tokenforembedcodes in the ViewController.m file. The syntax is shown in 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 CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 20

21 */ - (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 with OOEmbedTokenGenerator implemented. From the SDK archive, navigate to: OoyalaSDK-iOS/SampleApps/DeviceManagementSampleApp Implementing EmbedTokenGenerator for Android To use the Ooyala Player Token for user authorization implement OOEmbedTokenGenerator in the Android 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 the following example: public class MainActivity extends Activity implements EmbedTokenGenerator, Observer Create an OoyalaPlayerLayoutController instance with the constructor that takes an embedtokengenerator 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!"); CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 21

22 4. A server-side generated token can only be created by the customer so content is authorized for playback on authorized sites. The client receives it and submits it to EmbedTokenGeneratorCallback(). These tokens should not be created on the client. The API secret should only be on the server and should not be publicly visible. This example is only useful for debugging but should not be used in production. Implement the gettokenforembedcodes method with an EmbedTokenGeneratorCallback interface. Add the.setembedtoken callback, where token is a valid Ooyala player token for the list of embed codes. This is shown in the following 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 with EmbedTokenGenerator implemented. From the SDK archive, navigate to: OoyalaSDK-Android/SampleApps/DeviceManagementSampleApp AKAMAI SECURE TOKEN You 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. The Akamai token provides a basic 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 authorization mechanism 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 Ooyala generates a short lived token that is then sent to Akamai to unlock an asset for streaming. This process 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 a playback button for an asset in an Ooyala player. 2. The player sends a token request to the Ooyala server. CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 22

23 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). This duration is based on standard Akamai recommendations. SYSTEM REQUIREMENTS Ooyala Player supports the Akamai token, with the same supported browsers as those supported by the Ooyala player, including Flash-based players (Akamai token authorization works with ActionScript for Flash). INTEGRATING ADOBE PASS WITH OOYALA PLAYER Adobe 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 logging in 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 Adobe Server. 2. Adobe Server acknowledges that the requestorid is registered and returns the list of MVPDs associated with that requestorid. 3. An end user logs in through Adobe Pass, attempting to authenticate themselves as a valid user of an MVPD 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 is authorized. TERMINOLOGY Here are definitions to terms used in this document. Term authentication authorization Definition TV Provider login authenticates the end user. Adobe Pass and Backlot authorize the end user to playback the video content. CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 23

24 Term requestorid resourceid staticresourceid Definition Adobe Pass identifier. Obtained when the customer registered with Adobe. Associated with a list of MVPDs on Adobe Pass. Ooyala Backlot identifier. Associated with the user s authorization rights on Adobe Pass (as configured in Backlot: pass:resourceid). Player parameter. Maps to resourceid (video s label in 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 the desired 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 your organization 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 page 24. Adobe Pass Integration Reference Player parameters, the APIs, and events associated with Adobe Pass integration. PLAYER PARAMETERS Parameter staticresourceid showloginatstart Description Player parameter that is passed to Adobe Pass Server. Match with the resourceid on the Backlot label. Whether to show the login at startup. TRUE - If the end user is not yet authenticated, automatically show MVPD to login. CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 24

25 Parameter Description FALSE (default) - Do not show MPVD to login. API REFERENCE OO.Pass API API Call OO.Pass.login() OO.Pass.logout() OO.Pass.checkAuthentication() OO.Pass.isAuthenticated() OO.Pass.selectProvider(event) OO.Pass.getSelectedProvider() OO.Pass.useProviderDialog(dialog) OO.Pass.checkAuthorization(resourceId) Description Check authentication and login. You can listen to OO.EVENTS.ADOBE_PASS_AUTH_STATUS if you're already logged in. Otherwise it will show login dialog. Attempt to logout the current user. Will do a full check if authenticated. You can listen to OO.EVENTS.ADOBE_PASS_AUTH_STATUS with the current auth status. Returns true if authenticated. See useproviderdialog(). You can use this function to parse out the provider and to tell Adobe Pass your MVPD choice. Returns the provider that you are currently logged into. Use custom MVPD dialog callback function. See the Sample Web Page. If the end user is authenticated, check whether they have authorization with the given resourceid. Success: Publishes OO.EVENTS.ADOBE_PASS_TOKEN_FETCHED and settoken (specific within Adobe Pass). Failure : Publishes OO.ERROR.ADOBE_PASS_TOKEN and tokenrequestfailed (specific within Adobe Pass). OO.Pass.getAuthorization(resourceId) Attempt to get authorization for the provided resourceid. If the end user is not authenticated, it will attempt to login first. Success: Publishes OO.EVENTS.ADOBE_PASS_TOKEN_FETCHED and settoken (specific within Adobe Pass). Failure: Publishes OO.ERROR.ADOBE_PASS_TOKEN and tokenrequestfailed (specific within Adobe Pass). OO.Pass.isEntitlementLoaded() Returns true if the Access Enabler is loaded and initialized. OO.PASS CALLBACK API CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 25

26 API Call OO.Pass.onSetToken(func) OO.Pass.onTokenRequestFailed(func) OO.Pass.onSetAuthenticationStatus(func) OO.Pass.onEntitlementLoaded(func) Description Takes a function in the form of function func(event, resid, token) to callback when Adobe Pass dispatches a settoken event. Takes a function in the form of function func(event, stat, errorcode) to callback when Adobe Pass dispatches a tokenrequestfailed event. Takes a function in the form of function func (event, stat, errorcode) to callback when Adobe Pass dispatches the setauthenticationstatus event. Takes a function in the form of function func(event, stat, errorcode) to callback when Adobe Pass dispatches the entitlementloaded event. EVENT REFERENCE Event OO.EVENTS.ADOBE_PASS_AUTH_STATUS OO.EVENTS.ADOBE_PASS_TOKEN_FETCHED OO.EVENTS.ERROR Description When someone checks for authentication. When a successful token is fetched for authorization. When an error is produced. Adobe Pass has additional parameters passed to listeners for some Adobe Pass errors. Note: More detailed errors from MVPD will be in params.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 IMPLEMENTATIONS Sample Web Page Integration <html> <head> <script src=" </ script> <script> OO.ready(function() window.pp = OO.Player.create("video-container", "[your_embed_code]", width: '400px', height: '300px', staticresourceid: '[your_resource_id]', ); CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 26

27 ); </script> </head> <body> <div class="video-container" id="video-container"></div> a> <a href="#" onclick="javascript:oo.pass.login();return false;">log In</ <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=' <script src=" </ 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(); CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 27

28 ); // end custom Display Provider Dialog </script> </head> <body> <div class="video-container" id="video-container"></div> a> <a href="#" onclick="javascript:oo.pass.login();return false;">log In</ <a href="#" onclick="javascript:oo.pass.logout();return false;">log Out</a><br /> </body> </html> CONTENT PROTECTION DEVELOPER GUIDE AUTHENTICATION 28

29 AUTHORIZATION Publishers use playback authorization to ensure that videos can be played only from an authorized account. The Ooyala Player Token helps ensure that only authorized viewers can view content. For instance, 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 versions of their favorite channels. Concurrent stream limits let publishers limit the number of simultaneous streams being played by one particular user account. This protects a publisher s revenue streams by limiting paying subscribers who share login information with friends. It also meets stringent studio license agreements that specify concurrent stream limit enforcement in addition to using industry-accepted DRM technologies. PLAYER AUTHORIZATION API The Authorization API request is the key element in Ooyala's content protection features. A request to the Authorization API has the following syntax: [GET]/sas/player_api/v1/authorization/embed_code/pcode/ ListOfCommaSeparatedEmbedCodes?query_string_paramters Example: R0Y3Y6HtBEQtRUoC55GY8DTF4pGA/44azdwNDpSWUvfd8F30d55tXY0YH9njH? device=html5&domain= ROUTE ATTRIBUTES The following table describes all attributes of the route. Attribute pcode ListOfCommaSeparatedEmbedCodes Description Your provider code Embed codes (content IDs or asset IDs) must be separated by commas in this list. QUERY STRING PARAMETERS The following table describes the query string parameters of the routes. The request can have several optional 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 request was made (epoch time). No CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 29

30 Parameter Description Required? Default: Time request received by server supported_formats device jsonp embed_token auth_token List of comma-separated values indicating supported formats. The value of this parameter is normally tightly coupled with the device type, since support for formats is limited by device. Valid Values: Shown in table below List of comma-separated devices for playback. Valid Values: See table below Value of this parameter will be used as the wrapper in returning JSONP. Default: JSON Discussed in section "Ooyala Player Token" in the Player Developer Guide. Authorization token, discussed in Enforcing Per-Viewer Limits on Concurrent Streams on page 33 No No No No No SUPPORTED FORMATS AND DEVICES The supported_formats parameter can be a list of any of the following values, separated by commas. Format HDS RTMP HLS MP4 Akamai HD Widevine HLS Widevine MP4 Widevine WVM Adobe Access HLS MicroSoft Smooth Streaming. Value hds RTMP m3u8 mp4 akamai_hd wv_hls wv_mp4 wv_wvm faxs_hls smooth Note: For smooth streaming, device (see below) must be GENERIC. The device parameter can be a list of any of the following values, separated by commas: CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 30

31 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 JSON array indicating the authorization status for each of the embed codes included in the list in question. The following is a sample response from the Authorization API: "debug_data": "server_latency":"21.919", "request_id":"domu b-d2-11_ _57", "user_info": "ip_address":" ", "continent":"north AMERICA", "country":"us", "request_timestamp":" ", "language":"en-us", "device":"html5", "timezone":-7, "domain":" "signature":"0pobctrsloiszchrmi7aeoub05/okriavq36bgw74lu=\n", "authorization_data": "44azdwNDpSWUvfd8F30d55tXY0YH9njH": "authorized":true, "message":"authorized", "code":"0", "request_timestamp":" ", "retry":null, "streams":[ "delivery_type":"hls", "url": "data":"ahr0cdovl3bsyxllci5vb3lhbgeuy29tl3bsyxllci9pcghvbmuvndrhemr3tkrwu1dvdmzkoeyzmgq "format":"encoded" ] ELEMENTS OF THE RESPONSE The significant portions of the response are in boldface type in the sample. These parts of the response are: CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 31

32 1. debug_data is used only for debugging data. It can change at any time. 2. signature in the response (discussed in the following section, How the Output Is Signed) is used to ensure that the response has not been tampered with by a 3rd party. The most significant hash is the authorization-data hash, which includes the result of the authorization request. Below are all the enumerations for possible codes:message pairs (authorized has a binary true/false value). This list can continue to change as we add additional parameters to authorization, providing more system visibility into the potential failure. 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 is returned. This value should be passed along with the stream URL to the playback SDKs for obtaining the Widevine license and decrypting the token. "authorization_data": "hunwp2njocackrsv_wqbdcsw9p1xmlww":... "streams":[ "delivery_type":"wv_wvm", "url":..., "widevine_server_path":" 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 Enforcing Per- Viewer Limits on Concurrent Streams on page 33. CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 32

33 ENFORCING PER-VIEWER LIMITS ON CONCURRENT STREAMS Your Ooyala Backlot provider account can be configured to set a limit on the number of concurrent streams. Each of your viewers (your own specific accounts) has the same global limit. The limit applies to all syndication groups for your provider account. After the limit is reached, no more videos can be accessed until the number of concurrent streams goes below it. BROWSER LIMITATIONS Ooyala is aware of the limitation of certain browsers that have different methodologies of handling playback sessions that impacts the behavior of concurrent stream limits. For example, two different browsers, with one being Google Chrome, on the same same device, will count as two different devices or playback sessions. Under this scenario, if the stream upper bound limit is 1, then the user will be restricted from playing back on the browser that is opened last because it is identified as another device. On the other hand, some browsers are able to properly identify session data that allows a user to playback streams simultaneously on the same device. This means that as long as the same device is used by the user to stream content, the concurrency limit will not count other browsers as different sessions. It s important to note that this use case is not a bug. It is also not a breach of concurrency limits because there is no sharing of user identities between browsers. In the event that the user login is shared with another device, then concurrent stream limit is enforced, not allowing another stream to be opened until the previous one is stopped. ENABLING THE LIMIT If you are interested in this feature, contact your Ooyala Customer Success Manager to enable it. Be prepared with the upper limit (the maximum number of concurrent streams) you want. You can enable this limit yourself either in the Backlot UI or with a Backlot API call. However, you must still contact your Customer Success Manager to specify the upper limit. To prevent the accidental changing of this limit, it can be changed only by your Customer Success Manager. 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 Syndication Group or the Default Group. 5. On the right, make sure the checkbox for Require Ooyala Player Token is checked. 6. Under Require Ooyala Player Token, check Limit per-user concurrent streams. 7. Contact your Customer Success Manager to set the upper limit. With the Backlot API 1. Add the property restrict_concurrent_streams with a value of true to the appropriate publishing rules. In the following example, this property is added to a previously created publishing rule by making a call to [PATCH]/v2/publishing_rules/9b70a34a67881c7a291d8b restrict_concurrent_streams : true 2. Contact your Customer Success Manager to set the upper limit. CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 33

34 HOW IT WORKS Concurrent stream limits can be enforced on HTML5 players, Flash players, Google Android, and Apple ios. To enforce the concurrent streams limits the player has to keep sending the heartbeat requests to Ooyala systems. Sending of heartbeat requests is already implemented on the Ooyala Flash player, HTML5 player, Chromecast, ios and Android SDKs. On these platforms you don't need to write any code for sending the heartbeat requests. Using any other player will require you to implement the heartbeat. You can configure the heartbeat by contacting you Customer Success Manager. The Ooyala service keeps a count of the active streams for each of your viewers (customer accounts). When a viewer attempts to access some content, your client application program calls Ooyala s Authorization 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 the viewer leaves the page or exits the mobile application, the client no longer sends the heartbeat, and the service 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 stream count by one. Begin and continue playback Immediately send auth_token to Ooyala as heartbeat Send auth_token as heartbeat every heartbeat_interval seconds Return: require_heartbeat set to true auth_token heartbeat_interval in seconds Respond OK Maintain concurrent stream count End playback Stop sending heartbeat Decrement the counter by one After the pertinent web page or client application is exited, if the service has not received a heartbeat in a certain period of time, the stream is stopped, the auth_token is invalidated, and the count of concurrent streams is decreased by one. To enforce content protection, Ooyala does not disclose the precise length of time before token invalidation for security reasons. CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 34

35 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 by the Ooyala service. Note: To enforce content protection, when the client receives the first response that includes the auth_token, it immediately sends a heartbeat. It does not wait for heartbeat_interval seconds before sending the first heartbeat. Thereafter, the client GETs the heartbeat continually at heartbeat_interval seconds until the pertinent web page or application is exited. The response to a successful heartbeat request looks like the following: "auth_token"=>"abc", "message"=>"ok", "timestamp"=> , "signature"=>"2sbwfegoi+hqvz4ektihm/vzo3cuoq2c+5/yogyldtw=" Any message other than OK indicates failure, in which case the client application should stop playback. FULL EXAMPLE WITH ALL PROPERTIES The following is an example of first-time GET to the Authorization API, with response highlighting the properties (near the end) that are needed for enforcing the concurrent stream limit: require_heartbeat, auth_token, and heartbeat_interval. Note that the actual returned values are much longer strings than is shown here for ease of reading. Then follows the request/response sequence to maintain the heartbeat. First Request [GET] 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" =>" ", "retry" =>nil, "synd_rule_failures" =>nil, "require_heartbeat" =>true, "streams" => [ "delivery_type" =>"hds", "url" => "format" =>"encoded", CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 35

36 "data" => "ahr0cdovlmy0bq==" ], "user_info" => "ip_address" =>" ", "domain" =>"gnarly.com", "request_timestamp" =>" ", "account_id" =>"johnsmith", "country" "timezone" =>-8.0, "continent" =>"NA" =>"UNKNOWN",, "debug_data" => "server_latency" =>" ", "request_id" "user_info" => "request_timestamp" =>" ", "auth_token" => "WGd5uZ29WTFBpeDlnPT0K", "heartbeat_data" => "heartbeat_interval" =>300, "signature" Immediately Send Heartbeat =>"4f397d7f6091ce8e7d43354c424095fe", =>"b09xu7uxl/ufrj9mokmhisprsf21zcok+7iv1lfcnva=" [GET] FoeGbkH9m/auth_token/WGd5uZ29WTFBpeDlnPT0K Response "auth_token"=>"abc", "message"=>"ok, "expires"=> , "signature"=>"2sbwfegoi+hqvz4ektihm/vzo3cuoq2c+5/yogyldtw=" Heartbeat Interval By default, this values is 300 seconds. This limit is configurable at the provider level, which will override the default value. The lower limit of the heartbeat interval is capped at 30 seconds. Please contact your account manager to configure this limit. [GET] FoeGbkH9m/auth_token/WGd5uZ29WTFBpeDlnPT0K Response "auth_token"=>"abc", "message"=>"ok", "timestamp"=> , "signature"=>"2sbwfegoi+hqvz4ektihm/vzo3cuoq2c+5/yogyldtw=" CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 36

37 CONFIGURABLE PADDING (HEARTBEAT LATENCY) Configurable padding determines the lifetime of a stream. If this attribute is not set, a default latency of 30 seconds will be used. We recommend setting a default latency greater or equal to 10 seconds. Please contact 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 failure message, 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" =>" ", "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 stream limit reached ERROR_AUTHORIZATION_ HEARTBEAT_FAILED OOOoyalaErrorCodeHeartbeatFail Failure in heartbeat request When these exceptions are thrown, your client applications must catch them to display an appropriate message. For instance, on Android in Java, enclose your GETs for authorization and for heartbeat in 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: CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 37

38 Your mobile application should save a timestamp before backgrounding and then cease sending heartbeats. When the viewer resumes the application, check the saved timestamp. If the elapsed time is less than heartbeat_interval, simply resume playback. Otherwise, you should require reauthorization, get a fresh auth_token and start a new heartbeat. A suspended desktop application cannot continue sending heartbeats. This increases the likelihood that an 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 authorization so the count is not incremented against the limit. In this case, the viewer can quickly switch videos without raising the concurrent stream count. CONTENT PROTECTION DEVELOPER GUIDE AUTHORIZATION 38

39 ACCESS CONTROL Publishing rules give publishers complete control over their content by enabling control of where and when contents can be viewed. It also allows or restricts website domains that can show content by either specifying a list of domains that are allowed to embed the publisher s content or specifying a list of domains 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 ACCESS CONTROL 39

40 RIGHTS MANAGEMENT The Ooyala Rights Locker is a highly scalable authorization system that enforces granular access control to 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 individual asset or a bundle (collection) of assets; assets can be discrete movies, live events, linear channels or even 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 publishers better 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 binds entitlements to viewer devices. Mostly used for higher value (purchase or rental window) assets. As with Device Management, required by studios to go with a robust DRM deployment to open devices. This is a restriction 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 entitlements to digital assets. As a whole Rights Locker consists of three sets of APIs and Ooyala services. API Location Description Backlot API developers/documentation/ concepts/book_api.html Manages assets (videos) Manages labels Manages publishing rules Rights Locker API Player Authorization API developers/documentation/api/ rightslocker.html developers/documentation/api/ player_v3_authorization_api.html Creates and manages entitlements for customerdefined accounts, using assets, labels and publishing rules defined in the Backlot API Run-time check of authorization 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 rules to create and group entitlements for individual users. 3. With the player, verify the authorization to entitlements at playback and when required issue licenses or other credentials for Digital Rights Management (DRM) systems. In the majority of cases, authorization simply occurs, without any programming. Prerequisites to Rights Locker To use Rights Locker, you need to have the following: CONTENT PROTECTION DEVELOPER GUIDE RIGHTS MANAGEMENT 40

41 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 Concepts Some essential terms are introduced to help define concepts that are key to Rights Locker. Term Asset Label Provider Account Publishing Rule Entitlement Product Definition/Description In Backlot, your materials (videos and the like) are called assets and are identified by an asset identifier or asset_id (also called embed code ). Note: You cannot use external identifiers with Rights Locker. The values passed must be real embed codes (asset IDs). In Backlot, you can associate your assets with labels you define to categorize your assets. Labels are identified by label_id. 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's ACCOUNT tab, Developers subtab and is called "Partner Code." You need this provider ID to make calls to the Rights Locker API. An account identifies one of your video consumers to whom you grant entitlement to assets. The account is identified by an account_id, which should be secured in a manner recommended in Your Users, Your Accounts: Security on page 42. Rights Locker uses your account IDs only to create the entitlement and for no other reason. Account IDs are unique by provider. A publishing rule is a set of restrictions on content, such as geographic or time limitations. 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 global restrictions for a piece of content 2. Entitlement publishing rules, which are per user, per label (content-group) for modeling business restrictions around particular transactions or products sold to the user. 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 one entitlement. Any updates with the same three values will overwrite the previous entitlement. A user can have multiple entitlements to the same label, as long as they are under different external_product_ids. One or more entitlements together reflect a user's "ownership" (using the term loosely) of a product offered by the provider. These products are grouped by external_product_id. For example, a user might subscribe to the "silver" package and therefore have access to back catalog sitcoms (which are group by a label) on all devices, sports channels (a label) only on desktops. A user can "own" different products, and so they can have many different entitlements, grouped under different external_product_ids. For instance, continuing the above example, the user could own both the silver package that grants access CONTENT PROTECTION DEVELOPER GUIDE RIGHTS MANAGEMENT 41

42 Term Definition/Description to sports channels on desktop and also own the mobile package that grants access to the sports channel on mobile phones. Your Users, Your Accounts: Security User 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 in your 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 address. For example, an acceptable account_id is to use a base64, URl-encoded, Secure-hash-algorithm-(SHA)-256 digest of the username or address, salted with some secret string that only you know. This salt must not be reused for any of your vendors other than Ooyala. This ensures that neither Ooyala nor a "man-in-the-middle" hacker sniffing network traffic can translate back from your GUIDs to real usernames or passwords. The account_id must 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 an account wherever an API request requires it. How Authorization Works Based on the types of publishing rules described in Key Concepts on page 41, for each authorization request, the user is allowed access if one of two sets of conditions shown below is true: Table 1: Rights Locker Authorization Conditions Condition 1: The asset publishing rule passes. Condition 2: AND The "Require user entitlement" setting for that publishing rule is not true. OR Condition 3: AND The "Require user entitlement" setting for that publishing rule is true; AND The user has a valid token containing and account_id; AND The account_id in the token has one or more entitlements for the asset or for the label that includes the asset; AND An entitlement publishing rule associated with one of those entitlements passes. Multiple entitlements can relate to the same asset, in which case the authorization is based on the union of the rules. As long as one of the entitlements passes, the access is allowed. Backlot Setup Rights Locker relies on Backlot API calls for creating and managing assets (videos), labels, and publishing rules. 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 and manage labels. After creating labels and associating them with assets, with Rights Locker you make combinations of labels and publishing rules to define entitlements. CONTENT PROTECTION DEVELOPER GUIDE RIGHTS MANAGEMENT 42

43 Note: Tip on Label Design: The shallower the hierarchy of labels, the better performance, even though deep 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 appropriate rules with these field. See the example PATCH in Extended Example of Rights Locker on page 43. REQUIRE OOYALA PLAYBACK TOKEN To ensure that all requests for an asset are subjected to authorization, you need to enable the Ooyala Player 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 require the token. See the example PATCH in Extended Example of Rights Locker on page 43. Extended Example of Rights Locker This 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 be granted access to the content (with Rights Locker API). At the time of playback, the system checks if the authenticated 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 create a publishing rule or use an existing one. In this example, the user decides to reuse the publishing rule ID my_publishing_rule_id. 1. Update the publishing rule my_publishing_rule to set the require_user_entitlement field to true. Make a request to the Backlot API server at [PATCH]/v2/publishing_rules/my_publishing_rule_id "secure_playback_token": "enabled":true, CONTENT PROTECTION DEVELOPER GUIDE RIGHTS MANAGEMENT 43

44 // 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 the creation 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 on page 42 so that only the provider knows who the actual viewer is.) Make a request to the Rights Locker API server at [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 : , end_time : ] 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 an embedded, URL-encoded Ooyala Player Token (OPT), including the user's account ID (account_id %3Dmy_account_id). Make a request to the authorization service: [GET] 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%3D %26signature%3DnSYMwiVFzbGE5O%252BWhEbXvm1M The system retrieves the asset and assigned publishing rules. The system then checks if the user account is authorized based on those rules, as described in How Authorization Works on page 42. In the majority of cases (based on the Ooyala Player without customization), verification of entitlement occurs automatically with your calls to the Player Authorization API; no additional programming is required, as long as you have setup the prerequisite configuration for Rights Locker described in Prerequisites to Rights Locker on page 40. BINDING VIEWER DEVICES TO ENTITLEMENTS To protect your assets and ensure that you realize all possible revenue, with Rights Locker in conjunction with the Device Registration API on page 48, you can programmatically bind the entitlements your viewers purchase to the viewers' devices. This binding can prevent your customers from accessing content that they have not purchased. CONTENT PROTECTION DEVELOPER GUIDE RIGHTS MANAGEMENT 44

45 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 48 you can build a portal for your users or customer support 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 and prevents multiple viewers from sharing the same account. Rights Locker gives you the ability to "bind", or associate, the viewer's devices to your content via 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 a video, once a viewer starts watching a purchased video on a particular device, the video is restricted to that 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 device limit. 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 devices against the upper limit of devices per provider. This is both for speed of performance and for separation of concern. Most logically, a device-bound entitlement is part of your checkout or purchasing process on your site. Ooyala has made the creation of entitlements simple to fit in with your checkout, but it is up to you to ensure that "Case B" shown above does not occur, because at playback time, in "Case B", a viewer is denied authorization to access the asset. CONTENT PROTECTION DEVELOPER GUIDE RIGHTS MANAGEMENT 45

46 Thus, in the design of your device registration portals and your checkout, you need to keep track of the counts 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 either assets or labels as described inhttp://support.ooyala.com/documentation/developers/api/rightslocker.html 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. A label-based device-bound entitlement means that the viewer must access all assets under the label only from 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 of num_devices_to_bind. CONTENT PROTECTION DEVELOPER GUIDE RIGHTS MANAGEMENT 46

47 BASIC WORKFLOW WITH DEVICE REGISTRATION AND BINDING The following use case illustrates a basic pattern in device binding. (As detailed in the Device Registration API on page 48, 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 with your checkout process. 1. A viewer purchases a single-device movie. 2. You create an entitlement for that viewer, including num_devices_to_bind = 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 on page 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 on page Ooyala services determine that the single-use entitlement has already been used and playback is not authorized. SOME BEHAVIOR TO CONSIDER Discussed below are some basic behaviors of device binding and some possible "corner cases" to take into 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 device 2. 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 is authorized 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 asset 2. 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 all the 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 his mobile 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 entitlement and then create a new one with num_devices_to_bind = 2. This means that you must keep track of how many devices a viewer can register for an entitlement., as discussed in the introduction. CONTENT PROTECTION DEVELOPER GUIDE RIGHTS MANAGEMENT 47

48 DEVICE REGISTRATION Device management, if enabled in Backlot, is the automatic registration of devices in Ooyala Rights Locker upon 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, please contact your CSM. DEVICE REGISTRATION API With Ooyala's device registration APIs, which are integrated with Ooyala Rights Locker, providers can comply with content owners requirements to limit the number of devices associated with a single viewer. A single consumer account (called a "viewer") can be limited to no more than a specific number of registered devices, after which limit has been reached, devices must be "de-registered" before other devices can be added. Only devices registered to the viewer are able to play videos published with the device limits policy. 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. The endpoint for these API calls is player.ooyala.com. This interface is suitable for you to create a viewer self-service "portal" through which the viewers themselves can manage their own registered devices, 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' specific accounts device history and modify device rules or settings not permitted by client application API described above. The endpoint for these API calls is rl.ooyala.com. These calls must be signed by your provider secret key, as described at Your API Keys. 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 Microsoft PlayReady 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 rule limit_devices_per_viewer. For any one specific provider, all assets subject to device limits have the same limit. CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 48

49 2. Deregistration rule: limit consumer account to deregister X devices in Y time interval. Ooyala enforces a limit on the number of deletions that can happen in a given time period. Applies provider-wide to all assets. 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 own authentication 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 portal is described below. CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 49

50 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. CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 50

51 2. Application requests a DRM license for the DRM-protected stream. The license request is proxied via your authorization service to the license server; the authorization service attaches the account_id and 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 asset published with a require user entitlement policy, the entitlements for that specific user are checked against the Ooyala Rights Locker. If the asset s policy includes device limits, Ooyala s authorization service ensures that the current device is in the registered domain of devices for that user before granting the license. The DRM license servers generate a unique device id. The device id is encrypted and cannot be read by the client application. 4. As part of entitlement validation, Ooyala Rights Locker checks the device limits, based on the account_id and device_id. A successful check is necessary before a DRM license. Device Registration depends on the Ooyala Player Token for secure authentication (account_id) and DRM for robust, secure device ID. If all entitlement checks pass, the license is cryptographically bound to the device. 5. If the device has not been registered, the provider can configure his service so that the device is autoregistered. If the user has not exceeded the device limits, auto-registration adds the device to the user s device domain. (The user-agent string of the device is recorded automatically.) The user is authorized to proceed. For the Ooyala Flash Player, when an authorization token is issued or modified, the event authtokenchanged is triggered. With the player message bus, you can listen for this event. For an example, see "Listening To a Message Bus Event." At this point, you can optional automatically prompt the user for a device nickname. Of course, your user 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 nicknames to create a user experience that appropriately communicates the device limit restriction. The provider can use APIs to create a self-service portal and/or create a customer service capability to (de-) register devices. 7. When authorization fails, the client needs to make a request to user Portal API as defined below to get the 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 a device 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 Registration These properties and their definitions apply to both the user portal and the customer support portal. account_id actor and actor_type auth_token Provider's specific users. For certain PATCH or DELETE requests, the username of the administrator must be specified in the request body. An encrypted string returned to the client in the authorization response. However, in places like a device registration portal you would not do video authorization. To get the auth_token in these cases use the embed token API and specify an CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 51

52 device_limit next_delete_time nickname pcode public_device_id registration_time result user_agent additional query parameter return_json=1 to get the response auth_token : sample_auth_token. The maximum number of devices that can be registered with the viewer. The next time a registered device may be deleted from this viewer. ISO 8601 format. A user friendly name for a device. There are no restrictions on what characters are allowed and the maximum length of a nickname is 255 characters. Provider code. For details, see Your API Credentials. A random string generated by Ooyala that identifies the device. (This is not the actual ID generated by the Digital Rights Management (DRM) system. The DRM device ID is never exposed.) See the note below about how the behavior of the Chrome browser can affect the value of the public_device_id. The time at which registration was attempted. ISO 8601 format. Returned in the response, a specific result of an attempt to register a device. The HTTP response code for most of these messages is 200; be sure to check the response body for specific error messages. 200: new device registered 200: device binding failed 200: device limit reached 200: no device registration action 404: device registration last result not found The client s user agent when the registration attempt was made. ABOUT GOOGLE CHROME AND DEVICE IDS Due to restrictions imposed by the Google Chrome browser's architecture for security, your users might experience 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 will be assigned two diffferent device IDs. Users who reset their Adobe Access DRM licenses in Chrome will lose their device IDs. The IDs will be 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 your customer support group, allowing the user to remove the old device IDs and register the "new" ones. CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 52

53 Device Management API for User Portals Part of Ooyala Player API family, these APIs can be called from either the client application itself or from a user 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. The response 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 that supplies the required device ID. Unfortunately, if a license request fails, an Ooyala-specific error response cannot 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/registration failure. This request returns error messages if either the device limit or the entitlement limit is reached, in addition to other error conditions. The request also returns a list of previously registered devices, so the user can determine 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/ Firefox/23.0", "registration_time":" :41: ", "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/ Firefox/23.0" ] 200 result : Either success or a specific error message about why the registration failed. The following 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 CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 53

54 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 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. 429 "message": "Delete Limit Reached" - Returned if deletion was not allowed because of recent attempts CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 54

55 Device Registration API for Customer Support Portals Part of the Ooyala Rights Locker family of APIs, Ooyala's REST-based device registration API can be used to construct customer support tools. The APIs are designed to be called from servers running provider's the 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/DELETE In requests that rely on PUT and DELETE to update or remove settings, in addition to other properties that might be required for the operation, the body of the request must include the following properties, where the 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 the viewer... 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,. ] CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 55

56 GET LAST RESULTS FOR AN ACCOUNT The value of the results property in the response from the /last_result qualifier is a message about the success or failure of an account's recent attempts to register devices. This request is similar to /last_results qualifier for the user portal, except for customer support, it returns all results for all playback sessions for the given account. (For user portals, /last_result returns information only for a specific 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/ Firefox/23.0", "registration_time":" :15: ", "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/ Firefox/23.0", "registration_time":" :21: ", "result":"new device registered", "public_device_id":"48cf9f3f-71f a544-a1c13d97a298" ] GET HISTORY OF ALL ACTIONS ON AN ACCOUNT Account history can be used by Customer Support to diagnose problems with deleting, renaming, and adding devices to an account. The account history displays what action was taken, when it was taken, and by 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 CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 56

57 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 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 200 "message": "OK" - Request succeeded 404 "message" "device does not exist" - account_id under pcode not found MODIFY DEVICE LIMIT [PUT]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/ device_limit "device_limit":device_limit Responses 200 "message": "OK" - Request succeeded 404 "message" "device does not exist" - account_id under pcode not found GET DEVICE LIMIT [GET]rl.ooyala.com/device_management/pcode/pcode/account_id/account_id/ device_limit Responses device_limit : actual limit, CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 57

58 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 200 "message": "OK" - Request succeeded. 404 "message" "device does not exist" - account_id under pcode not found CONTENT PROTECTION DEVELOPER GUIDE DEVICE REGISTRATION 58

59 DIGITAL RIGHTS MANAGEMENT Ooyala delivers premium content at the highest level of security provided by studio-approved DRM providers - Adobe Access, Google Widevine, and Microsoft PlayReady. This lets publishers monetize their content on mobile devices and connected TVs, while distributors can meet their obligations to 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 is described in the section DRM Attributes for Remote Asset. Ooyala still maintains the DRM license servers for live streams (treated as remote assets in Backlot), but the encoder is responsible for packaging and encryption. Ooyala supports the following studio-approved DRMs: Widevine Content Protection on page 63 PlayReady Content Protection on page 66 Adobe Access on page 70 DRM ATTRIBUTES FOR REMOTE ASSETS (INCLUDING LIVE STREAMS) For remote assets protected by Digital Rights Management (DRM) systems, you need to associate information about that system. 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 applied automatically, but remote assets do not pass through Ooyala transcoding and thus must be updated by you. For example, for live encoders this has to be updated by someone configuring the encoder (such as you or your vendor's technical support team). For every remote asset that is protected by licenses issued from DRM systems operated by Ooyala, you need to set some attributes pertinent to the type of DRM system in use (Widevine or PlayReady). Widevine needs an id (explained below). Widevine should provide your service information, which contains all the necessary parameters needed for packaging your media (id, IV, Key). 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: For PlayReady-protected remote assets (when drm_type is playready or playready_hls on the request), you need to set these attributes before acquiring a license from PlayReady; otherwise, the remote 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 identifier associated with the content. It can be any 16-byte value expressed in base64 or hex format. The content key should be a random 16-byte value that is used as the AES key to encrypt the content. This may also be stored in base64 or hex format. You must check if your encoder requires the key id and content key to be in the base64 format or hex format. When you create a key for the first time, you don t need to use a version. In this case your content key field will be content_key and the license URL would be: Ooyala allows you to associate multiple content keys with an asset. You can do this by naming the content key field as content_key_version where version is a number that needs to match the version in the license CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 59

60 URL. For example, if the content key field is content_key_2, then the license URL would need to end with a 2:.../playready/ooyala/version/2. You may associate multiple keys with an asset by using a different version number each time. See example below. SET/REPLACE WIDEVINE ATTRIBUTE FOR DRM PROTECTION OF REMOTE ASSET id is generated by the encoder and needs to be passed to Ooyala through the API shown below. Ooyala stores the id in Ooyala systems. Work with Widevine to retrieve your id. If you are unable to retrieve the id from Widevine, your CSM can work with you and the encoder to get these values configured in the encoder. [PATCH]/v2/assets/asset_id/drm_attributes/widevine "id":"value1" 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 for PlayReady 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 and PlayReady 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. For example, 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 datastore if 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 the encryption 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", CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 60

61 "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 can work with you to get this value configured in the encoder. Ooyala stores the license acquisition URL in Ooyala systems. PROPERTIES The following table describes the properties you need to set for each DRM type. drm_type Property Description playready key_id The key_id is an identifier associated with the content. It can be any 16-byte value expressed in base64 or hex format. Type: String Default: None Example in base64 - V/ YqH723UV48kjRlUzyqww== Example in hex - 1f2af657b7bd5e513c caac3 playready content_key_version The PlayReady content key. The version of the parameter name is an integer that matches the CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 61

62 drm_type Property Description version in the license acquisition URL for the specific asset. For example, if the license acquisition URL is: player.ooyala.com/sas/ drm2/jqbkh9m/uphgnsr/ playready/ooyala/ version/3 Then the corresponding parameter name is content_key_3. Type: String Default: None Example in base64 - V/ YqH723UV48kjRlUzyqww== Example in hex - 1f2af657b7bd5e513c caac3 widevine id The Widevine identifier for the asset Type: String Default: None Example: "1234" EXAMPLE This example creates DRM attributes for the IzNnoCi9B2rtWs asset for a live encoder. The license acquisition URL for this asset is as follows: 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 about using the Scratchpad, see The Scratchpad. CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 62

63 WIDEVINE CONTENT PROTECTION Ooyala provides support for Widevine to meet the content protection requirements for high-quality content online in on-demand and live streaming formats. Widevine s multi-platform DRM provides the capability to license, securely distribute and protect playback of multimedia content on any consumer device. Content owners and digital media providers can use Widevine s solutions to ensure revenue generating services keep flowing to whatever device consumers desire. To give you the capacity to protect your content using Ooyala and Widevine, you need to understand how Widevine works and how to use Widevine with your ios, Android or Connected TV device. This document describes how to do this. Widevine is part of a set of comprehensive content protection features that work together to provide you with the ability to secure your content. These features include: User Authentication through token-based options such as the Ooyala Secure Player Token. For information about setting up and using this feature, see Ooyala Player Token on page 12. Content Authorization through mechanisms such as Widevine. Information about Widevine is provided in this document. Authorization API which is a mechanism that handles all authorization requests. For more information about the Authorization API, see Player Authorization API on page 29. The content protection that Ooyala offers work standalone or in combination to provide multiple levels of content protection. Ooyala enables you to combine these features to create your content protection strategy. To learn about additional content protection features (such as Adobe Pass), contact Sales, your Customer Success Manager, or Technical Support. SUPPORTED PLATFORMS AND FORMATS If you want to have content that is DRM-protected with Widevine, you need to use the supported platforms formats appropriate for ios Apps, Android Apps, and Connected TVs. Platform Supported Formats Notes Android 2.x MP4 Android 2x does not support live streaming. Android 3.0+ MP4, WVM (VOD)HLS (Live) WVM is Widevine ABR. ios WVM (VOD) HLS (Live) Although MP4 is available, we should encourage customers to move away from using this format. ConnectedTVs and STBsSamsung 2010+LG2011+ WVM (VOD) HLS (Live)What the TV supports For apps that support WVM or HLS.Note that other Connected TVs and STBs may work but have not yet been tested by Ooyala. OOYALA AND WIDEVINE DRM WORKFLOW Customers who want Widevine need to work with Ooyala Customer Success Managers or professional services to enable Widevine support. When you use Ooyala s Widevine server, the licenses exist in the Widevine cloud. CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 63

64 With the implementation of Widevine DRM, each content viewer needs an individual license as the content is encrypted and is useless without license. Widevine does not perform the encryption, content from the CDN 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 the various parts of the Ooyala content protection features. The following diagram illustrates how Widevine is related to the Ooyala Player Token (an optional but recommended user authentication feature) and the Ooyala 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 Additional Documentation 1. The video player App, authenticates the user against the content provider. 2. The content provider provides an Ooyala Player Token to the app that indicates the authentication status of the user. 3. The video app makes an authorization request to Ooyala that includes the Ooyala Player Token. 4. Ooyala's authorization request returns a stream url and the authorization cookie. 5. Device native playback components will contact Ooyala for DRM licenses. 6. Ooyala provides the license to playback DRM content. App developers and content provider s services App developers and content provider s services App developers App developers Ooyala Ooyala Ooyala Player Token on page 12 Ooyala Player Token on page 12 Ooyala Player Token on page 12 and Player Authorization API on page 29 Player Authorization API on page 29 CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 64

65 USING WIDEVINE WITH OOYALA SDK-BASED APPS To use Widevine with our ios and Android players you need to download and use our Native SDKs to create the client-side pages. To download the Ooyala: Android SDK - ios SDK - Once you have downloaded the SDK, you should following the instructions in the package for implementing Android or ios apps. That s all you need as once you have the Widevine feature enabled, the Ooyala SDK-based apps should work seamlessly with Widevine. USING WIDEVINE WITH CONNECTED TVS If you want to use Widevine with connected TVs, you need to: 1. Implement Widevine in accordance with the device specific SDKs. You pre-configure your device SDK and Widevine set up according to the SDK instructions. 2. Initialize Widevine and the device SDK in the SDK-specific language (this will vary from device to device). Set up your app in accordance with the applicable platform programming guide. 3. You will make a call 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... video url drm server portal, provider, or owner id device id Provide... the stream URL Widevine server path in the Authorization response ooyala optional, unique identifier for the device, you generate the id AUTHORIZATION RESPONSE WITH WIDEVINE STREAM For an authorization response that include a widevine stream, an additional value named widevine_server_path is returned. This should be passed along with the stream url to the playback SDKs for obtaining the Widevine license and decrypting the token. "authorization_data": "hunwp2njocackrsv_wqbdcsw9p1xmlww":... "streams":[ "delivery_type":"wv_wvm", "url":..., "widevine_server_path":" lvcjaxoj82_rjliaj6jr8zzqgp-s/hunwp2njocackrsv_wqbdcsw9p1xmlww/widevine/ ooyala" ], CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 65

66 "debug_data":..., "signature":"fo6ewzq2ttrljrfmjo5eqpekuoolvhsen7kljrfu1yq=\n" PLAYREADY CONTENT PROTECTION Ooyala provides support for PlayReady to meet the content protection requirements for high-quality content online in on-demand and live streaming formats. PlayReady is a DRM technology by Microsoft, used to protect premium content from being viewed without a valid license. It is used in conjunction with Microsoft s Smooth Streaming protocol. Ooyala provides a set of comprehensive content protection features that work together to provide you with the ability to secure your content. PlayReady is supported in the Discretix variant and is only compatible with players that support this variant. We integrate with additional content protection technologies such as Microsoft PlayReady to provide a full range of DRM solutions. These content protection features include: Content Authorization through mechanisms such as our integration with PlayReady. Information about PlayReady is provided in this document. User Authentication through token-based options such as the Ooyala Secure Player Token. For information about setting up and using this feature, see the Ooyala Secure Player Token Guide. Authorization API which is a mechanism that handles all authorization requests. For more information about 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 and PlayReady content protection, you need to have a PlayReady library for your platform and/or understand how to use the Microsoft PlayReady SDK. This document describes how our systems work with PlayReady and is designed for software developers who want to create a custom player and use Ooyala services and the PlayReady content protection option. SUPPORTED PLATFORMS If you want to have content that is DRM-protected with PlayReady, you need to use the supported platforms formats appropriate for Microsoft PlayReady. Microsoft XBOXsupports Smooth Streaming formats. Other Connected TV (CTV) and similar devices To get a list of the requirements necessary for your CTV device to use PlayReady, check with your account manger. PlayReady Workflow The PlayReady Workflow describes the process needed to implement and initialize PlayReady content protection. If you want to use PlayReady, you need to: Implement PlayReady in accordance with the device specific SDKs that you are using to create your custom players. You pre-configure your device SDK and PlayReady set up according to the SDK instructions. Initialize PlayReady and the device SDK in the SDK-specific language (this will vary from device to device). 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 Success Manager or professional services to enable PlayReady support. With the implementation of PlayReady CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 66

67 DRM, each content viewer needs an individual license as the content is encrypted and is useless without a license. The following two diagrams illustrate how PlayReady is related to the Ooyala Player Token (an optional but recommended user authentication feature) and the Ooyala Authorization API that handles the user authentication 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 PlayReady license. The following table describes in greater detail the workflow steps, illustrated in the prior diagrams, that are necessary for using PlayReady for content protection. Your app needs to perform the following workflow: Step Activity Responsible Party Additional Documentation 1 The video player app, authenticates the user against the content provider and requests an Ooyala Player Token (OPT). 2 The content (identity) provider supplies an Ooyala Player Token to the video player app that indicates the authentication status of the user. App developers and content provider s services App developers and content provider s services Ooyala Player Token Guide Ooyala Player Token Guide CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 67

68 Step Activity Responsible Party Additional Documentation 3 The video player app makes an authorization request to Ooyala that includes two key pieces of data: the embed code. the Ooyala Player Token. 4 The video manifest is fetched using the stream URL. The response contains the stream URL for the video (this will be the manifest when using smooth streaming). 5 The PlayReady license is requested using the acquisition URL from the manifest. The auth_token must be included within the license request. 6 Ooyala provides the license to playback DRM content. App developers App developers App developers Ooyala Ooyala Player Token Guide and Authorization API Guide Authorization API Guide PlayReady Example A PlayReady reference implementation shows example code needed to implement and initialize PlayReady content protection. To assist you in creating the code for PlayReady DRM, Ooyala provides a reference implementation in a zip file that contains sample code in Silverlight. The sample contained in the PlayReady_SRC.zip file demonstrates one way of making a license request. You can get the PlayReady_SRC.zip file from your account manger. When creating the code necessary to make the appropriate authorization requests, at a high-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 request includes a valid Ooyala Player Token, the response will include an auth_token. This authorization token will look 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 the PlayReady Workflow. CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 68

69 USING THE SMOOTH STREAM CLIENT SDK You can use PlayReady with the Smooth Stream Client SDK, which you can download at ( A sample is available from your Customer Success Manager that illustrates how to use the IIS (Smooth Stream Client SDK) to playback smooth streams 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. 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 in the: '/soap:envelop/soap:body/aquirelicense/challenge/challenge/la/customdata' CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 69

70 The following example show how to include the auth_token in the license request for other client libraries: ``` <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" schemas.xmlsoap.org/soap/envelope/"> <soap:body> <AcquireLicense xmlns=" protocols"> <challenge> <Challenge xmlns=" messages"> <LA xmlns=" Id="SignedData" xml:space="preserve">... <CustomData>auth_token=foo</CustomData> </LA> </Challenge> </challenge> </AcquireLicense> </soap:body> </soap:envelope> ``` ADOBE ACCESS INTRODUCTION Ooyala supports Adobe Access DRM to deliver and protect premium video to Ooyala Flash-based players across desktop devices. With Adobe Access DRM, publishers, broadcasters, and content owners can deliver video to a variety of desktop devices with the confidence of secure DRM delivery. Ooyala includes Adobe Access as one of a set of comprehensive content protection features that work together to provide you with the ability to secure your premium content. The Adobe Access DRM solution allows you to deliver 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 to distribution. The DRM regime also employs configurable DRM policies to ensure your video content is protected with restrictions in accordance to your security policies and compliance rules. Ooyala also integrates with supplemental content protection technologies from User Authorization through authentication mechanisms such as our integration with Adobe Pass. You also have the option of adding Ooyala Secure Player Token (OPT). For detailed information about setting up and using this feature, see the Ooyala Player Token on page 12. SUPPORTED PLATFORMS AND FORMATS Flash Player for Web: For details, see Player Functional Support Across Environments. Desktops: Windows, Mac OS or Linux operating systems. For details, see Player Platform and Browser Support and Player System Requirements by Platform. Streaming protocol: HTTP Dynamic Streaming. CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 70

71 OOYALA AND ADOBE ACCESS DRM WORKFLOW For an overview of the content distribution workflow in Adobe Access, you can read the Adobe Learn Flash 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 using Transcoding 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 to the 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. You just need to have Adobe Access enabled for your account. Work with your Ooyala Customer Success Manager or technical support to enable Adobe Access for your account. You also have the option of enabling the Ooyala Player Token (OPT) authentication with Adobe Access DRM. For more information about using OPT, see the Ooyala Player Token documentation. CONFIGURABLE DRM Digital Rights Management (DRM) enables you to control how viewers consume and access your high value content through DRM policies. DRM policies can be set at the account or asset level. Ooyala DRM policies support three DRM technologies: Adobe Access, which is used to secure Flash playback Widevine, which is used for mobile devices. PlayReady is used when specifically set up for your account. With configurable DRM, your Customer Success Manager or Ooyala Support creates multiple DRM policies. Once enabled, you can assign any policy to any asset after ingestion. Then, you can change the policy for an asset at any time. For example, you might have new content to which you want to assign your most stringent DRM policy. After the content is no longer new and in high demand, you might choose to loosen 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 are determined at license issuance time and can include policies issued on a package or more commonly issued as policies enforced on output controls (such as enforcing no playback if HDCP is not present). In general 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": CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 71

72 "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_policy": "name":"sample_hd_policy", "license_duration":300, "digital_copy_protection":"stop_video", "encryption_mode_indicator":"copying_prohibited", "analog_protection_system":"agc_on, 4_line_split_burst_on", "constrained_image_trigger":"none", "hdcp":"on", "Analog_component_output_control":"analog_component_signal_output_allowed", "digital_component_output_control":"only_compressed_digital_signal_output", "region":"australia" Assigning DRM Policies Once 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 can assign 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 information about using the Scratchpad, see The Scratchpad. 2. Assign the DRM policy to an asset. [PUT]/v2/assets/IzNnllMjphu2XF3_UgPROoCi9B2rtWs/ drm_policy/86ff97ae7c81495eacbd9a01feff0f21 Backlot returns a 200 response. Note: CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 72

73 Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see The Scratchpad. 3. If you want to make a DRM policy the default for your account, you can assign the policy at the account level. [PUT]/v2/drm_policies/86ff97ae7c81495eacbd9a01feff0f21 Backlot returns a 200 response. Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see The Scratchpad. Deleting DRM Policies You 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 Backlot returns a 200 response. Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see The Scratchpad. 2. If you want to make a DRM policy the default for your account, you can assign the policy at the account level. For example: [DELETE]/v2/provider_drm_policy Backlot returns a 200 response. Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see The Scratchpad. CONTENT PROTECTION DEVELOPER GUIDE DIGITAL RIGHTS MANAGEMENT 73