214 lines
6.5 KiB
ReStructuredText
214 lines
6.5 KiB
ReStructuredText
Authentication
|
|
**************
|
|
|
|
.. _Overview:
|
|
|
|
Overview
|
|
========
|
|
|
|
For a language agnostic overview of authentication on Google Cloud, see `Authentication Overview`_.
|
|
|
|
.. _Authentication Overview: https://cloud.google.com/docs/authentication
|
|
|
|
* **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`_:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ gcloud auth application-default login
|
|
|
|
Note that this command generates credentials for client libraries. To authenticate the CLI itself, use:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ gcloud auth login
|
|
|
|
Previously, ``gcloud auth login`` was used for both use cases. If
|
|
your ``gcloud`` installation does not support the new command,
|
|
please update it:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ gcloud components update
|
|
|
|
.. _Google Cloud SDK: http://cloud.google.com/sdk
|
|
|
|
|
|
* **If you're running your application elsewhere**,
|
|
you should download a `service account`_ JSON keyfile
|
|
and point to it using an environment variable:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
|
|
|
|
.. _service account: https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating
|
|
|
|
Client-Provided Authentication
|
|
==============================
|
|
|
|
Every package uses a :class:`Client <google.cloud.client.Client>`
|
|
as a base for interacting with an API.
|
|
For example:
|
|
|
|
.. code-block:: python
|
|
|
|
from google.cloud 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`_.
|
|
|
|
.. _Application Default Credentials: https://developers.google.com/identity/protocols/application-default-credentials
|
|
|
|
.. _Precedence:
|
|
|
|
Credential Discovery Precedence
|
|
-------------------------------
|
|
|
|
When loading the `Application Default Credentials`_,
|
|
the library will check for credentials in your environment by following the
|
|
precedence outlined by :func:`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
|
|
:class:`~google.auth.credentials.Credentials` object suited to your environment.
|
|
After creation, you can pass it directly to a :class:`Client <google.cloud.client.Client>`:
|
|
|
|
.. code:: python
|
|
|
|
client = Client(credentials=credentials)
|
|
|
|
.. tip::
|
|
To create a credentials object, follow the `google-auth-guide`_.
|
|
|
|
.. _google-auth-guide: https://googleapis.dev/python/google-auth/latest/user-guide.html#service-account-private-key-files
|
|
|
|
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
|
|
:class:`credentials <google.auth.compute_engine.Credentials>`:
|
|
|
|
.. code:: python
|
|
|
|
from google.auth import compute_engine
|
|
credentials = compute_engine.Credentials()
|
|
|
|
Service Accounts
|
|
----------------
|
|
|
|
A `service account`_ is stored in a JSON keyfile.
|
|
|
|
.. code:: python
|
|
|
|
from google.oauth2 import service_account
|
|
|
|
credentials = service_account.Credentials.from_service_account_file(
|
|
'/path/to/key.json')
|
|
|
|
A JSON string or dictionary:
|
|
|
|
.. code:: python
|
|
|
|
import json
|
|
|
|
from google.oauth2 import service_account
|
|
|
|
json_account_info = json.loads(...) # convert JSON to dictionary
|
|
credentials = 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`_.
|
|
|
|
.. _OAuth 2.0: https://developers.google.com/identity/protocols/OAuth2
|
|
|
|
.. 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 ``gcloud auth login``
|
|
(as mentioned above) and :func:`google.auth.default`:
|
|
|
|
.. code:: python
|
|
|
|
import google.auth
|
|
|
|
credentials, project = google.auth.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.
|
|
|
|
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`_.
|
|
|
|
.. _Creating a Service Account: https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating
|
|
|
|
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-platform``
|
|
* ``https://www.googleapis.com/auth/cloud-platform.read-only``
|
|
|
|
For scopes for specific APIs see `OAuth 2.0 Scopes for Google APIs`_
|
|
|
|
.. _set up the GCE instance: https://cloud.google.com/compute/docs/authentication#using
|
|
.. _OAuth 2.0 Scopes for Google APIS: https://developers.google.com/identity/protocols/oauth2/scopes
|