signurl - Create a signed url

Synopsis

gsutil signurl [-c <content_type>] [-d <duration>] [-m <http_method>] \
    [-p <password>] [-r <region>] (-u | <private-key-file>) \
    (gs://<bucket_name> | gs://<bucket_name>/<object_name>)...

Description

The signurl command will generate a signed URL that embeds authentication data so the URL can be used by someone who does not have a Google account. Please see the Signed URLs documentation for background about signed URLs.

Multiple gs:// urls may be provided and may contain wildcards. A signed url will be produced for each provided url, authorized for the specified HTTP method and valid for the given duration.

The signurl command uses the private key for a service account (the '<private-key-file>' argument) to generate the cryptographic signature for the generated URL. The private key file must be in PKCS12 or JSON format. If the private key is encrypted the signed url command will prompt for the passphrase used to protect the private key file (default 'notasecret'). For more information regarding generating a private key for use with the signurl command please see the Authentication documentation.

If you used service account credentials for authentication, you can replace the <private-key-file> argument with the -u or --use-service-account option to use the system-managed private key directly. This avoids the need to download the private key file.

Options

-m Specifies the HTTP method to be authorized for use with the signed url, default is GET. You may also specify RESUMABLE to create a signed resumable upload start URL. When using a signed URL to start a resumable upload session, you will need to specify the 'x-goog-resumable:start' header in the request or else signature validation will fail.
-d

Specifies the duration that the signed url should be valid for, default duration is 1 hour.

Times may be specified with no suffix (default hours), or with s = seconds, m = minutes, h = hours, d = days.

This option may be specified multiple times, in which case the duration the link remains valid is the sum of all the duration options.

The max duration allowed is 7 days when private-key-file is used.

The max duration allowed is 12 hours when -u option is used. This limitation exists because the system-managed key used to sign the url may not remain valid after 12 hours.

-c Specifies the content type for which the signed url is valid for.
-p Specify the private key password instead of prompting.
-r <region>

Specifies the region in which the resources for which you are creating signed URLs are stored.

Default value is 'auto' which will cause gsutil to fetch the region for the resource. When auto-detecting the region, the current gsutil user's credentials, not the credentials from the private-key-file, are used to fetch the bucket's metadata.

This option must be specified and not 'auto' when generating a signed URL to create a bucket.

-u

Use service account credentials instead of a private key file to sign the url.

You can also use the --use-service-account option, which is equivalent to -u. Note that both options have a maximum allowed duration of 12 hours for a valid link.

Usage

Create a signed url for downloading an object valid for 10 minutes:

gsutil signurl -d 10m <private-key-file> gs://<bucket>/<object>

Create a signed url without a private key, using a service account's credentials:

gsutil signurl -d 10m -u gs://<bucket>/<object>

Create a signed url by impersonating a service account:

gsutil -i <service account email> signurl -d 10m -u gs://<bucket>/<object>

Create a signed url, valid for one hour, for uploading a plain text file via HTTP PUT:

gsutil signurl -m PUT -d 1h -c text/plain <private-key-file> \
    gs://<bucket>/<obj>

To construct a signed URL that allows anyone in possession of the URL to PUT to the specified bucket for one day, creating an object of Content-Type image/jpg, run:

gsutil signurl -m PUT -d 1d -c image/jpg <private-key-file> \
    gs://<bucket>/<obj>

To construct a signed URL that allows anyone in possession of the URL to POST a resumable upload to the specified bucket for one day, creating an object of Content-Type image/jpg, run:

gsutil signurl -m RESUMABLE -d 1d -c image/jpg <private-key-file> \
    gs://bucket/<obj>