Content Proxy

Welcome to Content Proxy! This repo contains the source code for building the verimatrixinc/content-proxy image.

What does this service do?

Content Proxy is an ExpressJs application meant to act as a Proxy for accessing Content authorization JSON Web tokens. The Content Proxy contains a default version of Entitlement Check middleware that always returns true such that all devices are entitled to content. It also contains a Token Generator middleware that generates a JSON Web Token that grants access to Content. The default version of Entitlement Check is meant to provide a sample implementation that can be overriden.

What is not included in this repo?

The repo comes with a default Entitlement Check that can be overriden with any custom entitlement check. There are no deployment scripts or infrastructure, these details are left to the user to deploy into their own container orchestration service. There is no secrets management and it is up to the user to secure their own private keys and secrets. This README file contains an example of (how to perform secrets management using AWS secrets manager)

How to use this Docker image

Running with only the required configurations

docker run \
  --env OPERATOR_KEY_ID="[key-id]" \
  --env OPERATOR_ISSUER="[issuer]" \
  --env OPERATOR_AUDIENCE="[audience]" \
  verimatrixinc/content-proxy

Running with additional optional configurations

docker run \
  --env OPERATOR_KEY_ID="[key-id]" \
  --env OPERATOR_ISSUER="[issuer]" \
  --env OPERATOR_AUDIENCE="[audience]" \
  --env SERVER_PORT="80" \
  --env DEFAULT_ENTITLEMENT_ENABLED="true" \
  verimatrixinc/content-proxy

Configurations explained

• Required
  • OPERATOR_KEY_ID - Identifies the key that will secure the token
  • OPERATOR_ISSUER - Identifies the issuer of the token
  • OPERATOR_AUDIENCE - Identifies the recipients that the token is intended for
• Optional
  • SERVER_PORT - Port where the authorization server will run (default: 80)
  • DEFAULT_ENTITLEMENT_ENABLED - Enable or disable default Entitlement Check, when enabled it will always return true, otherwise false

Verimatrix JSON Web Token Specification

Please refer to Verimatrix PROD-7310 JSON Web Token Specification for more information on how to configure key-id, issuer, and audience.

Secrets Management

One implementation that can be used to secure private keys and secrets is to use AWS Secrets Manager. This however can be done with any secrets management provider you may choose.

AWS Secrets Manager

Using a AWS account the secrets can be stored in the Secrets Manager Console. The data can then be read by the Content Proxy using an async function which calls AWS Secrets Manager and returns a secret value:

import * as AWS from "aws-sdk";

export async function getAwsSecret(secretId: string): Promise<string> {
  const secretsManager = new AWS.SecretsManager();
  const value = (await secretsManager.getSecretValue({ SecretId: secretId }).promise()).SecretString;

  if (!value) {
    throw new Error("Unable to retrieve value from Secrets Manager");
  }

  return value;
}

The secret values retrieved are a JSON object similar to this:

{
  "privateKey": "some private key",
  "secret": "some secret"
}

With the JSON Object, the user only needs to parse the response and use it to call the Token Generator middleware that will handle the actual generation of the Token:

fetchSecrets(config.get<string>('secretId')).then(secret =>
  const secretObj = JSON.parse(secret);
  app.use(tokenGenerator({ privateKey: secretObj.privateKey }))
  // server start logic
);

Default Entitlement Check

The Default Entitlement Check is a middleware designed to provide a basic skeleton for any custom Entitlement Checks. The Default Enititlement check will will always succeed and grant access to all devices, for all content.

The middleware is stored in the /middleware folder inside /default, and it's implemented in index.ts

if defaultEntitlement.enable is set to true:

if (config.get < boolean > "defaultEntitlement.enabled") app.use(defaultEntitlement());

Each request that is sent to the Content Proxy running will always succeed if the query parameters include a vdis and subject (deviceId and contentId), regardless of the values. Users are encouraged to create their own Entitlement Checks under /middleware and to plug them into the server the same way Default Entitlement Check is implemented

Recommended and tested load scenarios

Please review the load testing scenario and recommendations doc.

Local Development

• Requirements
  • node
  • yarn
• Optional
  • nvm

To Run Server Locally:

nvm use # use proper node version
yarn install # install dependencies
yarn start # start the server using nodemon

Any updates to the files within the ./src directory will trigger a restart of the server.

Configuration

Configuration is set using the "config" npm package. This provides a nice interface for setting default variables, with the ability to override per environment or with environment variables.