Implementing Playback Rights Management Service

Introduction

Brightcove's Playback Rights Management Service provides a scalable and expressive way to manage video playback.

If you are not familiar with this feature, see the Overview: Managing Playback Rights document.

Validation process

Playback rights are applied in order of specificity and matching. An allow rule negates the rest of the rules since they are less specific than the one allowing the rule.

You may want to allow a specific ip to avoid a country rule for that ip. You may also want to block a different ip that would normally be allowed by the country restriction. So, it can make sense to have both block-ips and allow-ips in the same playback rights definition. The same holds true for other rules.

You can have allow and block rules for most rights. Countries is the only one where it might not make sense to have both.

The following flow diagrams show how the validation process works.

Workflow

To manage playback restrictions, follow these steps:

1. Set up your account
2. Define restrictions
3. Associate restrictions with a video

4. Optional: Define user-level restrictions

5. Configure your player

Set up your account

This feature is available for a specific set of customers with access to the Limited Availability phase of the Playback Rights Management Service. Contact your Customer Success Manager for details.

Generate OAuth credentials

Get your BC_TOKEN and account number.

1. Log into Video Cloud Studio. In the Admin dropdown, select Account Information. Copy your Account ID.

2. With any page in Studio open, open the developer tools for the browser, go to the Console, and paste in the following code:

   var cookiesArray = document.cookie.split(";"), cookiesObj = {}, i, tmpArray = [];
   for (i = 0; i < cookiesArray.length; i++) {
       tmpArray = cookiesArray[i].split("=");
       if (tmpArray[0].indexOf('BC_TOKEN') > -1) {
           cookiesObj.BC_TOKEN = tmpArray[1];
       }
   }
   window.prompt("BC_TOKEN:", cookiesObj.BC_TOKEN);

   and press return.

3. You should see a prompt appear that contains your BC_TOKEN

Request client credentials

Add account permissions for the Playback Rights API.

1. The simplest way to create client credentials for the Playback Rights API is to use this online app and ensure that you include these permissions when you create the credentials:

   

2. If you prefer generating your credentials using the OAuth API directly, continue with the following steps.

3. Here is an example of an OAuth client request with the permissions needed. See Getting your BC_TOKEN for information on getting your BC_TOKEN.

   curl \
     --include \
     --header "Authorization: BC_TOKEN your BC_TOKEN" \
     --data {
       name=demo&maximum_scope=[{
         "identity": {
           "type": "video-cloud-account",
           "account-id": your account id
         },
         "operations": [
           "video-cloud/playback-auth/playback-rights/read",
           "video-cloud/playback-auth/playback-rights/write",
           "video-cloud/video/read",
           "video-cloud/video/create",
           "video-cloud/video/update",
           "video-cloud/video/delete",
           "video-cloud/playback-auth/key/read",
           "video-cloud/playback-auth/key/write"
         ]
     }]
   } \
   https://oauth.brightcove.com/v4/client_credentials

4. From the API response, copy the client_id and client_secret. You will use these to generate an access token when making requests to the Playback Rights API.

Define restrictions

Use the Playback Rights API to define video playback restrictions.

Playback Rights API

Each playback rights restriction object can be used with one or more videos.

Base URL

The base URL for the API is:

https://playback-rights.api.brightcove.com/v1

Account path

In all cases, requests will be made for a specific Video Cloud Account. So, you will always add the term accounts followed by your account id to the base URL:

https://playback-rights.api.brightcove.com/v1/accounts/{accountID}

Authorization

An access token for requests is required and must be present in the Authorization header::

Authorization: Bearer {access_token}

The access token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

Permissions

Requests to the Playback Rights API must be made from client credentials with the following permissions:

• video-cloud/playback-auth/playback-rights/read
• video-cloud/playback-auth/playback-rights/write

Manage restrictions

The Playback Rights API supports the following requests. For API details, see the Playback Rights API Reference.

Create new playback rights

POST /v1/accounts/{accountID}/playback_rights
  Content-Type: application/json
  Body: {playback rights object}

For a list of valid fields, see the Request body section.

curl -X POST \
  https://playback-rights.api.brightcove.com/v1/accounts/{your_account_id}/playback_rights \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "geo": {
    "allowed_countries": [
      "AU"
    ]
  }
}'

Save the playback_rights_id value for later use. You can find this value in the API response. Either:

• Response header:

  The playback_rights_id value can be found in the Location field of the Header response. It should be similar to this:

  Location: /v1/accounts/your account_id/playback_rights/your playback_rights_id
      

