Prevent unauthorized distribution

This page briefly describes the options that Media CDN provides to help prevent unauthorized distribution of your content.

Media CDN offers the following options to help protect your content from unauthorized distribution.

  • Tokens (recommended approach): Media CDN uses tokens to help protect content.

    A token is a medium of exchanging signed requests, such as a signed cookie, a URI with query parameters, or a path component. Valid tokens presented by viewers are used to authenticate access to your content. A viewer with an invalid token or a missing token is prevented from accessing your content.

    You can choose to use either single-token or dual-token authentication. Tokens are required for dual-token authentication.

    When dual-token authentication is used, Media CDN uses two tokens, a short-duration token and a long-duration token.

    Google recommends tokens for new integrations because they offer the following advantages:

    • Provide compatibility with non-Google content delivery networks (CDNs).
    • Support path-only signing.
    • Enable signing multiple headers.
    • Offer granular access control and revocation.
    • Minimize the impact of compromised tokens.
    • Can embed arbitrary data and session IDs.

  • Signatures: Media CDN uses a single signature to help protect content. Signatures let you do full URL signing, including the host and protocol.

You can use both options together to help protect your content.

How dual-token authentication works

Dual-token authentication uses two tokens to authenticate requests to your content: a short-duration token for playback initiation, and a long-duration token for the remainder of the playback session.

To use dual-token authentication, you configure your application server to issue short-duration tokens to user agents. Then, you configure Media CDN to respond to the short-duration tokens. You can place the token in a query parameter of your choosing, or place the token in a cookie. For more information, see Use dual-token authentication.

Short-duration tokens generated by your application server help protect primary manifests (sometimes called multivariant playlists). The expiration of the signed request is short enough to request a primary manifest, but not to watch all of the content contained within a manifest.

When Media CDN receives a request with an authorized short-duration token, it generates a signed long-duration token. You can use the token in either a single-named query parameter or in a cookie. The long-duration token supports viewing a full-length program. The signed long-duration tokens generated by Media CDN use Ed25519 signatures that are signed with Google-managed keys associated with an EdgeCacheKeyset resource.

You can customize the expiration time of short- and long-duration tokens. As a best practice, Google recommends that you configure the expiration time of short-duration tokens generated on your application server to one minute. You must set the expiration time of long-duration tokens that Media CDN generates to a duration greater than your content length, up to a maximum of one day.

Request flow for dual-token authentication

The following describes the request flow:

  1. A viewer requests metadata from your application server for media they want to view. Your application server returns the URI of the primary manifest signed with a short-duration token.

  2. Your player application requests the primary manifest from Media CDN. The request includes the short-duration token as a value of a URI query parameter in the single-named query parameter format.

  3. Media CDN verifies the short-duration token and the token's signed parameters.

    1. If the token is valid, Media CDN creates a long-duration signature token. Media CDN returns the token either in a Set-Cookie header, or by modifying manifest and segment URIs in the primary manifest to include the token.
    2. If the token isn't valid, Media CDN responds with an HTTP 403 Forbidden response.

  4. The player application receives the primary manifest from Media CDN, then requests the media playlist or the media segments referenced in the primary manifest. The request must include the long-duration token, either as a signed cookie or as a URI parameter.

  5. Media CDN verifies the long-duration signature token:

    1. If the long-duration token is valid for the specific request, then Media CDN serves the requested content.
    2. If the long-duration token isn't valid (due to either an expired token or an invalid path), then Media CDN responds with an HTTP 403 Forbidden response.

  6. The process repeats until media playback ends or the long-duration signature expires.

Supported token formats for dual-token signed requests

Media CDN dual-token signed requests support multiple formats, depending on the token type.

Short-duration signed requests

For short-duration signed requests, Media CDN supports tokens signed with Ed25519 signatures by default. You can also use symmetric-key hash-based message authentication codes (HMACs) for compatibility with existing application code and other CDNs.

To use HMACs, you use Secret Manager to store the HMAC secret. Then you grant access to the Media CDN service account to access the stored secret. As a best practice, Google recommends using asymmetric signing with Ed25519 signatures for security and performance.

The Media CDN service account is owned by the Media CDN project, and isn't displayed in your project's list of service accounts. The service account grants access only to Media CDN resources in the projects that you explicitly allow.

The service account has the following format:

service-PROJECT_NUMBER@gcp-sa-mediaedgefill.iam.gserviceaccount.com

Where PROJECT_NUMBER is your project number.

To activate the service Media CDN service account, create at least one Media CDN resource, such as EdgeCacheOrigin.

Long-duration signed requests

