diff options
Diffstat (limited to 'docs/auth.rst')
| -rw-r--r-- | docs/auth.rst | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/docs/auth.rst b/docs/auth.rst new file mode 100644 index 0000000..a9b296d --- /dev/null +++ b/docs/auth.rst @@ -0,0 +1,213 @@ +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 |