This page provides an overview of signed URLs, which you use to give time-limited resource access to anyone in possession of the URL, regardless of whether they have a Google account. To learn how to create a signed URL, see V4 Signing Process with Cloud Storage Tools and V4 Signing Process with Your Own Program. To learn about other ways of controlling access to buckets and objects, see Overview of Access Control.
A signed URL is a URL that provides limited permission and time to make a request. Signed URLs contain authentication information in their query string, allowing users without credentials to perform specific actions on a resource. When you generate a signed URL, you specify a user or service account which must have sufficient permission to make the request that the signed URL will make. 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.
When should you use a signed URL?
In some scenarios, you might not want to require your users to have a Google account in order to access Cloud Storage, but you still want to control access using your application-specific logic. The typical way to address this use case is to provide a signed URL to a user, which gives the user read, write, or delete access to that resource for a limited time. You specify an expiration time when you create the signed URL. Anyone who knows the URL can access the resource until the expiration time for the URL is reached or the key used to sign the URL is rotated.
The most common requests for signed URLs are object uploads and downloads. In most other cases, such as copying objects, composing objects, or editing metadata, creating a signed URL and giving it to someone to use is an unnecessary extra step. Instead, you should consider a design in which the entity responsible for creating the signed URL directly makes the desired request to Cloud Storage.
Options for generating a signed URL
Cloud Storage supports several methods for generating a signed URL:
V4 signing with service account authentication: This signing mechanism is described below.
V2 signing with service account authentication: For more information about this signing mechanism, go here.
Signing with HMAC authentication: If you're an Amazon Simple Storage Service (Amazon S3) user, you can use your existing workflows to generate signed URLs for Cloud Storage. Simply specify Cloud Storage resources, point to the host
storage.googleapis.com, and use Google HMAC credentials in the process of generating the signed URL.
Signed URL example
The following is an example of a signed URL that was created following the V4 signing process with service account authentication:
https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm= GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount .com%2F20181026%2Fus-central-1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T18 1309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f16 9edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa849 6def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dc c1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c2058 0e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a 66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823 a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b13344703 2ea7abedc098d2eb14a7
This signed URL provided access to read the object
cat.jpeg in the bucket
example-bucket. The query parameters that make this a signed URL are:
X-Goog-Algorithm: The algorithm used to sign the URL.
X-Goog-Credential: Information about the credentials used to create the signed URL.
X-Goog-Date: The date and time the signed URL became usable, in the ISO 8601 basic format
X-Goog-Expires: The length of time the signed URL remained valid, measured in seconds from the value in
X-Goog-Date. In this example the Signed URL expires in 15 minutes. The longest expiration value is 604800 seconds (7 days).
X-Goog-SignedHeaders: Headers that had to be included as part of any request that used the signed URL.
X-Goog-Signature: The authentication string that allowed requests using this signed URL to access
Using signed URLs with resumable uploads
When working with resumable uploads, you only create and use a signed URL
POST request that initiates the upload. This initial request
returns a session URI that you use in subsequent
PUT requests to upload
the data. Since the session URI acts as an authentication token, the
requests do not use any signed URLs.
One advantage of resumable uploads is they allow the initiation request to be made by the server, avoiding the need for clients to have to deal with signed URLs. However, there are certain considerations to keep in mind:
The session URI can be used by anyone in possession of it to upload data. Be sure to transmit the session URI over HTTPS when giving it to a client.
Resumable uploads are pinned to the region of the initial request. To avoid slow uploads, if your server and client are in geographically distant places, have the initial
POSTrequest constructed and signed by the server, but then give the signed URL to the client so that the upload is initiated from their location.
Signed URL considerations
When working with signed URLs, keep in mind the following:
Signed URLs can only be used to access Cloud Storage resources through XML API endpoints.
Signed URLs can generally be made for any XML API request; however, there are two exceptions:
Signed URLs that use V4 signatures cannot be used in requests whose body uses chunked encoding.
Node.js Cloud Storage Client Libraries currently can only make signed URLs for individual objects. For example, it cannot be used to make signed URLs for listing objects in a bucket.
When specifying credentials, it is recommended that you identify your service account by using its email address; however, use of the service account ID is also supported.
Be sure to omit the authorization header from any requests that use a signed URL. If both are used, Cloud Storage may authenticate against the credentials provided in the header, rather than the signed URL. Doing so could allow more access to resources than you intended.
Signed URLs use canonical requests as part of the information encoded in
X-Goog-Signature query string parameter. When you
make a signed URL with Cloud Storage tools, the required canonical
request is created and incorporated automatically. However, when you
make a signed URL with your own program, you need to define the canonical
The credential scope appears in both the string-to-sign and the
X-Goog-Credential query string parameter.
Signing strings with IAM signBlob
When generating a signed URL using a program, one option for signing the
string is to use the IAM signBlob method provided by Google Cloud.
Signature that is output from this method is used when assembling the
signBlob service regularly rotates the private key that it uses. Signed
URLs generated are usable for at least 12 hours, but may stop working prior to
your set expiration time if the expiration time is greater 12 hours. Given this,
signed URLs generated from
signBlob are best used for short-lived access
- Create a signed URL with Cloud Storage tools such as gsutil.
- Create a signed URL with your own program.
- Learn more about Canonical requests.
- Learn more about Signatures.