For long-duration signed requests, Media CDN uses Ed25519 signatures that are signed with Google-managed keys associated with an EdgeCacheKeyset resource.

Media CDN supports a single token format for long-duration tokens, which can be used in either a single-named query parameter for HLS streams, or in a cookie.

How signed requests work

A signed request uses signatures or tokens to verify that every viewer is authenticated to access content. You can configure Media CDN so that the access is scoped to any of the following:

  • Either an exact URI or URI prefix for a limited time
  • A specific client
  • For signed requests using tokens, up to five paths with wildcards

To use signed requests, you generate keys to sign and verify signatures. You then configure routes, which let you optimize behavior based on the type of content, client attributes, and your freshness requirements. Signed requests can be enforced on a per-route basis, which helps you protect specific endpoints.

Each Media CDN service can use a collection of multiple keys. The collection of keys is also known as a keyset. Keysets let you rotate keys and distribute private keys across your own infrastructure without interruption.

You can configure Media CDN to use either signed requests or tokens to help protect content.

For signed requests using tokens, you can place the token in either of the following:

  • In a query parameter of your choosing
  • In a cookie

For more information, see Generate tokens.

For signed requests using signatures, you can use any of the following formats:

  • An exact URI with query parameters: You specify a URLPrefix with the exact URI and append the same query parameters to multiple URIs.
  • A URI prefix with query parameters: You specify a URLPrefix with a URI prefix and append the same query parameters to multiple URIs.
  • A path component: You specify a path component, which lets relative manifest URIs inherit the signed URI component.
  • A signed cookie: You specify a URI prefix in a cookie, which allows access to any URI with the prefix that you specified.

For more information, see Generate signatures.

Considerations

The following sections discuss various factors to consider to help prevent the unauthorized distribution of your content.

Security considerations

Media CDN validates all requests that match a route configured with a cdnPolicy.signedRequestMode of REQUIRE_SIGNATURES or REQUIRE_TOKENS.

We recommend that you validate requests at your origin. Although Media CDN rejects invalid and unsigned requests for a route that requires signatures, clients might find a way to access your origin directly. An additional layer of validation helps provide a defense-in-depth approach to protecting your content.

The following table explains scenarios when Media CDN validates a request:

Request has signature Signature valid? signedRequestMode Behavior Status code
No N/A REQUIRE_SIGNATURES or REQUIRE_TOKENS Requests without signatures or tokens are treated as if the signature is invalid. HTTP 403
Yes No REQUIRE_SIGNATURES or REQUIRE_TOKENS A signature or token is considered invalid if it has expired or has a mismatched URL or incorrect key. Invalid signatures or tokens are rejected at the CDN edge. HTTP 403
Yes Yes REQUIRE_SIGNATURES or REQUIRE_TOKENS A signature or a token is validated, and the response is served with content from a cache or the origin. HTTP 200
Yes Yes None or DISABLED No validation is performed, and a response is served to the user directly. HTTP 200
Yes No None or DISABLED No validation is performed, and a response is served to the user directly. HTTP 200

When your application detects an invalid signature, make sure that your application responds with an HTTP 403 (Forbidden) status code. HTTP 403 status codes aren't cacheable.

If your application sends a cacheable status code to an invalid request, valid future requests might be incorrectly rejected.

URI limits

Most modern HTTP clients support URIs up to 8000 characters long. However, some legacy or niche devices may have stricter limits. In general, a signed URI adds about 125 characters to the request URI, which includes the following:

  • If all field names are used, approximately 67 characters for each field (such as Expires= and KeyName=).
  • For the Unix timestamp, 10 characters
  • For the KeyName, five characters
  • For the base64-encoded Signature value, 43 characters

As a best practice, keep URIs less than 2000 characters long using query parameters as tokens. Shorter URIs prevent devices from sending truncated URIs to Media CDN.

Legacy video streaming devices

Some legacy video streaming devices may not fully support attaching cookies to manifest or media segment requests. If you have devices with known issues handling HTTP cookies, configure Media CDN to use query parameters for signed requests and dual-token exchange.

You're solely responsible for any consent and privacy compliance required when using cookies to exchange short-duration tokens. When Media CDN is configured to use dual-token signed requests, Google issues and manages the cookies used for long-duration tokens.

Billing

To learn more about how Secret Manager is billed, see Pricing.

Media CDN fetches for secrets are cached internally, significantly reducing the rate of secret fetches from Secret Manager. The reduced fetches also significantly reduce the rates of accesses that Secret Manager observes and bills you for.

For more information on secret caching in Media CDN, see Keys overview.