From 728ba47c2e1d38aaacb297ded086fe9fe75d46f6 Mon Sep 17 00:00:00 2001 From: Jon Wayne Parrott Date: Tue, 8 Nov 2016 14:17:27 -0800 Subject: [PATCH 1/2] Add basic user guide --- docs/index.rst | 65 ++++++++--- docs/user-guide.rst | 267 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 319 insertions(+), 13 deletions(-) create mode 100644 docs/user-guide.rst diff --git a/docs/index.rst b/docs/index.rst index e7a17e330..2a926dfb2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,61 @@ -Welcome to ``google-auth``'s documentation! -=========================================== - -Contents: +google-auth +=========== .. toctree:: + :hidden: :maxdepth: 2 - reference/modules + user-guide + Reference + +``google-auth`` is the Google authentication library for Python. This library +provides the ability to authenticate to Google APIs using various methods. It +also provides integration with several HTTP libraries. + +- Support for Google :func:`Application Default Credentials `. +- Support for signing and verifying :mod:`JWTs `. +- Support for Google :mod:`Service Account credentials `. +- Support for :mod:`Google Compute Engine credentials `. +- Support for :mod:`Google App Engine standard credentials `. +- Support for various transports, including + :mod:`Requests `, + :mod:`urllib3 `, and + :mod:`gRPC `. + +Installing +---------- + +google-auth can be installed with `pip `_:: + + $ pip install google-auth + +google-auth is open-source, so you can alternatively grab the source code from +`GitHub`_ and install from source. + +.. _GitHub: https://github.com/GoogleCloudPlatform/google-auth-library-python + +Usage +----- + +The :doc:`user-guide` is the place to go to learn how to use the library and +accomplish common tasks. + +The :doc:`Module Reference ` documentation provides API-level documentation. + +License +------- -Reference documentation -======================= +google-auth is made available under the Apache License, Version 2.0. For more +details, see `LICENSE`_ -The :doc:`reference documentation ` details the complete API for :mod:`google.auth` and :mod:`google.oauth2`. +.. _LICENSE: + https://github.com/GoogleCloudPlatform/google-auth-library-python/LICENSE -Indices and tables -================== +Contributing +------------ -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +We happily welcome contributions, please see our `contributing`_ documentation +for details. +.. _contributing: + https://github.com/GoogleCloudPlatform/google-auth-library-python/CONTRIBUTING.rst diff --git a/docs/user-guide.rst b/docs/user-guide.rst new file mode 100644 index 000000000..6ba71d4fb --- /dev/null +++ b/docs/user-guide.rst @@ -0,0 +1,267 @@ +User Guide +========== + +.. currentmodule:: google.auth + +Credentials and account types +----------------------------- + +:class:`~credentials.Credentials` are the means of identifying an application or +user to a service or API. Credentials can be obtained with two different types +of accounts: *service accounts* and *user accounts*. Credentials from service +accounts identify a particular application. These types of credentials are used +in server-to-server use cases, such as accessing a database. Credentials from +user accounts are obtained by asking the user to authorize access to their data. +These types of credentials are used in cases where your application needs access +to a user's data in another service, such as accessing a user's documents in +Google Drive. + +This library primarily focuses on service account credentials and provides +some limited support for user credentials. + +Obtaining credentials +--------------------- + +.. _application-default: + +Application default credentials ++++++++++++++++++++++++++++++++ + +`Google Application Default Credentials`_ abstracts authentication across the +different Google Cloud Platform hosting environments. When running on any Google +Cloud hosting environment or when running locally with the `Google Cloud SDK`_ +installed :func:`default` can automatically determine the credentials from the +environment:: + + import google.auth + + credentials, project = google.auth.default() + +If your application requires specific scopes:: + + credentials, project = google.auth.default( + scopes=['https://www.googleapis.com/auth/cloud-platform']) + +.. _Google Application Default Credentials: + https://developers.google.com/identity/protocols/application-default-credentials +.. _Google Cloud SDK: https://cloud.google.com/sdk + + +Service account private key files ++++++++++++++++++++++++++++++++++ + +A service account private key file can be used to obtain credentials for a +service account. You can create a private key using the `Credentials page of the +Google Cloud Console`_. Once you have a private key you can either obtain +credentials one of two ways: + +1. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full + path to your service account private key file:: + + $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json + + Then, use :ref:`application default credentials `. + :func:`default` checks for the ``GOOGLE_APPLICATION_CREDENTIALS`` + environment variable before all other checks, so this will always use the + credentials you explicitly specify. + +2. Use :meth:`service_account.Credentials.from_service_account_file + `:: + + from google.oauth2 import service_account + + credentials = service_account.Credentials.from_service_account_file( + '/path/to/key.json') + + scoped_credentials = credentials.with_scopes( + ['https://www.googleapis.com/auth/cloud-platform']) + +.. warning:: Private keys must be kept secret. If you expose your private key it + is recommended to revoke it immediately from the Google Cloud Console. + +.. _Credentials page of the Google Cloud Console: + https://console.cloud.google.com/apis/credentials + +Compute Engine, Container Engine, and the App Engine flexible environment ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Applications running on `Compute Engine`_, `Container Engine`_, or the `App +Engine flexible environment`_ can obtain credentials provided by `Compute +Engine service accounts`_. When running on these platforms you can obtain +credentials for the service account one of two ways: + +1. Use :ref:`application default credentials `. + :func:`default` will automatically detect if these credentials are available. + +2. Use :class:`compute_engine.Credentials`:: + + from google.auth import compute_engine + + credentials = compute_engine.Credentials() + +.. _Compute Engine: https://cloud.google.com/compute +.. _Container Engine: https://cloud.google.com/container-engine +.. _App Engine flexible environment: + https://cloud.google.com/appengine/docs/flexible/ +.. _Compute Engine service accounts: + https://cloud.google.com/compute/docs/access/service-accounts + +The App Engine standard environment ++++++++++++++++++++++++++++++++++++ + +Applications running on the `App Engine standard environment`_ can obtain +credentials provided by the `App Engine App Identity API`_. You can obtain +credentials one of two ways: + +1. Use :ref:`application default credentials `. + :func:`default` will automatically detect if these credentials are available. + +2. Use :class:`app_engine.Credentials`:: + + from google.auth import app_engine + + credentials = app_engine.Credentials() + +.. _App Engine standard environment: + https://cloud.google.com/appengine/docs/python +.. _App Engine App Identity API: + https://cloud.google.com/appengine/docs/python/appidentity/ + +User credentials +++++++++++++++++ + +User credentials are typically obtained via `OAuth 2.0`_. This library does not +provide any support for *obtaining* user credentials, however, you can use user +credentials with this library. You can use libraries such as `oauthlib`_ or +`oauth2client`_ to obtain the access token. After you have an access token, you +can create a :class:`google.oauth2.credentials.Credentials` instance:: + + import google.oauth2.credentials + + credentials = google.oauth2.credentials.Credentials( + 'access_token') + +If you obtain a refresh token, you can also specify the refresh token and token +URI to allow the credentials to be automatically refreshed:: + + credentials = google.oauth2.credentials.Credentials( + 'access_token', + refresh_token='refresh_token', + token_uri='token_uri', + client_id='client_id', + client_secret='client_secret') + +.. _OAuth 2.0: + https://developers.google.com/identity/protocols/OAuth2 +.. _oauthlib: + https://oauthlib.readthedocs.io/en/latest/ +.. _oauth2client: + https://oauth2client.readthedocs.org + +Making authenticated requests +----------------------------- + +Once you have credentials you can attach them to a *transport*. You can then +use this transport to make authenticated requests to APIs. google-auth supports +several different transports. Typically, it's up to your application or an +opinionated client library to decide which transport to use. + +Requests +++++++++ + +The recommended HTTP transport is :mod:`google.auth.transport.requests` which +uses the `Requests`_ library. To make authenticated requests using Requests +you use a custom `Session`_ object:: + + from google.auth.transport.requests import AuthorizedSession + + authed_session = AuthorizedSession(credentials) + + response = authed_session.get( + 'https://www.googleapis.com/storage/v1/b') + +.. _Requests: http://docs.python-requests.org/en/master/ +.. _Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects + +Urllib3 ++++++++ + +:mod:`urllib3` is the underlying HTTP library used by Requests and can also be +used with google-auth. urllib3's interface isn't as high-level as Requests but +it can be useful in situations where you need more control over how HTTP +requests are made. To make authenticated requests using urllib3 create an +instance of :class:`google.auth.transport.urllib3.AuthorizedHttp`:: + + from google.auth.transport.urllib3 import AuthorizedHttp + + authed_http = AuthorizedHttp(credentials) + + response = authed_http.request( + 'GET', 'https://www.googleapis.com/storage/v1/b') + +You can also construct your own :class:`urllib3.PoolManager` instance and pass +it to :class:`~google.auth.transport.urllib3.AuthorizedHttp`:: + + import urllib3 + + http = urllib3.PoolManager() + authed_http = AuthorizedHttp(credentials, http) + +gRPC +++++ + +`gRPC`_ is an RPC framework that uses `Protocol Buffers`_ over `HTTP 2.0`_. +google-auth can provide `Call Credentials`_ for gRPC. The easiest way to do +this is to use google-auth to create the gRPC channel:: + + import google.auth.transport.grpc + import google.auth.transport.requests + + http_request = google.auth.transport.requests.Request() + + channel = google.auth.transport.grpc.secure_authorized_channel( + credentials, 'pubsub.googleapis.com:443', http_request) + +.. note:: Even though gRPC is its own transport, you still need to use one of + the other HTTP transports with gRPC. The reason is that most credential + types need to make HTTP requests in order to refresh their access token. + +Alternatively, you can create the channel yourself and use +:class:`google.auth.transport.grpc.AuthMetadataPlugin`:: + + import grpc + + metadata_plugin = AuthMetadataPlugin(credentials, http_request) + + # Create a set of grpc.CallCredentials using the metadata plugin. + google_auth_credentials = grpc.metadata_call_credentials( + metadata_plugin) + + # Create SSL channel credentials. + ssl_credentials = grpc.ssl_channel_credentials() + + # Combine the ssl credentials and the authorization credentials. + composite_credentials = grpc.composite_channel_credentials( + ssl_credentials, google_auth_credentials) + + channel = grpc.secure_channel( + 'pubsub.googleapis.com:443', composite_credentials) + +You can use this channel to make a gRPC stub that makes authenticated requests +to a gRPC service:: + + from google.pubsub.v1 import pubsub_pb2 + + pubsub = pubsub_pb2.PublisherStub(channel) + + response = pubsub.ListTopics( + pubsub_pb2.ListTopicsRequest(project='your-project')) + + +.. _gRPC: http://www.grpc.io/ +.. _Protocol Buffers: + https://developers.google.com/protocol-buffers/docs/overview +.. _HTTP 2.0: + http://www.grpc.io/docs/guides/wire.html +.. _Call Credentials: + http://www.grpc.io/docs/guides/auth.html From 546ad15e710cf36cc8d1bc4e60f303ff346fc53b Mon Sep 17 00:00:00 2001 From: Jon Wayne Parrott Date: Wed, 9 Nov 2016 11:09:05 -0800 Subject: [PATCH 2/2] Address review comments --- docs/index.rst | 7 ++++--- docs/user-guide.rst | 35 ++++++++++++++++++++++------------- 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 2a926dfb2..c0cbdbfab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,7 @@ google-auth user-guide Reference -``google-auth`` is the Google authentication library for Python. This library +google-auth is the Google authentication library for Python. This library provides the ability to authenticate to Google APIs using various methods. It also provides integration with several HTTP libraries. @@ -25,13 +25,14 @@ also provides integration with several HTTP libraries. Installing ---------- -google-auth can be installed with `pip `_:: +google-auth can be installed with `pip`_:: - $ pip install google-auth + $ pip install --upgrade google-auth google-auth is open-source, so you can alternatively grab the source code from `GitHub`_ and install from source. +.. _pip: https://pip.pypa.io .. _GitHub: https://github.com/GoogleCloudPlatform/google-auth-library-python Usage diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 6ba71d4fb..3d91d0854 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -8,16 +8,18 @@ Credentials and account types :class:`~credentials.Credentials` are the means of identifying an application or user to a service or API. Credentials can be obtained with two different types -of accounts: *service accounts* and *user accounts*. Credentials from service -accounts identify a particular application. These types of credentials are used -in server-to-server use cases, such as accessing a database. Credentials from -user accounts are obtained by asking the user to authorize access to their data. -These types of credentials are used in cases where your application needs access -to a user's data in another service, such as accessing a user's documents in -Google Drive. +of accounts: *service accounts* and *user accounts*. -This library primarily focuses on service account credentials and provides -some limited support for user credentials. +Credentials from service accounts identify a particular application. These types +of credentials are used in server-to-server use cases, such as accessing a +database. This library primarily focuses on service account credentials. + +Credentials from user accounts are obtained by asking the user to authorize +access to their data. These types of credentials are used in cases where your +application needs access to a user's data in another service, such as accessing +a user's documents in Google Drive. This library provides no support for +obtaining user credentials, but does provide limited support for using user +credentials. Obtaining credentials --------------------- @@ -30,7 +32,7 @@ Application default credentials `Google Application Default Credentials`_ abstracts authentication across the different Google Cloud Platform hosting environments. When running on any Google Cloud hosting environment or when running locally with the `Google Cloud SDK`_ -installed :func:`default` can automatically determine the credentials from the +installed, :func:`default` can automatically determine the credentials from the environment:: import google.auth @@ -43,7 +45,8 @@ If your application requires specific scopes:: scopes=['https://www.googleapis.com/auth/cloud-platform']) .. _Google Application Default Credentials: - https://developers.google.com/identity/protocols/application-default-credentials + https://developers.google.com/identity/protocols/ + application-default-credentials .. _Google Cloud SDK: https://cloud.google.com/sdk @@ -56,7 +59,9 @@ Google Cloud Console`_. Once you have a private key you can either obtain credentials one of two ways: 1. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full - path to your service account private key file:: + path to your service account private key file + + .. code-block:: bash $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json @@ -183,7 +188,7 @@ you use a custom `Session`_ object:: .. _Requests: http://docs.python-requests.org/en/master/ .. _Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects -Urllib3 +urllib3 +++++++ :mod:`urllib3` is the underlying HTTP library used by Requests and can also be @@ -225,6 +230,10 @@ this is to use google-auth to create the gRPC channel:: .. note:: Even though gRPC is its own transport, you still need to use one of the other HTTP transports with gRPC. The reason is that most credential types need to make HTTP requests in order to refresh their access token. + The sample above uses the Requests transport, but any HTTP transport can + be used. Additionally, if you know that your credentials do not need to + make HTTP requests in order to refresh (as is the case with + :class:`jwt.Credentials`) then you can specify ``None``. Alternatively, you can create the channel yourself and use :class:`google.auth.transport.grpc.AuthMetadataPlugin`::