Skip to content

Update auth documentation #2801

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
theacodes merged 3 commits into from
Dec 2, 2016
Merged

Update auth documentation #2801

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2c8351c
Update auth documentation
Dec 2, 2016
04a8e05
Fix nits
Dec 2, 2016
3bf0f46
Ooops
Dec 2, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 30 additions & 40 deletions docs/google-cloud-auth.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,14 +68,8 @@ Credential Discovery Precedence
-------------------------------

When loading the `Application Default Credentials`_,
the library will check properties of your local environment
in the following order:

#. Application running in Google App Engine
#. JSON or PKCS12/P12 keyfile pointed to by
``GOOGLE_APPLICATION_CREDENTIALS`` environment variable
#. Credentials provided by the Google Cloud SDK (via ``gcloud auth login``)
#. Application running in Google Compute Engine
the library will check for credentials in your environment by following the
precedence outlined by :func:`google.auth.default`.

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view


Explicit Credentials
====================
Expand All @@ -93,10 +87,9 @@ However, you may want to be explicit because
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 <google.cloud.client.Client>`:
: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

Expand All @@ -106,43 +99,36 @@ Google App Engine Environment
-----------------------------

To create
:class:`credentials <oauth2client.contrib.appengine.AppAssertionCredentials>`
:class:`credentials <google.auth.app_engine.Credentials>`
just for Google App Engine:

.. code:: python

from oauth2client.contrib.appengine import AppAssertionCredentials
credentials = AppAssertionCredentials([])
from google.auth import app_engine
credentials = app_engine.Credentials()

Google Compute Engine Environment
---------------------------------

To create
:class:`credentials <oauth2client.contrib.gce.AppAssertionCredentials>`
:class:`credentials <google.auth.compute_engine.Credentials>`
just for Google Compute Engine:

.. code:: python

from oauth2client.contrib.gce import AppAssertionCredentials
credentials = AppAssertionCredentials([])
from google.auth import compute_engine
credentials = compute_engine.Credentials()

Service Accounts
----------------

A `service account`_ can be used with both a JSON keyfile and
a PKCS12/P12 keyfile.
A `service account`_ is stored in a JSON keyfile.

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

.. _oauth2client: http://oauth2client.readthedocs.io/en/latest/

For example, with a JSON keyfile:

.. code:: python
Expand All @@ -151,9 +137,9 @@ For example, with a JSON keyfile:

.. tip::

Unless you have a specific reason to use a PKCS12/P12 key for your
service account,
we recommend using a JSON key.
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
-------------------------------------------------------
Expand All @@ -173,12 +159,13 @@ possible to call Google Cloud APIs with a user account via

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

.. code:: python

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

credentials, project = google.auth.default()

This will still follow the :ref:`precedence <Precedence>`
described above,
Expand All @@ -192,10 +179,14 @@ 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>`.
:meth:`from_json() <oauth2client.client.Credentials.from_json>`. In order
to use ``oauth2client``'s credentials with this library, you'll need to
`convert them`_.

.. _oauth2client: https://github.com/Google/oauth2client.

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

.. _client secrets: https://developers.google.com/api-client-library/python/guide/aaa_oauth#flow_from_clientsecrets
.. _webserver flow: https://developers.google.com/api-client-library/python/guide/aaa_oauth#OAuth2WebServerFlow
.. _convert them: http://google-auth.readthedocs.io/en/stable/user-guide.html#user-credentials

Troubleshooting
===============
Expand Down Expand Up @@ -307,10 +298,12 @@ you add the correct scopes for the APIs you want to access:
Advanced Customization
======================

Though the ``google-cloud-python`` library defaults to using `oauth2client`_
Though the ``google-cloud-python`` library defaults to using `google-auth`_
to sign requests and ``httplib2`` for sending requests,
it is not a strict requirement.

.. _google-auth: http://google-auth.readthedocs.io/en/stable/

The :class:`Client <google.cloud.client.Client>` constructor accepts an optional
``http`` argument in place of a ``credentials`` object.
If passed, all HTTP requests made by the client will use your
Expand All @@ -337,10 +330,7 @@ using the `requests`_ library.
.. _custom HTTP class: https://github.com/GoogleCloudPlatform/google-cloud-python/issues/908#issuecomment-110811556
.. _requests: http://www.python-requests.org/en/latest/

As for handling authentication on your own,
it may be easiest just to re-use bits from ``oauth2client``.
Unfortunately, these parts have a hard dependency on ``httplib2``.
We hope to enable using `custom HTTP libraries`_ with ``oauth2client`` at
We hope to enable using `custom HTTP libraries`_ with this library at
some point.

This comment was marked as spam.

Sign in to view


.. _custom HTTP libraries: https://github.com/google/oauth2client/issues/128