blob: b8a6c49a1eba51c23b9c138c0a260130952e451d [file] [log] [blame]
salrashid1231fbc6792018-11-09 11:05:34 -08001# Copyright 2018 Google Inc.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""Google Cloud Impersonated credentials.
16
17This module provides authentication for applications where local credentials
18impersonates a remote service account using `IAM Credentials API`_.
19
20This class can be used to impersonate a service account as long as the original
21Credential object has the "Service Account Token Creator" role on the target
22service account.
23
24 .. _IAM Credentials API:
25 https://cloud.google.com/iam/credentials/reference/rest/
26"""
27
salrashid1237a8641a2019-08-07 14:31:33 -070028import base64
salrashid1231fbc6792018-11-09 11:05:34 -080029import copy
30from datetime import datetime
31import json
32
33import six
34from six.moves import http_client
35
36from google.auth import _helpers
37from google.auth import credentials
38from google.auth import exceptions
salrashid1237a8641a2019-08-07 14:31:33 -070039from google.auth import jwt
40from google.auth.transport.requests import AuthorizedSession
salrashid1231fbc6792018-11-09 11:05:34 -080041
42_DEFAULT_TOKEN_LIFETIME_SECS = 3600 # 1 hour in seconds
43
Bu Sun Kim9eec0912019-10-21 17:04:21 -070044_IAM_SCOPE = ["https://www.googleapis.com/auth/iam"]
salrashid1231fbc6792018-11-09 11:05:34 -080045
Bu Sun Kim9eec0912019-10-21 17:04:21 -070046_IAM_ENDPOINT = (
47 "https://iamcredentials.googleapis.com/v1/projects/-"
48 + "/serviceAccounts/{}:generateAccessToken"
49)
salrashid1231fbc6792018-11-09 11:05:34 -080050
Bu Sun Kim9eec0912019-10-21 17:04:21 -070051_IAM_SIGN_ENDPOINT = (
52 "https://iamcredentials.googleapis.com/v1/projects/-"
53 + "/serviceAccounts/{}:signBlob"
54)
salrashid1237a8641a2019-08-07 14:31:33 -070055
Bu Sun Kim9eec0912019-10-21 17:04:21 -070056_IAM_IDTOKEN_ENDPOINT = (
57 "https://iamcredentials.googleapis.com/v1/"
58 + "projects/-/serviceAccounts/{}:generateIdToken"
59)
salrashid1237a8641a2019-08-07 14:31:33 -070060
Bu Sun Kim9eec0912019-10-21 17:04:21 -070061_REFRESH_ERROR = "Unable to acquire impersonated credentials"
salrashid1231fbc6792018-11-09 11:05:34 -080062
salrashid1237a8641a2019-08-07 14:31:33 -070063_DEFAULT_TOKEN_LIFETIME_SECS = 3600 # 1 hour in seconds
64
Bu Sun Kim9eec0912019-10-21 17:04:21 -070065_DEFAULT_TOKEN_URI = "https://oauth2.googleapis.com/token"
salrashid1237a8641a2019-08-07 14:31:33 -070066
salrashid1231fbc6792018-11-09 11:05:34 -080067
bojeil-googled4d7f382021-02-16 12:33:20 -080068def _make_iam_token_request(
69 request, principal, headers, body, iam_endpoint_override=None
70):
salrashid1231fbc6792018-11-09 11:05:34 -080071 """Makes a request to the Google Cloud IAM service for an access token.
72 Args:
73 request (Request): The Request object to use.
74 principal (str): The principal to request an access token for.
75 headers (Mapping[str, str]): Map of headers to transmit.
76 body (Mapping[str, str]): JSON Payload body for the iamcredentials
77 API call.
bojeil-googled4d7f382021-02-16 12:33:20 -080078 iam_endpoint_override (Optiona[str]): The full IAM endpoint override
79 with the target_principal embedded. This is useful when supporting
80 impersonation with regional endpoints.
salrashid1231fbc6792018-11-09 11:05:34 -080081
82 Raises:
arithmetic17289d5a9a92020-06-03 10:47:36 -070083 google.auth.exceptions.TransportError: Raised if there is an underlying
84 HTTP connection error
85 google.auth.exceptions.RefreshError: Raised if the impersonated
86 credentials are not available. Common reasons are
87 `iamcredentials.googleapis.com` is not enabled or the
88 `Service Account Token Creator` is not assigned
salrashid1231fbc6792018-11-09 11:05:34 -080089 """
bojeil-googled4d7f382021-02-16 12:33:20 -080090 iam_endpoint = iam_endpoint_override or _IAM_ENDPOINT.format(principal)
salrashid1231fbc6792018-11-09 11:05:34 -080091
Bu Sun Kima57a7702020-01-10 13:17:34 -080092 body = json.dumps(body).encode("utf-8")
salrashid1231fbc6792018-11-09 11:05:34 -080093
Bu Sun Kim9eec0912019-10-21 17:04:21 -070094 response = request(url=iam_endpoint, method="POST", headers=headers, body=body)
salrashid1231fbc6792018-11-09 11:05:34 -080095
arithmetic17289b7228e2020-05-06 17:11:01 -070096 # support both string and bytes type response.data
arithmetic1728e115bae2020-05-06 16:00:17 -070097 response_body = (
98 response.data.decode("utf-8")
99 if hasattr(response.data, "decode")
100 else response.data
101 )
salrashid1231fbc6792018-11-09 11:05:34 -0800102
103 if response.status != http_client.OK:
104 exceptions.RefreshError(_REFRESH_ERROR, response_body)
105
106 try:
arithmetic1728e115bae2020-05-06 16:00:17 -0700107 token_response = json.loads(response_body)
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700108 token = token_response["accessToken"]
109 expiry = datetime.strptime(token_response["expireTime"], "%Y-%m-%dT%H:%M:%SZ")
salrashid1231fbc6792018-11-09 11:05:34 -0800110
111 return token, expiry
112
113 except (KeyError, ValueError) as caught_exc:
114 new_exc = exceptions.RefreshError(
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700115 "{}: No access token or invalid expiration in response.".format(
116 _REFRESH_ERROR
117 ),
118 response_body,
119 )
salrashid1231fbc6792018-11-09 11:05:34 -0800120 six.raise_from(new_exc, caught_exc)
121
122
Bu Sun Kim41599ae2020-09-02 12:55:42 -0600123class Credentials(credentials.CredentialsWithQuotaProject, credentials.Signing):
salrashid1231fbc6792018-11-09 11:05:34 -0800124 """This module defines impersonated credentials which are essentially
125 impersonated identities.
126
127 Impersonated Credentials allows credentials issued to a user or
128 service account to impersonate another. The target service account must
129 grant the originating credential principal the
130 `Service Account Token Creator`_ IAM role:
131
132 For more information about Token Creator IAM role and
133 IAMCredentials API, see
134 `Creating Short-Lived Service Account Credentials`_.
135
136 .. _Service Account Token Creator:
137 https://cloud.google.com/iam/docs/service-accounts#the_service_account_token_creator_role
138
139 .. _Creating Short-Lived Service Account Credentials:
140 https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials
141
142 Usage:
143
144 First grant source_credentials the `Service Account Token Creator`
145 role on the target account to impersonate. In this example, the
146 service account represented by svc_account.json has the
147 token creator role on
148 `impersonated-account@_project_.iam.gserviceaccount.com`.
149
salrashid123b29f2622018-11-12 09:49:16 -0800150 Enable the IAMCredentials API on the source project:
151 `gcloud services enable iamcredentials.googleapis.com`.
152
salrashid1231fbc6792018-11-09 11:05:34 -0800153 Initialize a source credential which does not have access to
154 list bucket::
155
Bu Sun Kim3319ea82020-12-07 11:00:03 -0700156 from google.oauth2 import service_account
salrashid1231fbc6792018-11-09 11:05:34 -0800157
158 target_scopes = [
159 'https://www.googleapis.com/auth/devstorage.read_only']
160
161 source_credentials = (
162 service_account.Credentials.from_service_account_file(
163 '/path/to/svc_account.json',
164 scopes=target_scopes))
165
166 Now use the source credentials to acquire credentials to impersonate
167 another service account::
168
169 from google.auth import impersonated_credentials
170
171 target_credentials = impersonated_credentials.Credentials(
172 source_credentials=source_credentials,
173 target_principal='impersonated-account@_project_.iam.gserviceaccount.com',
174 target_scopes = target_scopes,
175 lifetime=500)
176
177 Resource access is granted::
178
179 client = storage.Client(credentials=target_credentials)
180 buckets = client.list_buckets(project='your_project')
181 for bucket in buckets:
salrashid1237a8641a2019-08-07 14:31:33 -0700182 print(bucket.name)
salrashid1231fbc6792018-11-09 11:05:34 -0800183 """
184
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700185 def __init__(
186 self,
187 source_credentials,
188 target_principal,
189 target_scopes,
190 delegates=None,
191 lifetime=_DEFAULT_TOKEN_LIFETIME_SECS,
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700192 quota_project_id=None,
bojeil-googled4d7f382021-02-16 12:33:20 -0800193 iam_endpoint_override=None,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700194 ):
salrashid1231fbc6792018-11-09 11:05:34 -0800195 """
196 Args:
197 source_credentials (google.auth.Credentials): The source credential
198 used as to acquire the impersonated credentials.
199 target_principal (str): The service account to impersonate.
200 target_scopes (Sequence[str]): Scopes to request during the
201 authorization grant.
202 delegates (Sequence[str]): The chained list of delegates required
203 to grant the final access_token. If set, the sequence of
204 identities must have "Service Account Token Creator" capability
205 granted to the prceeding identity. For example, if set to
206 [serviceAccountB, serviceAccountC], the source_credential
207 must have the Token Creator role on serviceAccountB.
salrashid1237a8641a2019-08-07 14:31:33 -0700208 serviceAccountB must have the Token Creator on
209 serviceAccountC.
salrashid1231fbc6792018-11-09 11:05:34 -0800210 Finally, C must have Token Creator on target_principal.
211 If left unset, source_credential must have that role on
212 target_principal.
213 lifetime (int): Number of seconds the delegated credential should
salrashid123b29f2622018-11-12 09:49:16 -0800214 be valid for (upto 3600).
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700215 quota_project_id (Optional[str]): The project ID used for quota and billing.
216 This project may be different from the project used to
217 create the credentials.
bojeil-googled4d7f382021-02-16 12:33:20 -0800218 iam_endpoint_override (Optiona[str]): The full IAM endpoint override
219 with the target_principal embedded. This is useful when supporting
220 impersonation with regional endpoints.
salrashid1231fbc6792018-11-09 11:05:34 -0800221 """
222
223 super(Credentials, self).__init__()
224
225 self._source_credentials = copy.copy(source_credentials)
Bu Sun Kim82e224b2020-03-13 13:21:18 -0700226 # Service account source credentials must have the _IAM_SCOPE
227 # added to refresh correctly. User credentials cannot have
228 # their original scopes modified.
229 if isinstance(self._source_credentials, credentials.Scoped):
230 self._source_credentials = self._source_credentials.with_scopes(_IAM_SCOPE)
salrashid1231fbc6792018-11-09 11:05:34 -0800231 self._target_principal = target_principal
232 self._target_scopes = target_scopes
233 self._delegates = delegates
234 self._lifetime = lifetime
235 self.token = None
236 self.expiry = _helpers.utcnow()
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700237 self._quota_project_id = quota_project_id
bojeil-googled4d7f382021-02-16 12:33:20 -0800238 self._iam_endpoint_override = iam_endpoint_override
salrashid1231fbc6792018-11-09 11:05:34 -0800239
240 @_helpers.copy_docstring(credentials.Credentials)
241 def refresh(self, request):
salrashid1231fbc6792018-11-09 11:05:34 -0800242 self._update_token(request)
243
salrashid1231fbc6792018-11-09 11:05:34 -0800244 def _update_token(self, request):
245 """Updates credentials with a new access_token representing
246 the impersonated account.
247
248 Args:
249 request (google.auth.transport.requests.Request): Request object
250 to use for refreshing credentials.
251 """
252
arithmetic1728eb7be3f2020-05-28 11:01:24 -0700253 # Refresh our source credentials if it is not valid.
254 if not self._source_credentials.valid:
255 self._source_credentials.refresh(request)
salrashid1231fbc6792018-11-09 11:05:34 -0800256
salrashid1231fbc6792018-11-09 11:05:34 -0800257 body = {
258 "delegates": self._delegates,
259 "scope": self._target_scopes,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700260 "lifetime": str(self._lifetime) + "s",
salrashid1231fbc6792018-11-09 11:05:34 -0800261 }
262
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700263 headers = {"Content-Type": "application/json"}
salrashid1231fbc6792018-11-09 11:05:34 -0800264
265 # Apply the source credentials authentication info.
266 self._source_credentials.apply(headers)
267
268 self.token, self.expiry = _make_iam_token_request(
269 request=request,
270 principal=self._target_principal,
271 headers=headers,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700272 body=body,
bojeil-googled4d7f382021-02-16 12:33:20 -0800273 iam_endpoint_override=self._iam_endpoint_override,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700274 )
salrashid1237a8641a2019-08-07 14:31:33 -0700275
276 def sign_bytes(self, message):
277
278 iam_sign_endpoint = _IAM_SIGN_ENDPOINT.format(self._target_principal)
279
Aniruddha Maruca8d98a2020-05-15 14:52:50 -0700280 body = {
281 "payload": base64.b64encode(message).decode("utf-8"),
282 "delegates": self._delegates,
283 }
salrashid1237a8641a2019-08-07 14:31:33 -0700284
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700285 headers = {"Content-Type": "application/json"}
salrashid1237a8641a2019-08-07 14:31:33 -0700286
287 authed_session = AuthorizedSession(self._source_credentials)
288
289 response = authed_session.post(
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700290 url=iam_sign_endpoint, headers=headers, json=body
291 )
salrashid1237a8641a2019-08-07 14:31:33 -0700292
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700293 return base64.b64decode(response.json()["signedBlob"])
salrashid1237a8641a2019-08-07 14:31:33 -0700294
295 @property
296 def signer_email(self):
297 return self._target_principal
298
299 @property
300 def service_account_email(self):
301 return self._target_principal
302
303 @property
304 def signer(self):
305 return self
306
Bu Sun Kim41599ae2020-09-02 12:55:42 -0600307 @_helpers.copy_docstring(credentials.CredentialsWithQuotaProject)
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700308 def with_quota_project(self, quota_project_id):
309 return self.__class__(
310 self._source_credentials,
311 target_principal=self._target_principal,
312 target_scopes=self._target_scopes,
313 delegates=self._delegates,
314 lifetime=self._lifetime,
315 quota_project_id=quota_project_id,
bojeil-googled4d7f382021-02-16 12:33:20 -0800316 iam_endpoint_override=self._iam_endpoint_override,
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700317 )
318
salrashid1237a8641a2019-08-07 14:31:33 -0700319
Bu Sun Kim41599ae2020-09-02 12:55:42 -0600320class IDTokenCredentials(credentials.CredentialsWithQuotaProject):
salrashid1237a8641a2019-08-07 14:31:33 -0700321 """Open ID Connect ID Token-based service account credentials.
322
323 """
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700324
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700325 def __init__(
326 self,
327 target_credentials,
328 target_audience=None,
329 include_email=False,
330 quota_project_id=None,
331 ):
salrashid1237a8641a2019-08-07 14:31:33 -0700332 """
333 Args:
334 target_credentials (google.auth.Credentials): The target
335 credential used as to acquire the id tokens for.
336 target_audience (string): Audience to issue the token for.
337 include_email (bool): Include email in IdToken
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700338 quota_project_id (Optional[str]): The project ID used for
339 quota and billing.
salrashid1237a8641a2019-08-07 14:31:33 -0700340 """
341 super(IDTokenCredentials, self).__init__()
342
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700343 if not isinstance(target_credentials, Credentials):
344 raise exceptions.GoogleAuthError(
345 "Provided Credential must be " "impersonated_credentials"
346 )
salrashid1237a8641a2019-08-07 14:31:33 -0700347 self._target_credentials = target_credentials
348 self._target_audience = target_audience
349 self._include_email = include_email
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700350 self._quota_project_id = quota_project_id
salrashid1237a8641a2019-08-07 14:31:33 -0700351
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700352 def from_credentials(self, target_credentials, target_audience=None):
salrashid1237a8641a2019-08-07 14:31:33 -0700353 return self.__class__(
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700354 target_credentials=self._target_credentials,
355 target_audience=target_audience,
Pietro De Nicolaofd9b5b12020-12-11 20:00:30 +0100356 include_email=self._include_email,
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700357 quota_project_id=self._quota_project_id,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700358 )
salrashid1237a8641a2019-08-07 14:31:33 -0700359
360 def with_target_audience(self, target_audience):
361 return self.__class__(
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700362 target_credentials=self._target_credentials,
363 target_audience=target_audience,
Pietro De Nicolaofd9b5b12020-12-11 20:00:30 +0100364 include_email=self._include_email,
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700365 quota_project_id=self._quota_project_id,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700366 )
salrashid1237a8641a2019-08-07 14:31:33 -0700367
368 def with_include_email(self, include_email):
369 return self.__class__(
370 target_credentials=self._target_credentials,
371 target_audience=self._target_audience,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700372 include_email=include_email,
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700373 quota_project_id=self._quota_project_id,
374 )
375
Bu Sun Kim41599ae2020-09-02 12:55:42 -0600376 @_helpers.copy_docstring(credentials.CredentialsWithQuotaProject)
Bu Sun Kim3dda7b22020-07-09 10:39:39 -0700377 def with_quota_project(self, quota_project_id):
378 return self.__class__(
379 target_credentials=self._target_credentials,
380 target_audience=self._target_audience,
381 include_email=self._include_email,
382 quota_project_id=quota_project_id,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700383 )
salrashid1237a8641a2019-08-07 14:31:33 -0700384
385 @_helpers.copy_docstring(credentials.Credentials)
386 def refresh(self, request):
387
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700388 iam_sign_endpoint = _IAM_IDTOKEN_ENDPOINT.format(
389 self._target_credentials.signer_email
390 )
salrashid1237a8641a2019-08-07 14:31:33 -0700391
392 body = {
393 "audience": self._target_audience,
394 "delegates": self._target_credentials._delegates,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700395 "includeEmail": self._include_email,
salrashid1237a8641a2019-08-07 14:31:33 -0700396 }
397
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700398 headers = {"Content-Type": "application/json"}
salrashid1237a8641a2019-08-07 14:31:33 -0700399
arithmetic1728eb7be3f2020-05-28 11:01:24 -0700400 authed_session = AuthorizedSession(
401 self._target_credentials._source_credentials, auth_request=request
402 )
salrashid1237a8641a2019-08-07 14:31:33 -0700403
404 response = authed_session.post(
405 url=iam_sign_endpoint,
406 headers=headers,
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700407 data=json.dumps(body).encode("utf-8"),
408 )
salrashid1237a8641a2019-08-07 14:31:33 -0700409
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700410 id_token = response.json()["token"]
salrashid1237a8641a2019-08-07 14:31:33 -0700411 self.token = id_token
Bu Sun Kim9eec0912019-10-21 17:04:21 -0700412 self.expiry = datetime.fromtimestamp(jwt.decode(id_token, verify=False)["exp"])