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:

Set up your account
Define restrictions
Associate restrictions with a video
Optional: Define user-level restrictions
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 account manager for details.

Generate OAuth credentials

Get your BC_TOKEN and account number.

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

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.

You should see a prompt appear that contains your BC_TOKEN

Request client credentials

Add accout permissions for the Playback Rights API.

Here is an example of an OAuth client request with the permissions needed.

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

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 example

Create playback right valid only for Australia.

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"
    ]
  }
}'

API Response

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:

Field	Type	Description
`allowed_countries`, `blocked_countries`	String	Array of two letter country codes, which follow the ISO 3166-1 alpha-2 standard. For a list of values, see the Officially assigned code elements.
`allowed_zip_codes`, `blocked_zip_codes`	String	Array of zip codes, which are prefixed with the two letter country and hyphen. e.g. `["US-90045"]`. The two letter country code must be upper case and follow the ISO 3166-1 alpha-2 standard, as shown in the Officially assigned code elements.
`allowed_dmas`, `blocked_dmas`	Integer	Array of Nielsen Designated Market Area (DMA) numbers. For a list of values, see the DMA Codes document.
`blocked_proxies: anonymous`	Boolean	IP address of the client is not available. Includes services that change location to beat DRM, TOR points, temporary proxies, and other masking services.
`blocked_proxies: public`	Boolean	Multiple users proxied from a location allowing public internet access.
`blocked_proxies: corporate`	Boolean	Generally considered harmless, but location can be a concern. Identify if multiple users are proxied through a central location or locations, and can share a single network-apparent IP address.
`blocked_proxies: transparent`	Boolean	IP address of the client is available via HTTP headers, though the value is not necessarily reliable (e.g., it can be spoofed).
`allowed_domains`, `blocked_domains`	String	Array of domain names
`start_time`, `end_time`	Integer	Epoch time
`allowed_ips`, `blocked_ips`	Integer	Array of ipv4/ipv6 addresses or CIDR blocks.
`allowed_days`	String	Array of 3-letter lowercase names for the days that the resource is allowed to be retrieved. One or more of: `mon, tue, wed, thu, fri, sat, sun`
`allowed_hours`	Integer	Array of hours from the 24-hour clock (starting at 0 and up to 47) during which the resource is allowed to be retrieved. 0 to 23 for current day, and 24 to 47 for next day end-date. If an allowed hours block starts in previous day and ends at the following day then a 24+ notation is required. Example: the value of `3-4` in this header means that the resource is available from 3:00 am UTC to 3:59 am UTC
`allow_insecure`	Boolean	Default: `false` Setting this to `true` makes the JWT token optional.
`disabled`	Boolean	Default: `false` Setting this to `true` disables the Playback Right, allowing playback for everyone.
`name`	String	Optional playback right name

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/{account_id}/videos/{video_id}
  Content-Type: application/json
  Body: {video object}

Curl example

Add a playback_rights_id to a video.

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/{account_id}/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:

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.

You are limited to an array of 40 tags in the JWT token.
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}

Implementing Playback Rights Management Service

Introduction

Validation process

Workflow

Set up your account

Generate OAuth credentials

Request client credentials

Define restrictions

Playback Rights API

Base URL

Account path

Authorization

Permissions

Manage restrictions

Create new playback rights

Curl example

API Response

Get all playback rights for an account

Get a specific playback right for an account

Update a specific playback right:

Delete a specific playback right:

Request body

Associate restrictions with a video

CMS API

Base URL

Account path

Authorization

Permissions

Manage restrictions

Update a video:

Curl example

Get a specific video:

Define user-level restrictions

Steps

Determine restrictions

Device limits

Concurrent stream limits

Tags

Create a JSON Web Token

Configure your player

Web player

Native Android player

Native iOS player

Your own player

Related topics