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 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 Auth Guide.
Scopes
Authorization is the process of determining what permissions an authenticated
identity has on a set of specified resources. OAuth 2.0 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 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 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 gcloud CLI, you should authenticate with service account credentials.
Use an existing service account or create a new one, and download the associated private key. Note that you can only download the private key data for a service account key when the key is first created.
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.
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 Auth Guide.
Google Cloud
If you're running your application on 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. 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. You can
generate an access token from the OAuth 2.0 Playground:
In the OAuth 2.0 Playground, click Cloud Storage API v1, and then select an access level for your application (
full_control
,read_only
, orread_write
).Click Authorize APIs.
Sign in to your Google account when prompted. In the dialogue that appears, click Allow.
In Step 2 of the playground, click Exchange authorization code for tokens for the authorization code that appears.
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.
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 2.0 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. See Where do I start with Firebase Authentication for details on how to set up authentication systems for different use cases.
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 jane@gmail.com 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 and specifically in Cloud Storage
- Learn about API keys, which can be used to identify an application.