Authentication¶
Overview¶
For a language agnostic overview of authentication on Google Cloud, see Authentication Overview.
If you’re running in a Google Virtual Machine Environment (Compute Engine, App Engine, Cloud Run, Cloud Functions), authentication should “just work”.
If you’re developing locally, the easiest way to authenticate is using the Google Cloud SDK:
$gcloudauthapplication-defaultlogin
Note that this command generates credentials for client libraries. To authenticate the CLI itself, use:
$gcloudauthlogin
Previously,
gcloudauthloginwas used for both use cases. If yourgcloudinstallation does not support the new command, please update it:$gcloudcomponentsupdate
If you’re running your application elsewhere, you should download a service account JSON keyfile and point to it using an environment variable:
$exportGOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
Client-Provided Authentication¶
Every package uses a Client as a base for interacting with an API. For example:
fromgoogle.cloudimportdatastoreclient=datastore.Client()Passing no arguments at all will “just work” if you’ve followed the instructions in the Overview. The credentials are inferred from your local environment by using Google Application Default Credentials.
Credential Discovery Precedence¶
When loading the Application Default Credentials, the library will check for credentials in your environment by following the precedence outlined by google.auth.default().
Explicit Credentials¶
The Application Default Credentials discussed above can be useful if your code needs to run in many different environments or if you just don’t want authentication to be a focus in your code.
However, you may want to be explicit because
your code will only run in one place
you may have code which needs to be run as a specific service account every time (rather than with the locally inferred credentials)
you may want to use two separate accounts to simultaneously access data from different projects
In these situations, you can create an explicit Credentials object suited to your environment. After creation, you can pass it directly to a Client:
client=Client(credentials=credentials)Tip
To create a credentials object, follow the google-auth-guide.
Google Compute Engine Environment¶
These credentials are used in Google Virtual Machine Environments. This includes most App Engine runtimes, Compute Engine, Cloud Functions, and Cloud Run.
To create credentials:
fromgoogle.authimportcompute_enginecredentials=compute_engine.Credentials()Service Accounts¶
A service account is stored in a JSON keyfile.
fromgoogle.oauth2importservice_accountcredentials=service_account.Credentials.from_service_account_file('/path/to/key.json')A JSON string or dictionary:
importjsonfromgoogle.oauth2importservice_accountjson_account_info=json.loads(...)# convert JSON to dictionarycredentials=service_account.Credentials.from_service_account_info(json_account_info)Tip
Previously the Google Cloud Console would issue a PKCS12/P12 key for your service account. This library does not support that key format. You can generate a new JSON key for the same service account from the console.
User Accounts (3-legged OAuth 2.0) with a refresh token¶
The majority of cases are intended to authenticate machines or workers rather than actual user accounts. However, it’s also possible to call Google Cloud APIs with a user account via OAuth 2.0.
Tip
A production application should use a service account, but you may wish to use your own personal user account when first getting started with the google-cloud-* library.
The simplest way to use credentials from a user account is via Application Default Credentials using gcloudauthapplication-defaultlogin (as mentioned above) and google.auth.default():
importgoogle.authcredentials,project=google.auth.default()This will still follow the precedence described above, so be sure none of the other possible environments conflict with your user provided credentials.
Troubleshooting¶
Setting up a Service Account¶
If your application is not running on a Google Virtual Machine Environment, you need a Service Account. See Creating a Service Account.
Using Google Compute Engine¶
If your code is running on Google Compute Engine, using the inferred Google Application Default Credentials will be sufficient for retrieving credentials.
However, by default your credentials may not grant you access to the services you intend to use. Be sure when you set up the GCE instance, you add the correct scopes for the APIs you want to access:
All APIs
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/cloud-platform.read-only
For scopes for specific APIs see OAuth 2.0 Scopes for Google APIs
