Use signed URLs

This page provides an overview of signed URLs and instructions for using them with Cloud CDN. Signed URLs give time-limited resource access to anyone in possession of the URL, regardless of whether the user has a Google Account.

A signed URL is a URL that provides limited permission and time to make a request. Signed URLs contain authentication information in their query strings, allowing users without credentials to perform specific actions on a resource. When you generate a signed URL, you specify a user or service account that must have sufficient permission to make the request associated with the URL.

After you generate a signed URL, anyone who possesses it can use the signed URL to perform specified actions (such as reading an object) within a specified period of time.

Signed URLs also support an optional URLPrefix parameter, allowing you to provide access to multiple URLs based on a common prefix.

If you want to scope access to a specific URL prefix, consider using signed cookies.

Before you begin

Before you use signed URLs, do the following:

• Ensure that Cloud CDN is enabled; for instructions, see Using Cloud CDN. You can configure signed URLs on a backend before enabling Cloud CDN, but there is no effect until Cloud CDN is enabled.

• If necessary, update to the latest version of the Google Cloud CLI:

  gcloud components update
  

For an overview, see Signed URLs and signed cookies.

Configure signed request keys

Creating keys for your signed URLs or signed cookies requires several steps, which are described in the following sections.

Security considerations

Cloud CDN does not validate requests in the following circumstances:

• The request is not signed.
• The backend service or backend bucket for the request doesn't have Cloud CDN enabled.

Signed requests must always be validated at the origin before serving the response. This is because origins can be used for serving a mixture of signed and unsigned content and because a client might access the origin directly.

• Cloud CDN doesn't block requests without a Signature query parameter or Cloud-CDN-Cookie HTTP cookie. It rejects requests with invalid (or otherwise malformed) request parameters.
• When your application detects an invalid signature, make sure that your application responds with an HTTP 403 (Unauthorized) response code. HTTP 403 response codes aren't cacheable.
• Responses to signed and unsigned requests are cached separately, so a successful response to a valid signed request is never used to serve an unsigned request.
• If your application sends a cacheable response code to an invalid request, valid future requests might be incorrectly rejected.

For Cloud Storage backends, make sure to remove public access, so that Cloud Storage can reject requests that are missing a valid signature.

The following table summarizes the behavior.

Create signed request keys

You enable support for Cloud CDN signed URLs and signed cookies by creating one or more keys on a Cloud CDN-enabled backend service, backend bucket, or both.

For each backend service or backend bucket, you can create and delete keys as your security needs dictate. Each backend can have up to three keys configured at a time. We suggest periodically rotating your keys by deleting the oldest, adding a new key, and using the new key when signing URLs or cookies.

You can use the same key name in multiple backend services and backend buckets because each set of keys is independent of the others. Key names can be up to 63 characters. To name your keys, use the characters A-Z, a-z, 0-9, _ (underscore), and - (hyphen).

When you create keys, be sure to keep them secure because anyone who has one of your keys can create signed URLs or signed cookies that Cloud CDN accepts until the key is deleted from Cloud CDN. The keys are stored on the computer where you generate the signed URLs or signed cookies. Cloud CDN also stores the keys to verify request signatures.

To keep the keys secret, the key values aren't included in responses to any API requests. If you lose a key, you must create a new one.

To create a signed request key, follow these steps.

head -c 16 /dev/urandom | base64 | tr +/ -_ > KEY_FILE_NAME

gcloud compute backend-services \
   add-signed-url-key BACKEND_NAME \
   --key-name KEY_NAME \
   --key-file KEY_FILE_NAME

gcloud compute backend-buckets \
   add-signed-url-key BACKEND_NAME \
   --key-name KEY_NAME \
   --key-file KEY_FILE_NAME

Configure Cloud Storage permissions

If you use Cloud Storage and you have restricted who can read the objects, you must give Cloud CDN permission to read the objects by adding the Cloud CDN service account to Cloud Storage ACLs.

You don't need to create the service account. The service account is created automatically the first time that you add a key to a backend bucket in a project.

Before you run the following command, add at least one key to a backend bucket in your project. Otherwise, the command fails with an error because the Cloud CDN cache fill service account is not created until you add one or more keys for the project.

gcloud storage buckets add-iam-policy-binding gs://BUCKET \
  --member=serviceAccount:service-PROJECT_NUMBER@cloud-cdn-fill.iam.gserviceaccount.com \
  --role=roles/storage.objectViewer

Replace PROJECT_NUMBER with your project number and BUCKET with your storage bucket.

The Cloud CDN service account service-PROJECT_NUMBER@cloud-cdn-fill.iam.gserviceaccount.com doesn't appear in the list of service accounts in your project. This is because the Cloud CDN service account is owned by Cloud CDN, not your project.

For more information about project numbers, see Locate the project ID and project number in the Google Cloud console Help documentation.

Customize the maximum cache time

Cloud CDN caches responses for signed requests regardless of the backend's Cache-Control header. The maximum time that responses can be cached without revalidation is set by the signed-url-cache-max-age flag, which defaults to one hour and can be modified as shown here.

To set the maximum cache time for a backend service or backend bucket, run one of the following commands:

gcloud compute backend-services update BACKEND_NAME \
  --signed-url-cache-max-age MAX_AGE

gcloud compute backend-buckets update BACKEND_NAME \
  --signed-url-cache-max-age MAX_AGE

List signed request key names

To list the keys on a backend service or backend bucket, run one of the following commands:

gcloud compute backend-services describe BACKEND_NAME

gcloud compute backend-buckets describe BACKEND_NAME

Delete signed request keys

When URLs signed by a particular key should no longer be honored, run one of the following commands to delete that key from the backend service or backend bucket:

gcloud compute backend-services \
   delete-signed-url-key BACKEND_NAME --key-name KEY_NAME

gcloud compute backend-buckets \
   delete-signed-url-key BACKEND_NAME --key-name KEY_NAME

Sign URLs

The last step is to sign URLs and distribute them. You can sign URLs by using the gcloud compute sign-url command or by using code that you write yourself. If you need many signed URLs, custom code provides better performance.

Create signed URLs

Use these instructions to create signed URLs by using the gcloud compute sign-url command. This step assumes that you have already created the keys.

gcloud compute sign-url \
  "URL" \
  --key-name KEY_NAME \
  --key-file KEY_FILE_NAME \
  --expires-in TIME_UNTIL_EXPIRATION \
  [--validate]

gcloud compute sign-url \
  "https://example.com/media/video.mp4" \
  --key-name my-test-key \
  --expires-in 30m \
  --key-file sign-url-key-file

Programmatically create signed URLs

The following code samples demonstrate how to programmatically create signed URLs.

import (
	"crypto/hmac"
	"crypto/sha1"
	"encoding/base64"
	"fmt"
	"io"
	"io/ioutil"
	"os"
	"strings"
	"time"
)

// SignURL creates a signed URL for an endpoint on Cloud CDN.
//
// - url must start with "https://" and should not have the "Expires", "KeyName", or "Signature"
// query parameters.
// - key should be in raw form (not base64url-encoded) which is 16-bytes long.
// - keyName must match a key added to the backend service or bucket.
func signURL(url, keyName string, key []byte, expiration time.Time) string