ÃÛ¶¹ÊÓƵ

Media Tokens media-tokens

IMPORTANT
The content on this page is provided for information purposes only. Usage of this API requires a current license from ÃÛ¶¹ÊÓƵ. No unauthorized use is permitted.

The media token is a token generated by ÃÛ¶¹ÊÓƵ Pass Authentication REST API V2 as a result of an authorization decision meant to provide viewing access to protected content (resource).

The media token is valid for a limited and short timeframe (default 7 minutes) specified at the moment of issue, indicating the time limit before it must be verified and used by the client application. The media token is restricted to one-time use and must never be cached.

The media token consists of a signed string based on Public Key Infrastructure (PKI) sent in clear text. With the PKI-based protection, the token is signed using an asymmetric key issued to ÃÛ¶¹ÊÓƵ by a Certification Authority (CA).

The media token is passed to the Programmer, which then can validate it using the Media Token Verifier before starting the video stream to ensure the security of access for that resource.

The Media Token Verifier is a library distributed by ÃÛ¶¹ÊÓƵ Pass Authentication that is responsible for verifying the authenticity of a media token.

Media Token Verifier media-token-verifier

ÃÛ¶¹ÊÓƵ Pass Authentication recommends that Programmers send the media token to their own backend service integrating the Media Token Verifier library to ensure secure access before initiating the video stream. The media token’s time-to-live (TTL) is designed to account for potential clock synchronization issues between the token-generating server and the validating server.

ÃÛ¶¹ÊÓƵ Pass Authentication strongly advices against parsing the media token and directly extracting its data, as the token format is not guaranteed and may change in the future. The Media Token Verifier library should be the sole tool used to analyze the token’s content.

The Media Token Verifier library can be downloaded from the following link:

  • https://tve.zendesk.com/hc/en-us/articles/204963159-Media-Token-Verifier-library

The Media Token Verifier library requires JDK version 1.5 or higher and supports the use of a preferred Java Cryptography Extension (JCE) provider for the signature algorithm (SHA256WithRSA).

The Media Token Verifier library represented by the mediatoken-verifier-VERSION.jar Java archive includes:

  • ÃÛ¶¹ÊÓƵ public key.
  • Token verification API (ITokenVerifier.java).
  • Reference implementation (com.adobe.entitlement.test.EntitlementVerifierTest.java).
  • Dependencies and certificate keystores.
IMPORTANT
The default password for the included certificate keystore is 123456.

Methods methods

The ITokenVerifier class defines the following methods:

  • The isValid() method used to validate the media token. It accepts a single argument, the resource identifier. If the provided resource identifier is null, the method will validate only the media token’s authenticity and validity period.

    The isValid() method returns one of the following status values:

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
    VALID_TOKEN Token validations succeeded
    INVALID_TOKEN_FORMAT Token format is invalid
    INVALID_SIGNATURE Token authenticity could not be validated
    TOKEN_EXPIRED Token TTL is not valid
    INVALID_RESOURCE_ID Token not valid for given resource
    ERROR_UNKNOWN Token has not been validated yet
  • The getResourceID() method used to retrieve the resource identifier associated with the media token and compare it to the identifier returned from the authorization decision response.

  • The getTimeIssued() method used to retrieve the time when the media token was issued.

  • The getTimeToLive() method used to retrieve the TTL of the media token.

  • The getUserSessionGUID() method used to retrieve an anonymized GUID set by the MVPD.

  • The getMvpdId() method used to retrieve the identifier of the MVPD which authenticated the user.

  • The getProxyMvpdId() method used to retrieve the identifier of the Proxy MVPD which authenticated the user.

Sample sample

The Media Token Verifier archive contains a reference implementation (com.adobe.entitlement.test.EntitlementVerifierTest.java) and an example of invoking the API with the test class. This sample (com.adobe.entitlement.text.EntitlementVerifierTest.java) illustrates the integration of the Media Token Verifier library into a media server.

package com.adobe.entitlement.test;

import com.adobe.entitlement.verifier.CryptoDataHolder;
import com.adobe.entitlement.verifier.ITokenVerifier;
import com.adobe.entitlement.verifier.ITokenVerifierFactory;
import com.adobe.entitlement.verifier.SimpleTokenPKISignatureVerifierFactory;
import com.adobe.tve.crypto.SignatureVerificationCredential;
import java.io.InputStream;

public class EntitlementVerifierTest {
    String mRequestorID = null;
    String mTokenToVerify = null;
    String mPathToCertificate = null;
    String mKeystoreType = null;
    String mKeystorePasswd = null;
    String mResourceID = null;

