Cloud Storage authentication

Most of the operations you perform in Cloud Storage must be authenticated. The only exceptions are operations on resources that allow anonymous access. A resource has anonymous access if the allUsers group is included in the ACL for the resource or if the allUsers group is included in an IAM policy that applies to the resource. The allUsers group includes anyone on the Internet.

OAuth 2.0 authentication

Cloud Storage uses OAuth 2.0 for API authentication and authorization. Authentication is the process of determining the identity of a client. The details of authentication vary depending on how you are accessing Cloud Storage, but fall into two general types:

  • A server-centric flow allows an application to directly hold the credentials of a service account to complete authentication. Use this flow if your application works with its own data rather than user data. Google Cloud projects have default service accounts you can use, or you can create new ones.

  • A user-centric flow allows an application to obtain credentials from an end user. The user signs in to complete authentication. Use this flow if your application needs to access user data. See User account credentials for scenarios where a user-centric flow is appropriate.

Keep in mind that you can use both types of authentication together in an application. For more background information about authentication, see the Google Cloud Auth Guide.

Command line interface authentication

If you work with Cloud Storage using the Google Cloud CLI, you should typically authenticate with your user account credentials. To do so, run the command gcloud auth login and follow the instructions, which includes logging into your user account. For additional authentication options, see Authenticate for using the gcloud CLI.

Client library authentication

Client libraries can use Application Default Credentials to easily authenticate with Google APIs and send requests to those APIs. With Application Default Credentials, you can test your application locally and deploy it without changing the underlying code. For more information, see Authenticate for using client libraries.

  • Google Cloud

    If you're running your application on services that support attached service accounts, such as App Engine, Cloud Functions, Cloud Run, or Compute Engine, the environment already provides a service account's authentication information, so no further setup is required. For Compute Engine, the service account scope depends on how you created the instance. See Access scopes in the Compute Engine documentation. For App Engine, the cloud-platform scope is used.

  • Other environments

    To initialize your local development or production environment, create a Google Cloud service account, download its key, and set the GOOGLE_APPLICATION_CREDENTIALS environment variable to use the key. For step-by-step information, see Setting up authentication with Cloud Storage client libraries.

API authentication

To make requests using OAuth 2.0 to either the Cloud Storage XML API or JSON API, include your application's access token in the Authorization header in every request that requires authentication. You can generate an access token from the OAuth 2.0 Playground:

  1. In the OAuth 2.0 Playground, click Cloud Storage API v1, and then select an access level for your application (full_control, read_only, or read_write).

  2. Click Authorize APIs.

  3. Sign in to your account when prompted. In the dialogue that appears, click Allow.

  4. In Step 2 of the playground, click Exchange authorization code for tokens for the authorization code that appears.

  5. Copy your access token and include it in the Authorization header of your request:

    Authorization: Bearer OAUTH2_TOKEN

The following is an example of a request that lists objects in a bucket.

JSON API

Use the list method of the Objects resource.

GET /storage/v1/b/example-bucket/o HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

To authorize requests from the command line or for testing, you can use the curl command with the following syntax:

curl -H "Authorization: Bearer OAUTH2_TOKEN" "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o"

For local testing, you can use the gcloud auth application-default print-access-token command to generate a token.

XML API

Use a List objects request.

GET / HTTP/1.1
Host: example-bucket.storage.googleapis.com
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

To authorize requests from the command line or for testing, you can use the curl command with the following syntax:

curl -H "Authorization: Bearer OAUTH2_TOKEN" "https://BUCKET_NAME.storage.googleapis.com"

For local testing, you can use the gcloud auth application-default print-access-token command to generate a token.

Due to the complexity of managing and refreshing access tokens and the security risk when dealing directly with cryptographic applications, we strongly encourage you to use a verified client library.

If you're looking for HMAC keys to use with the XML API for interoperable access with Amazon S3, see Managing HMAC keys for service accounts.

What's next