Media Tokens media-tokens
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.
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 isnull
, 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.
For more details about how and when to integrate the above API, refer to the following document: