Using Playback Authorization DRM with the Native SDKs

In this topic, you will learn how to use Brightcove's Playback Authorization Service to retrieve videos ingested for Dynamic Delivery with the Brightcove Native SDKs.

Introduction

Brightcove's Playback Authorization Service (PAS) offers an extra level of security when using Dynamic Delivery with DRM-protected or HTTP Live Streaming Encryption (HLSe) content.

With PAS, license requests will be authenticated using a signed JSON Web Token (JWT).

It is used when requesting the video license, once the video has been loaded to the player and the source has been selected.

For more information about PAS, see the Overview: DRM with Playback Authorization Service document.

Android Implementation

The Native SDK for Android currently supports PAS for HLSe and Widevine DASH sources. You will provide your authorization token as part of the Brightcove catalog request for a single video or a playlist.

To make a Brightcove catalog request using PAS, follow these steps:

  1. Create an HttpRequestConfig object and set the Brightcove Authorization token as shown here: 

    HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
       .setBrightcoveAuthorizationToken(myToken)
       .build();

    The value of the Authorization token will be the value of your JSON Web Token.

  2. Once you have created the HttpRequestConfig object, you can pass that to one of the following Catalog methods:

    For a video request, use one of the following: 

    findVideoByID(String, HttpRequestConfig, VideoListener)

    findVideoByReferenceID(String, HttpRequestConfig, VideoListener)

    For a playlist request, use one of the following: 

    findPlaylistByID(String, HttpRequestConfig, PlaylistListener)

    findPlaylistByReferenceID(String, HttpRequestConfig, PlaylistListener)

    The details of token usage for HLSe and Widevine license acquisition are handled by the SDK.

Code example

The following example shows how to pass your authorization token when making a Catalog request: 

String myToken = "...";
HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
       .setBrightcoveAuthorizationToken(myToken)
       .build();
…

Catalog catalog = new Catalog(eventEmitter, accountId, policyKey, playbackApiBaseUrl);
catalog.findVideoByReferenceID(videoReferenceId, httpRequestConfig, new VideoListener(){...});

Offline Playback

The OfflineCatalog findVideo, requestPurchaseLicense and requestRentalLicense methods all take an HttpRequestConfig as an argument. 

private HttpRequestConfig httpRequestConfig;
private String pasToken = "YOUR_PAS_TOKEN";
...
HttpRequestConfig.Builder httpRequestConfigBuilder = new HttpRequestConfig.Builder();
httpRequestConfigBuilder.setBrightcoveAuthorizationToken(pasToken);
httpRequestConfig = httpRequestConfigBuilder.build();
playlist.findPlaylist(catalog, httpRequestConfig, new PlaylistListener() {
    @Override
    public void onPlaylist(Playlist playlist) {
        videoListAdapter.setVideoList(playlist.getVideos());
        onVideoListUpdated(false);
        brightcoveVideoView.addAll(playlist.getVideos());
    }

    @Override
    public void onError(String error) {
        String message = showToast("Failed to find playlist[%s]: %s", playlist.displayName, error);
        Log.w(TAG, message);
        onVideoListUpdated(true);
    }
});

For details, see the Offline Playback sample app.

Responses

The following responses are associated with PAS:

  • 200 - License is allowed to continue
  • 401 - The License delivery must not be allowed to continue

Limitations

There is a limitation with the current release:

  • Chromecast is not supported with Playback Authorization.

iOS Implementation

When using Brightcove's Playback Authorization Service, you will need to use the playback service methods that allow you to pass in your authorization token.

For a video request, use one of the following: 

- (void)findVideoWithVideoID:(NSString *)videoID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

- (void)findVideoWithReferenceID:(NSString *)referenceID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

For a playlist request, use one of the following: 

- (void)findPlaylistWithPlaylistID:(NSString *)playlistID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;

- (void)findPlaylistWithReferenceID:(NSString *)referenceID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;

The details of token usage for HLSe and FairPlay license acquisition are handled by the SDK.

For details, see the Playback Authorization Service section of the Native SDK for iOS reference.

Offline Playback

If you are using the Playback Authorization Service with Offline Playback, there is a new method for renewing a FairPlay license which accepts an authorization token: 

// Request license renewal
    [BCOVOfflineVideoManager.sharedManager renewFairPlayLicense:offlineVideoToken
        video:video // recent video from Playback API or Playback Service class
        authToken: authToken
        Parameters: parameters
        completion:^(BCOVOfflineVideoToken offlineVideoToken, NSError *error)
    {
        // handle errors
    }];

When license renewal is finshed, the completion block will be called with the same offline video token that was passed in. An NSError will indicate any problem that occurred (or nil if no error).

For details, see the Renewing a FairPlay License section of the Native SDK for iOS reference.

Responses

The following responses are associated with PAS:

  • 200 - License is allowed to continue
  • 401 - The License delivery must not be allowed to continue