Skip to content

gcloud-auth.rst

Latest commit

 

History

History
182 lines (125 loc) · 5.67 KB

gcloud-auth.rst

File metadata and controls

182 lines (125 loc) · 5.67 KB

Authentication

Overview

  • If you're running in Compute Engine or App Engine, authentication should "just work".

  • If you're developing locally, the easiest way to authenticate is using the Google Cloud SDK:

    $ gcloud auth login

  • If you're running your application elsewhere, you should download a service account JSON keyfile and point to it using an environment variable:

    $ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"

Client-Provided Authentication

Every package uses a :class:`Client <gcloud.client.Client>` as a base for interacting with an API. For example:

from gcloud import datastore
client = datastore.Client()

Passing no arguments at all will "just work" if you've followed the instructions in the :ref:`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 properties of your local environment in the following order:

  1. Application running in Google App Engine
  2. JSON or PKCS12/P12 keyfile pointed to by GOOGLE_APPLICATION_CREDENTIALS environment variable
  3. Credentials provided by the Google Cloud SDK (via gcloud auth login)
  4. Application running in Google Compute Engine

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 :class:`Credentials <oauth2client.client.Credentials>` object suited to your environment. After creation, you can pass it directly to a :class:`Client <gcloud.client.Client>`:

client = Client(credentials=credentials)

Google App Engine Environment

To create :class:`credentials <oauth2client.appengine.AppAssertionCredentials>` just for Google App Engine:

from oauth2client.appengine import AppAssertionCredentials
credentials = AppAssertionCredentials([])

Google Compute Engine Environment

To create :class:`credentials <oauth2client.gce.AppAssertionCredentials>` just for Google Compute Engine:

from oauth2client.gce import AppAssertionCredentials
credentials = AppAssertionCredentials([])

Service Accounts

A service account can be used with both a JSON keyfile and a PKCS12/P12 keyfile.

Directly creating credentials in oauth2client for a service account is a rather complex process, so as a convenience, the :meth:`from_service_account_json() <gcloud.client.Client.from_service_account_json>` and :meth:`from_service_account_p12() <gcloud.client.Client.from_service_account_p12>` factories are provided to create a :class:`Client <gcloud.client.Client>` with service account credentials.

For example, with a JSON keyfile:

client = Client.from_service_account_json('/path/to/keyfile.json')

Tip

Unless you have a specific reason to use a PKCS12/P12 key for your service account, we recommend using a JSON key.

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 gcloud-python library.

The simplest way to use credentials from a user account is via Application Default Credentials using gcloud auth login (as mentioned above):

from oauth2client.client import GoogleCredentials
credentials = GoogleCredentials.get_application_default()

This will still follow the :ref:`precedence <Precedence>` described above, so be sure none of the other possible environments conflict with your user provided credentials.

Advanced users of oauth2client can also use custom flows to create credentials using client secrets or using a webserver flow. After creation, :class:`Credentials <oauth2client.client.Credentials>` can be serialized with :meth:`to_json() <oauth2client.client.Credentials.to_json>` and stored in a file and then and deserialized with :meth:`from_json() <oauth2client.client.Credentials.from_json>`.