Use signed requests

To create a signed request, compose a string that includes parameters that describe the content that you want to protect and the expiration time of the signed value. You then include the composed string in your request. Media CDN then verifies that your signed request is valid before acting upon it.

Signed request requirements

Signed requests must meet the following requirements:

• Have a GET, HEAD, or OPTIONS HTTP method. Other methods are not supported.

• Have an expiration time set in the future. Due to potential clock synchronization differences, as well as client network conditions (for example, disconnects and retries), we recommend setting timestamps no less than one minute into the future, or no less than the length of the video stream, whichever is greater.

• Have a signature that can be verified by a key or secret in an EdgeCacheKeyset.

You cannot sign other HTTP methods, such as POST, PUT, or DELETE requests. If you need to issue signed URLs for user-facing uploads, see the Cloud Storage documentation for signed URLs.

Security considerations

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

Note: We strongly 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	Response 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 is 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	Validate a signature or a token and the response with content from cache or a fetch from 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) response code. HTTP 403 response codes aren't cacheable.

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

Configure signed requests

The following sections detail how to configure, sign, and validate signed requests.

Generate keys

Create the keys that Media CDN uses to sign requests.

Create a keyset

Create the keyset that Media CDN uses for signed requests.

Require signed requests

To allow only signed requests to access a resource, you can attach a list of keys to a route and set the signedRequestMode to one of the following:

• REQUIRE_SIGNATURES for signed requests not using tokens.

• REQUIRE_TOKENS for signed requests using tokens.

Enabling signed requests on a route enforces that all requests are signed or present a token. Requests without a valid signature (such as an invalid key name, expired signature or token, mismatched signature, and so on), fail.

An EdgeCacheKeyset can contain multiple keys to allow for key rotation. Valid requests signed with any listed key are accepted, and keys are tried in order. For more information about key rotation, see Rotate secrets.

When the signedRequestMode is set to REQUIRE_SIGNATURES or REQUIRE_TOKENS, Media CDN validates both cache hits and misses. This includes all requests to the origin.

Following is an example of a Media CDN configuration that enforces signed requests on a given PathMatcher (route):

gcloud edge-cache services describe prod-media-service

Output:

...
  routeAction:
    cdnPolicy:
      cacheMode: CACHE_ALL_STATIC
      signedRequestMode: REQUIRE_SIGNATURES
      signedRequestKeyset: prod-vod-keyset

For information on creating tokens for signed requests, see Generate tokens.

To disable request signing, you can set the signedRequestMode to DISABLED and delete the reference to the signedRequestKeyset.

Validate requests at the origin

When a route is configured with a signing mode of REQUIRE_SIGNATURES, Media CDN validates that every matching request has a valid signature. The lack of a signature is treated as an invalid signature for these routes.

To prevent cases where signing is misconfigured, and where a user attempts to access your origin directly, we recommend that you validate that requests are signed at the origin as well. A defense in depth approach to content protection helps prevent unauthorized access and download of your licensed and paid content.

For URL-based signing methods, where the signature is part of the query parameters or embedded as a URL path component, the signature and related parameters are removed from the URL before the request is sent to the origin. This prevents the signature from causing routing issues when the origin is handling the request. To validate these requests, you can inspect the x-client-request-url request header, which includes the original (signed) client request URL prior to the removal of the signed components.

Note: If you are using Cloud Storage and have removed the allUsers (public access) permission, Cloud Storage rejects unauthenticated, public access to content on your behalf.

To validate requests at the origin, use the same validation code as part of your request signing endpoints, which also helps mitigate key mismatch and issues due to key rotation.

Rotate keys

As a best practice, rotate or update the secrets used by Media CDN regularly. We recommend rotating keys every 30 to 60 days, but it isn't strictly required.

What's next

• To read more about how to enable and access Media CDN logs, including how to filter and query across your logs, see Logging.

• To configure Media CDN and a private Cloud Storage bucket, see Origin connectivity and shielding.