    public static void main(String[] args) {
        if (args == null || args.length < 2 ) {
            System.out.println("Incorrect args: Usage: EntitlementVerifierTest requestorID tokenToVerify [resourceID]");
            return;
        }
        String requestorID = args[0];
        String tokenToVerify = args[1];
        String pathToCertificate = "media_token_keystore.jks"; // the default keystore provided in the entitlement jar
        String keystoreType = "jks";
        String keystorePasswd = "123456"; // password for the default keystore
        if (requestorID == null || tokenToVerify == null) {
            System.out.println("One or more arguments is null");
            return;
        }
        System.out.println("RequestorID: " + requestorID);
        System.out.println("token: " + tokenToVerify);
        System.out.println("cert: " + pathToCertificate);
        System.out.println("keystoretype: " + keystoreType);
        System.out.println("keystore passwd: " + keystorePasswd);
        String resourceID = null;
        if (args.length > 2) {
            resourceID = args[2];
        }
        System.out.println("Resource ID: " + resourceID);
        EntitlementVerifierTest verifier = new EntitlementVerifierTest(requestorID,
            tokenToVerify, pathToCertificate, keystoreType, keystorePasswd, resourceID);
        verifier.verifyToken();
    }

    protected EntitlementVerifierTest(String inRequestorID,
                                      String inTokenToVerify,
                                      String inPathToCertificate,
                                      String inKeystoreType,
                                      String inKeystorePasswd, String inResourceID) {
        mRequestorID = inRequestorID;
        mTokenToVerify = inTokenToVerify;
        mPathToCertificate = inPathToCertificate;
        mKeystoreType = inKeystoreType;
        mKeystorePasswd = inKeystorePasswd;
        mResourceID = inResourceID;
    }

    protected void verifyToken() {
        // It is expected that the SignatureVerificationCredential and
        // CryptoDataHolder could be created at Init time in a web application
        // and be reused for all token verifications.
        CryptoDataHolder cryptoData = createCryptoDataHolder(mPathToCertificate, mKeystoreType, mKeystorePasswd);
        ITokenVerifierFactory tokenVerifierFactory = new SimpleTokenPKISignatureVerifierFactory();
        ITokenVerifier tokenVerifier = tokenVerifierFactory.getInstance(mRequestorID, mTokenToVerify, cryptoData);
        ITokenVerifier.eReturnValue status = tokenVerifier.isValid(mResourceID);
        System.out.println("Is token Valid? : " + status.toString());
        System.out.println("Token User ID: " + tokenVerifier.getUserSessionGUID());
        System.out.println("Token was generated at: " + tokenVerifier.getTimeIssued());

        System.out.println("Token Mvpd ID: " + tokenVerifier.getMvpdId());
        System.out.println("Token Proxy Mvpd ID: " + tokenVerifier.getProxyMvpdId());
    }

    protected CryptoDataHolder createCryptoDataHolder(String pathToCertificate,
                                                      String keystoreType, String keystorePasswd) {
        SignatureVerificationCredential verificationCredential =
            readShortTokenVerificationCredential(pathToCertificate, keystoreType, keystorePasswd);
        CryptoDataHolder cryptoData = new CryptoDataHolder();
        cryptoData.setCertificateInfo(verificationCredential);
        return cryptoData;
    }

    protected SignatureVerificationCredential readShortTokenVerificationCredential(String keystoreFile,
                                                                                   String keystoreType,
                                                                                   String keystorePasswd) {
        SignatureVerificationCredential cred = null;
        if (keystoreFile != null){
            try {
                // load the keystore file
                ClassLoader loader = EntitlementVerifierTest.class.getClassLoader();
                InputStream certInputStream =  loader.getResourceAsStream(keystoreFile);
                if (certInputStream != null) {
                    cred = new SignatureVerificationCredential(certInputStream, keystorePasswd, keystoreType);
                }
            }
            catch (Exception e) {
                System.out.println("Error creating short token server credentials: " + e.getMessage());
            }
        }
        if (cred == null) {
            System.out.println("Error creating short token server credentials");
        }
        return cred;
    }
}

REST API V2 rest-api-v2

The media token can be retrieved using the following API:

Refer to the Response and Samples sections of the above API to understand the structure of authorization decisions and media tokens.

IMPORTANT
The client application does not need to query a separate endpoint to retrieve the media tokens, as they are already included in the authorization decisions that permit user access.

For more details about how and when to integrate the above API, refer to the following document:

recommendation-more-help
3f5e655c-af63-48cc-9769-2b6803cc5f4b