• Response body

  The playback_rights_id value can be found in the response body as the id field. It should be similar to this:

  {
    "id": "your playback_rights_id",
    "geo": {
    "allowed_countries": [
      "MX",
      "US"]
  }

Get all playback rights for an account

GET /v1/accounts/{accountID}/playback_rights

Get a specific playback right for an account

GET /v1/accounts/{accountID}/playback_rights/{playbackRightsID}

Update a specific playback right:

PUT /v1/accounts/{accountID}/playback_rights/{playbackRightsID}
  Content-Type: application/json
  Body: {playback rights object}

For a list of valid fields, see the Request body section.

Delete a specific playback right:

DELETE /v1/accounts/{accountID}/playback_rights/{playbackRightsID}

Request body

Here is an example of all of the fields you can include in the request body:

{
  "geo": {
  "allowed_countries": [
    "MX",
    "US"
  ],
  "blocked_countries": [
    "JP",
    "CN"
  ],
  "allowed_zip_codes": [
    "US-90210"
  ],
  "blocked_zip_codes": [
    "US-72810"
  ],
  "allowed_dmas": [
    501
  ],
  "blocked_dmas": [
    803
  ]
},
"blocked_proxies": {
  "anonymous": true,
  "public": true,
  "corporate": true,
  "transparent": true
},
"allowed_domains": [
  "www.google.com",
  "www.brightcove.com"
],
"blocked_domains": [
  "www.ooyala.com"
],
"start_time": 1572905011,
"end_time": 1672905011,
"allowed_ips": [
  "192.168.1.1"
],
"blocked_ips": [
  "192.168.1.1"
],
"allowed_days": [
  "mon",
  "tue"
],
"allowed_hours": [
  "5-6"
],
"allow_insecure": true,
"disabled": false,
"name": "Optional playback right name"
}

Here are the field details:

Associate restrictions with a video

Use the CMS API to associate a Playback Rights id with a video. You'll use the Playback Rights id that you created in the previous step.

CMS API

Each playback rights restriction object can be used with one or more videos.

Base URL

The base URL for the API is:

https://cms.api.brightcove.com/v1

Account path

In all cases, requests will be made for a specific Video Cloud Account. So, you will always add the term accounts followed by your account id to the base URL:

https://cms.api.brightcove.com/v1/accounts/{accountId}

Authorization

An access token for requests is required and must be present in the Authorization header::

Authorization: Bearer {access_token}

The access token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

Permissions

Requests to the Playback Rights API must be made from client credentials with the following permissions:

• video-cloud/video/read
• video-cloud/video/update

Manage restrictions

The CMS API supports the many request types. To update a video, use the following:

Update a video:

Associate a playback_rights_id with a video. This id should exist in the Playback Rights API, which you created in the previous step.

PATCH /v1/accounts//videos/
  Content-Type: application/json
  Body: {video object}

curl -X PATCH \
  https://cms.api.brightcove.com/v1/accounts/your account_id/videos/your video_id \
  -H 'Authorization: Bearer your access_token' \
  -H 'Content-Type: application/json' \
  -d '{
	"playback_rights_id": "your playback_rights_id"
}'

Get a specific video:

GET /v1/accounts//videos/{video_ids}

For complete details about using the API, see the CMS API Reference.

Define user-level restrictions

If you want user-level restrictions, you will need a JSON Web Token (JWT) configured with claims associated with your restrictions.

Steps

To create a JSON Web Token (JWT) to pass to your player, follow these steps:

1. Determine restrictions

   Determine the type of user-level restrictions you want to use from the list below. Include the necessary JWT claims when you create your JSON Web Token (JWT).

   Device limits

   When a DRM license request is made, the user's device is registered and a unique id is assigned. The device limit is checked and enforced with each license request. To use this restriction, generate a JWT with the current user id (uid).

   For details, see the Implementing Device Limits document.

   Concurrent stream limits

   When a DRM license request is made, the user's device is registered and a unique id is assigned. With each license request, the device id is checked to ensure it is only watching a specified number of video streams at the same time.

   For details, see the Limiting Concurrent Streams per Viewer document.

   Tags

   Based on the tags claim, the JSON Web Token (JWT) will specify the group of videos that the user is entitled to watch. You can group videos with tags using the Media Module in Brightcove's Video Cloud Studio.

   The Playback Authorization Service will check the tags associated with each video. If at least one of the tags matches the list in the JWT token, then the video is viewable.

   Tags in the JWT token will be listed as an array of tags.

2. Create a JSON Web Token

   To create a token to use when communicating with Brightcove's Playback API, see the Creating a JSON Web Token (JWT) document.

Configure your player

By default, the Brightcove Player talks to the Brightcove Playback API (PAPI). A new system to manage playback restrictions sits in front of the Playback API. To configure your player, see the following:

Web player

To configure the Brightcove web player, see the Using Playback Rights with Brightcove Player document.

Native Android player

To configure the native player for Android, see the Using Playback Rights with the Native SDKs document.

Native iOS player

To configure the native player for iOS, see the Using Playback Rights with the Native SDKs document.

Your own player

If your content is in the Video Cloud library, but you are using your own player, you can make calls to the Playback API as shown in the Overview: Playback API document. Replace the base URL with the following:

https://edge-auth.api.brigthcove.com

Instead of using a Policy Key, you will use the JWT token for authentication:

Authorization: Bearer {JWT}

Here is a Curl example:

curl -X GET \
-H 'Authorization: Bearer {JWT}' \
https://edge-auth.api.brightcove.com/playback/v1/accounts/{your_account_id}/videos/{your_video_id}

Related topics

• Overview: Playback Rights Management Service
• Using Playback Rights with Brightcove Player
• Using Playback Rights with the Native SDKs
• Implementing Stream Concurrency
• Playback Rights Error Reference