Most of the operations you perform with the Google Cloud Storage API must be authenticated. The only exceptions are operations on objects that allow anonymous access. Objects are anonymously accessible if the
READ permission. The
AllUsers group includes anyone on the Internet.
Tip: Are you looking for Developer Keys to use with the XML API for interoperable access with Amazon S3?
OAuth 2.0 Authentication
Important: You need to use SSL (HTTPS) when you use OAuth 2.0 authentication. If you are using Python, you should also make sure that you are using an HTTPS library that validates certificates. The Python 2.x httplib does not do this but the library used by gsutil does.
Google recommends OAuth 2.0 authentication for interacting with the Google Cloud Storage API. OAuth 2.0 authentication eliminates the need to provide sensitive account information, such as a username and password, to any applications that need access to your data. Instead, you can use the OAuth 2.0 protocol to obtain and give out OAuth tokens. OAuth tokens authenticate tools and applications to access Google Cloud Storage API on your behalf and also provide the ability to restrict access using scopes. You can authorize different applications with separate tokens, and revoke tokens individually, if necessary.
OAuth tokens use scopes to determine the level of access to your data. For example, Google Cloud Storage has three specific scopes: read-only, read-write, or full-control. You can assign OAuth tokens to applications which then use their respective tokens to authenticate access to your data. Based on the scope of the token, the application is only allowed to perform certain types of actions. For example, by using OAuth 2.0 authentication, you can specify that application A with a read-only access token can only read your data on your behalf, while application B with a read-write access token can read and modify data on your behalf. Neither application can read or modify access control lists on objects and buckets; only an application with a full-control-scoped token could do so.
The details of the authorization process, or "flow," for OAuth 2.0 vary somewhat depending on what kind of application you're writing. The following general process applies to all application types:
- When you create your application, you register it with Google. Google then provides information you'll need later, such as a client ID and a client secret.
- Activate the Google Cloud Storage JSON API in the APIs section of the Google Developers Console. (If it isn't listed in the Console, then skip this step.)
- When your application needs access to user data, it asks Google for a particular scope of access.
- Google displays an consent screen to the user, asking them to authorize your application to request some of their data.
- If the user approves, then Google gives your application a short-lived access token.
- Your application requests user data, attaching the access token to the request.
- If Google determines that your request and the token are valid, it returns the requested data.
For more information, see the Using OAuth 2.0 to Access Google APIs.
Depending on the type of application, there are several ways to set up OAuth 2.0 authentication. For more information, see the Using OAuth 2.0 to Access Google APIs.
Google Cloud Storage API OAuth scopes are as follows:
||Only allows access to read data, including listing buckets.||
||Allows access to read and change data.||
||Allows full control over data, including the ability to modify ACLs.||
To make requests using OAuth 2.0, include the application's access token in the Authorization header, as follows:
Authorization: Bearer <oauth access token>
The following is an example of a GET request that uses OAuth 2.0 authentication:
GET / HTTP/1.1 Host: storage.googleapis.com Accept-Encoding: identity Content-Length: 0 x-goog-api-version: 2 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
If your application does not have an access token, you need to set up your application to use OAuth 2.0 authentication with the Google Cloud Storage API. When you grant your application an access token, keep in mind that it is not possible to grant an access token that has more control than you have. For example, if an ACL only grants you read-only access to a bucket, it is not possible for you to give read-write access to an application, even if you grant the application a read-write access token. For information on how to grant your application an access token, see Using OAuth 2.0 to Access Google APIs.
If you previously authorized your application for OAuth 2.0, your application should also have a refresh token, which can be used to acquire a new access token. For more information, see "Getting additional access tokens" at Using OAuth 2,0 to Access Google APIs.
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 are not stripped out by the proxy. Without the
Authorization header, you will receive a
MissingSecurityHeader error and your request will be rejected.
Google Cloud Storage lets you provide browser-based authenticated downloads to users who do not have Google Cloud Storage accounts. To do this, apply Google account-based ACLs to the object and then provide users with a URL that is scoped to the object. The URL for browser-based authenticated downloads is:
For example, to let Jane download an object named /europe/france/paris.jpg that's in a bucket named travel-maps, you grant email@example.com
READ permission for the object /europe/france/paris.jpg. Then you provide Jane with the following URL:
When Jane clicks the URL in her browser she's automatically prompted to sign in to her Google account (if she's not already logged in). After she is authenticated, and her browser has acquired a cookie with an encapsulated identity token, she is redirected to the object in the Google Cloud Storage repository. Google Cloud Storage then verifies that Jane is allowed to read the object, and the object is downloaded to Jane's computer.
The following figure shows how the authentication process for browser-based authenticated downloads works.
Note: All requests to the
storage.cloud.google.com URI require authentication. This is true even if an object's ACL grants
READ permission to the
AllUsers group. If you want users to download anonymously accessible objects without authenticating, use the
Using Service Accounts for Authentication
Google Cloud Storage lets you use service accounts to authenticate your application. Service accounts are special accounts that represent software rather than people. Every project has a service account associated with it, which may be used for authentication and to enable advanced features such as Signed URLs and browser uploads using POST.
When you use a service account to authenticate your application, you do not need to obtain an initial OAuth token using the web flow. Instead, you can obtain a private key from the Google APIs console, which you then use to send a signed request for an access token. You can then use the access token like you normally would. For more details, see Using OAuth 2.0 for Server to Server Applications.
Getting a Private Key from the Google Developers Console
You create the private key in the developer console when you create an OAuth client ID for a service account type application, as described in the Google Developers Console Help. As described in that help, you are prompted to download this key immediately after creating it-- Google does not store a copy:
This key is provided in PKCS12 format, which is supported by many different programming languages and libraries. If needed, it can be converted into other formats using openssl.
Note:If you forget to download the key, you can always create another one for your project in the Google Developers Console. In the API & auth section, select Registered Apps and find the registered application representing the service account. In the Certificate pane of the registered application, click Generate New Key.