Cloud Storage authentication

Most of the operations you perform in Cloud Storage must be authenticated. The only exceptions are operations on objects that allow anonymous access. Objects are anonymously accessible if the allUsers group has READ permission. 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 Platform 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 the User account credentials section later in this page 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 Platform Auth Guide.

Scopes

Authorization is the process of determining what permissions an authenticated identity has on a set of specified resources. OAuth uses scopes to determine if an authenticated identity is authorized. Applications use a credential (obtained from a user-centric or server-centric authentication flow) together with one or more scopes to request an access token from a Google authorization server to access protected resources. For example, application A with an access token with read-only scope can only read, while application B with an access token with read-write scope can read and modify data. Neither application can read or modify access control lists on objects and buckets; only an application with full-control scope can do so.

Type	Description	Scope URL
read-only	Only allows access to read data, including listing buckets.	https://www.googleapis.com/auth/devstorage.read_only
read-write	Allows access to read and change data, but not metadata like IAM policies.	https://www.googleapis.com/auth/devstorage.read_write
full-control	Allows full control over data, including the ability to modify IAM policies.	https://www.googleapis.com/auth/devstorage.full_control
cloud-platform.read-only	View your data across Google Cloud Platform services. For Cloud Storage, this is the same as devstorage.read-only.	https://www.googleapis.com/auth/cloud-platform.read-only
cloud-platform	View and manage data across all Google Cloud Platform services. For Cloud Storage, this is the same as devstorage.full-control.	https://www.googleapis.com/auth/cloud-platform

gsutil authentication

With gsutil installed from the Cloud SDK, you should authenticate with service account credentials.

1. Use an existing service account or create a new one, and download the associated private key.

2. Use gcloud auth activate-service-account to authenticate with the service account:

   gcloud auth activate-service-account --key-file [KEY_FILE]

   Where [KEY_FILE] is the name of the file that contains your service account credentials.

gcloud auth uses the cloud-platform scope when getting an access token.

If you installed gsutil independent of the Cloud SDK, then see the gsutil install page for information about how to authenticate.

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, including code samples, see Google Cloud Platform Auth Guide.

• Google Cloud Platform

  If you're running your application on App Engine 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 Setting the scope of service account access for instances. For App Engine, the cloud-platform scope is used.

• Other environments

  To initialize your local development or production environment, create a GCP 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. As an alternative to setting an environment variable, you can also use the service account key directly in code.

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.

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

XML API

Use a List objects request.

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

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 developer keys to use with the XML API for interoperable access with Amazon S3, see Managing developer keys for a simple migration.

Note: If your requests are being routed through a proxy, you may need to check with your network administrator to ensure that the Authorization header containing your credentials is not stripped out by the proxy. Without the Authorization header, you will receive a MissingSecurityHeader error and your request will be rejected. For more information about accessing Cloud Storage through a proxy server, see the Troubleshooting topic.

User account credentials

Use user account credentials for authentication when your application requires access to data on a user's behalf; otherwise, use service account credentials. Here are examples of scenarios where user account credentials can be used:

• Web server applications
• Installed and desktop applications
• Mobile applications
• Client-side JavaScript
• Applications on limited-input devices

For more information on these scenarios, see OAuth scenarios.

If you are designing an application to support multiple authentication options for end users, then use Firebase Authentication, which supports email and password authentication as well as federated sign in with identity providers such as Google, Facebook, Twitter, and GitHub.

When an application is granted an access token in a user-centric auth flow by an end-user, that access token will only have the permissions available to the user who grants the token. For example, if [e-mail] has read-only access to example-bucket, an application which Jane has granted read-write access to will be unable to write to example-bucket on her behalf.

What's next

• Learn about browser-based downloads using cookie authentication.
• Learn about how service accounts are used generally in Google Cloud Platform and specifically in Cloud Storage