Jon Wayne Parrott | 53c7b17 | 2016-11-10 10:44:30 -0800 | [diff] [blame] | 1 | User Guide |
| 2 | ========== |
| 3 | |
| 4 | .. currentmodule:: google.auth |
| 5 | |
| 6 | Credentials and account types |
| 7 | ----------------------------- |
| 8 | |
| 9 | :class:`~credentials.Credentials` are the means of identifying an application or |
| 10 | user to a service or API. Credentials can be obtained with two different types |
| 11 | of accounts: *service accounts* and *user accounts*. |
| 12 | |
| 13 | Credentials from service accounts identify a particular application. These types |
| 14 | of credentials are used in server-to-server use cases, such as accessing a |
| 15 | database. This library primarily focuses on service account credentials. |
| 16 | |
| 17 | Credentials from user accounts are obtained by asking the user to authorize |
| 18 | access to their data. These types of credentials are used in cases where your |
| 19 | application needs access to a user's data in another service, such as accessing |
| 20 | a user's documents in Google Drive. This library provides no support for |
| 21 | obtaining user credentials, but does provide limited support for using user |
| 22 | credentials. |
| 23 | |
| 24 | Obtaining credentials |
| 25 | --------------------- |
| 26 | |
| 27 | .. _application-default: |
| 28 | |
| 29 | Application default credentials |
| 30 | +++++++++++++++++++++++++++++++ |
| 31 | |
| 32 | `Google Application Default Credentials`_ abstracts authentication across the |
| 33 | different Google Cloud Platform hosting environments. When running on any Google |
| 34 | Cloud hosting environment or when running locally with the `Google Cloud SDK`_ |
| 35 | installed, :func:`default` can automatically determine the credentials from the |
| 36 | environment:: |
| 37 | |
| 38 | import google.auth |
| 39 | |
| 40 | credentials, project = google.auth.default() |
| 41 | |
| 42 | If your application requires specific scopes:: |
| 43 | |
| 44 | credentials, project = google.auth.default( |
| 45 | scopes=['https://www.googleapis.com/auth/cloud-platform']) |
| 46 | |
| 47 | .. _Google Application Default Credentials: |
| 48 | https://developers.google.com/identity/protocols/ |
| 49 | application-default-credentials |
| 50 | .. _Google Cloud SDK: https://cloud.google.com/sdk |
| 51 | |
| 52 | |
| 53 | Service account private key files |
| 54 | +++++++++++++++++++++++++++++++++ |
| 55 | |
| 56 | A service account private key file can be used to obtain credentials for a |
| 57 | service account. You can create a private key using the `Credentials page of the |
| 58 | Google Cloud Console`_. Once you have a private key you can either obtain |
| 59 | credentials one of two ways: |
| 60 | |
| 61 | 1. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full |
| 62 | path to your service account private key file |
| 63 | |
| 64 | .. code-block:: bash |
| 65 | |
| 66 | $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json |
| 67 | |
| 68 | Then, use :ref:`application default credentials <application-default>`. |
| 69 | :func:`default` checks for the ``GOOGLE_APPLICATION_CREDENTIALS`` |
| 70 | environment variable before all other checks, so this will always use the |
| 71 | credentials you explicitly specify. |
| 72 | |
| 73 | 2. Use :meth:`service_account.Credentials.from_service_account_file |
| 74 | <google.oauth2.service_account.Credentials.from_service_account_file>`:: |
| 75 | |
| 76 | from google.oauth2 import service_account |
| 77 | |
| 78 | credentials = service_account.Credentials.from_service_account_file( |
| 79 | '/path/to/key.json') |
| 80 | |
| 81 | scoped_credentials = credentials.with_scopes( |
| 82 | ['https://www.googleapis.com/auth/cloud-platform']) |
| 83 | |
| 84 | .. warning:: Private keys must be kept secret. If you expose your private key it |
| 85 | is recommended to revoke it immediately from the Google Cloud Console. |
| 86 | |
| 87 | .. _Credentials page of the Google Cloud Console: |
| 88 | https://console.cloud.google.com/apis/credentials |
| 89 | |
| 90 | Compute Engine, Container Engine, and the App Engine flexible environment |
| 91 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 92 | |
| 93 | Applications running on `Compute Engine`_, `Container Engine`_, or the `App |
| 94 | Engine flexible environment`_ can obtain credentials provided by `Compute |
| 95 | Engine service accounts`_. When running on these platforms you can obtain |
| 96 | credentials for the service account one of two ways: |
| 97 | |
| 98 | 1. Use :ref:`application default credentials <application-default>`. |
| 99 | :func:`default` will automatically detect if these credentials are available. |
| 100 | |
| 101 | 2. Use :class:`compute_engine.Credentials`:: |
| 102 | |
| 103 | from google.auth import compute_engine |
| 104 | |
| 105 | credentials = compute_engine.Credentials() |
| 106 | |
| 107 | .. _Compute Engine: https://cloud.google.com/compute |
| 108 | .. _Container Engine: https://cloud.google.com/container-engine |
| 109 | .. _App Engine flexible environment: |
| 110 | https://cloud.google.com/appengine/docs/flexible/ |
| 111 | .. _Compute Engine service accounts: |
| 112 | https://cloud.google.com/compute/docs/access/service-accounts |
| 113 | |
| 114 | The App Engine standard environment |
| 115 | +++++++++++++++++++++++++++++++++++ |
| 116 | |
| 117 | Applications running on the `App Engine standard environment`_ can obtain |
| 118 | credentials provided by the `App Engine App Identity API`_. You can obtain |
| 119 | credentials one of two ways: |
| 120 | |
| 121 | 1. Use :ref:`application default credentials <application-default>`. |
| 122 | :func:`default` will automatically detect if these credentials are available. |
| 123 | |
| 124 | 2. Use :class:`app_engine.Credentials`:: |
| 125 | |
| 126 | from google.auth import app_engine |
| 127 | |
| 128 | credentials = app_engine.Credentials() |
| 129 | |
| 130 | .. _App Engine standard environment: |
| 131 | https://cloud.google.com/appengine/docs/python |
| 132 | .. _App Engine App Identity API: |
| 133 | https://cloud.google.com/appengine/docs/python/appidentity/ |
| 134 | |
| 135 | User credentials |
| 136 | ++++++++++++++++ |
| 137 | |
| 138 | User credentials are typically obtained via `OAuth 2.0`_. This library does not |
Jon Wayne Parrott | 8170194 | 2017-03-01 14:03:38 -0800 | [diff] [blame] | 139 | provide any direct support for *obtaining* user credentials, however, you can |
| 140 | use user credentials with this library. You can use libraries such as |
| 141 | `oauthlib`_ to obtain the access token. After you have an access token, you |
Jon Wayne Parrott | 53c7b17 | 2016-11-10 10:44:30 -0800 | [diff] [blame] | 142 | can create a :class:`google.oauth2.credentials.Credentials` instance:: |
| 143 | |
| 144 | import google.oauth2.credentials |
| 145 | |
| 146 | credentials = google.oauth2.credentials.Credentials( |
| 147 | 'access_token') |
| 148 | |
| 149 | If you obtain a refresh token, you can also specify the refresh token and token |
| 150 | URI to allow the credentials to be automatically refreshed:: |
| 151 | |
| 152 | credentials = google.oauth2.credentials.Credentials( |
| 153 | 'access_token', |
| 154 | refresh_token='refresh_token', |
| 155 | token_uri='token_uri', |
| 156 | client_id='client_id', |
| 157 | client_secret='client_secret') |
| 158 | |
Jon Wayne Parrott | 8170194 | 2017-03-01 14:03:38 -0800 | [diff] [blame] | 159 | |
Jon Wayne Parrott | d47281b | 2017-03-22 13:45:26 -0700 | [diff] [blame^] | 160 | There is a separate library, `google-auth-oauthlib`_, that has some helpers |
| 161 | for integrating with `requests-oauthlib`_ to provide support for obtaining |
| 162 | user credentials. You can use |
| 163 | :func:`google_auth_oauthlib.helpers.credentials_from_session` to obtain |
Jon Wayne Parrott | 8170194 | 2017-03-01 14:03:38 -0800 | [diff] [blame] | 164 | :class:`google.oauth2.credentials.Credentials` from a |
| 165 | :class:`requests_oauthlib.OAuth2Session` as above:: |
| 166 | |
Jon Wayne Parrott | d47281b | 2017-03-22 13:45:26 -0700 | [diff] [blame^] | 167 | from google_auth_oauthlib.helpers import credentials_from_session |
Jon Wayne Parrott | 8170194 | 2017-03-01 14:03:38 -0800 | [diff] [blame] | 168 | |
Jon Wayne Parrott | d47281b | 2017-03-22 13:45:26 -0700 | [diff] [blame^] | 169 | google_auth_credentials = credentials_from_session(oauth2session) |
Jon Wayne Parrott | 8170194 | 2017-03-01 14:03:38 -0800 | [diff] [blame] | 170 | |
Jon Wayne Parrott | d47281b | 2017-03-22 13:45:26 -0700 | [diff] [blame^] | 171 | You can also use :class:`google_auth_oauthlib.flow.Flow` to perform the OAuth |
| 172 | 2.0 Authorization Grant Flow to obtain credentials using `requests-oauthlib`_. |
Jon Wayne Parrott | 8170194 | 2017-03-01 14:03:38 -0800 | [diff] [blame] | 173 | |
Jon Wayne Parrott | 53c7b17 | 2016-11-10 10:44:30 -0800 | [diff] [blame] | 174 | .. _OAuth 2.0: |
| 175 | https://developers.google.com/identity/protocols/OAuth2 |
| 176 | .. _oauthlib: |
| 177 | https://oauthlib.readthedocs.io/en/latest/ |
Jon Wayne Parrott | d47281b | 2017-03-22 13:45:26 -0700 | [diff] [blame^] | 178 | .. _google-auth-oauthlib: |
| 179 | https://pypi.python.org/pypi/google-auth-oauthlib |
Jon Wayne Parrott | 8170194 | 2017-03-01 14:03:38 -0800 | [diff] [blame] | 180 | .. _requests-oauthlib: |
| 181 | https://requests-oauthlib.readthedocs.io/en/latest/ |
Jon Wayne Parrott | 53c7b17 | 2016-11-10 10:44:30 -0800 | [diff] [blame] | 182 | |
| 183 | Making authenticated requests |
| 184 | ----------------------------- |
| 185 | |
| 186 | Once you have credentials you can attach them to a *transport*. You can then |
| 187 | use this transport to make authenticated requests to APIs. google-auth supports |
| 188 | several different transports. Typically, it's up to your application or an |
| 189 | opinionated client library to decide which transport to use. |
| 190 | |
| 191 | Requests |
| 192 | ++++++++ |
| 193 | |
| 194 | The recommended HTTP transport is :mod:`google.auth.transport.requests` which |
| 195 | uses the `Requests`_ library. To make authenticated requests using Requests |
| 196 | you use a custom `Session`_ object:: |
| 197 | |
| 198 | from google.auth.transport.requests import AuthorizedSession |
| 199 | |
| 200 | authed_session = AuthorizedSession(credentials) |
| 201 | |
| 202 | response = authed_session.get( |
| 203 | 'https://www.googleapis.com/storage/v1/b') |
| 204 | |
| 205 | .. _Requests: http://docs.python-requests.org/en/master/ |
| 206 | .. _Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects |
| 207 | |
| 208 | urllib3 |
| 209 | +++++++ |
| 210 | |
| 211 | :mod:`urllib3` is the underlying HTTP library used by Requests and can also be |
| 212 | used with google-auth. urllib3's interface isn't as high-level as Requests but |
| 213 | it can be useful in situations where you need more control over how HTTP |
| 214 | requests are made. To make authenticated requests using urllib3 create an |
| 215 | instance of :class:`google.auth.transport.urllib3.AuthorizedHttp`:: |
| 216 | |
| 217 | from google.auth.transport.urllib3 import AuthorizedHttp |
| 218 | |
| 219 | authed_http = AuthorizedHttp(credentials) |
| 220 | |
| 221 | response = authed_http.request( |
| 222 | 'GET', 'https://www.googleapis.com/storage/v1/b') |
| 223 | |
| 224 | You can also construct your own :class:`urllib3.PoolManager` instance and pass |
| 225 | it to :class:`~google.auth.transport.urllib3.AuthorizedHttp`:: |
| 226 | |
| 227 | import urllib3 |
| 228 | |
| 229 | http = urllib3.PoolManager() |
| 230 | authed_http = AuthorizedHttp(credentials, http) |
| 231 | |
| 232 | gRPC |
| 233 | ++++ |
| 234 | |
| 235 | `gRPC`_ is an RPC framework that uses `Protocol Buffers`_ over `HTTP 2.0`_. |
| 236 | google-auth can provide `Call Credentials`_ for gRPC. The easiest way to do |
| 237 | this is to use google-auth to create the gRPC channel:: |
| 238 | |
| 239 | import google.auth.transport.grpc |
| 240 | import google.auth.transport.requests |
| 241 | |
| 242 | http_request = google.auth.transport.requests.Request() |
| 243 | |
| 244 | channel = google.auth.transport.grpc.secure_authorized_channel( |
Jon Wayne Parrott | 840b3ac | 2016-11-10 12:07:51 -0800 | [diff] [blame] | 245 | credentials, http_request, 'pubsub.googleapis.com:443') |
Jon Wayne Parrott | 53c7b17 | 2016-11-10 10:44:30 -0800 | [diff] [blame] | 246 | |
| 247 | .. note:: Even though gRPC is its own transport, you still need to use one of |
| 248 | the other HTTP transports with gRPC. The reason is that most credential |
| 249 | types need to make HTTP requests in order to refresh their access token. |
| 250 | The sample above uses the Requests transport, but any HTTP transport can |
| 251 | be used. Additionally, if you know that your credentials do not need to |
| 252 | make HTTP requests in order to refresh (as is the case with |
| 253 | :class:`jwt.Credentials`) then you can specify ``None``. |
| 254 | |
| 255 | Alternatively, you can create the channel yourself and use |
| 256 | :class:`google.auth.transport.grpc.AuthMetadataPlugin`:: |
| 257 | |
| 258 | import grpc |
| 259 | |
| 260 | metadata_plugin = AuthMetadataPlugin(credentials, http_request) |
| 261 | |
| 262 | # Create a set of grpc.CallCredentials using the metadata plugin. |
| 263 | google_auth_credentials = grpc.metadata_call_credentials( |
| 264 | metadata_plugin) |
| 265 | |
| 266 | # Create SSL channel credentials. |
| 267 | ssl_credentials = grpc.ssl_channel_credentials() |
| 268 | |
| 269 | # Combine the ssl credentials and the authorization credentials. |
| 270 | composite_credentials = grpc.composite_channel_credentials( |
| 271 | ssl_credentials, google_auth_credentials) |
| 272 | |
| 273 | channel = grpc.secure_channel( |
| 274 | 'pubsub.googleapis.com:443', composite_credentials) |
| 275 | |
| 276 | You can use this channel to make a gRPC stub that makes authenticated requests |
| 277 | to a gRPC service:: |
| 278 | |
| 279 | from google.pubsub.v1 import pubsub_pb2 |
| 280 | |
| 281 | pubsub = pubsub_pb2.PublisherStub(channel) |
| 282 | |
| 283 | response = pubsub.ListTopics( |
| 284 | pubsub_pb2.ListTopicsRequest(project='your-project')) |
| 285 | |
| 286 | |
| 287 | .. _gRPC: http://www.grpc.io/ |
| 288 | .. _Protocol Buffers: |
| 289 | https://developers.google.com/protocol-buffers/docs/overview |
| 290 | .. _HTTP 2.0: |
| 291 | http://www.grpc.io/docs/guides/wire.html |
| 292 | .. _Call Credentials: |
| 293 | http://www.grpc.io/docs/guides/auth.html |