0
# External Account Credentials
1
2
Workload identity and external identity provider integration for multi-cloud and hybrid scenarios. Enables applications running outside Google Cloud to authenticate using external identity providers like AWS, Azure, or OIDC providers.
3
4
## Capabilities
5
6
### Base External Account Credentials
7
8
Base class for external account credentials supporting workload identity pools and external identity providers.
9
10
```python { .api }
11
class Credentials(
12
google.auth.credentials.Scoped,
13
google.auth.credentials.CredentialsWithQuotaProject
14
):
15
"""External account credentials for workload identity."""
16
17
def __init__(
18
self,
19
audience,
20
subject_token_type,
21
token_url,
22
service_account_impersonation_url=None,
23
client_id=None,
24
**kwargs
25
):
26
"""
27
Initialize external account credentials.
28
29
Args:
30
audience (str): The STS audience which is usually the fully specified
31
resource name of the workload identity pool
32
subject_token_type (str): The subject token type
33
token_url (str): The token server endpoint URI
34
service_account_impersonation_url (str): The optional STS impersonation endpoint
35
client_id (str): The STS endpoint client ID
36
"""
37
38
@classmethod
39
def from_file(cls, filename, **kwargs):
40
"""
41
Create credentials from external account file.
42
43
Args:
44
filename (str): Path to external account JSON file
45
**kwargs: Additional arguments
46
47
Returns:
48
Credentials: The constructed external account credentials
49
"""
50
51
@classmethod
52
def from_info(cls, info, **kwargs):
53
"""
54
Create credentials from external account info.
55
56
Args:
57
info (Mapping[str, str]): External account info in JSON format
58
**kwargs: Additional arguments
59
60
Returns:
61
Credentials: The constructed external account credentials
62
"""
63
```
64
65
### AWS Credentials
66
67
External account credentials for AWS workload identity, enabling applications running on AWS to authenticate to Google Cloud.
68
69
```python { .api }
70
class Credentials(google.auth.external_account.Credentials):
71
"""AWS workload identity credentials."""
72
73
def __init__(
74
self,
75
audience,
76
subject_token_type,
77
token_url,
78
aws_region=None,
79
aws_role_arn=None,
80
aws_session_name=None,
81
**kwargs
82
):
83
"""
84
Initialize AWS external account credentials.
85
86
Args:
87
audience (str): The STS audience (workload identity pool)
88
subject_token_type (str): The subject token type
89
token_url (str): The token server endpoint URI
90
aws_region (str): The AWS region for the credentials
91
aws_role_arn (str): The AWS role ARN to assume
92
aws_session_name (str): The AWS session name
93
"""
94
95
@classmethod
96
def from_file(cls, filename, **kwargs):
97
"""
98
Create AWS credentials from file.
99
100
Args:
101
filename (str): Path to AWS external account JSON file
102
**kwargs: Additional arguments
103
104
Returns:
105
Credentials: The constructed AWS credentials
106
"""
107
```
108
109
Usage example:
110
111
```python
112
from google.auth import aws
113
114
# Create AWS workload identity credentials
115
credentials = aws.Credentials.from_file(
116
'/path/to/aws-config.json',
117
scopes=['https://www.googleapis.com/auth/cloud-platform']
118
)
119
120
# Use with service account impersonation
121
credentials = aws.Credentials(
122
audience='//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider',
123
subject_token_type='urn:ietf:params:aws:token-type:aws4_request',
124
token_url='https://sts.googleapis.com/v1/token',
125
aws_region='us-east-1',
126
service_account_impersonation_url='https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/my-sa@project.iam.gserviceaccount.com:generateAccessToken'
127
)
128
```
129
130
### Identity Pool Credentials
131
132
Workload identity pool credentials for generic OIDC and SAML providers.
133
134
```python { .api }
135
class Credentials(google.auth.external_account.Credentials):
136
"""Workload identity pool credentials."""
137
138
def __init__(
139
self,
140
audience,
141
subject_token_type,
142
token_url,
143
credential_source,
144
**kwargs
145
):
146
"""
147
Initialize identity pool credentials.
148
149
Args:
150
audience (str): The STS audience (workload identity pool)
151
subject_token_type (str): The subject token type
152
token_url (str): The token server endpoint URI
153
credential_source (Mapping[str, str]): The credential source configuration
154
"""
155
156
@classmethod
157
def from_file(cls, filename, **kwargs):
158
"""
159
Create identity pool credentials from file.
160
161
Args:
162
filename (str): Path to identity pool JSON file
163
**kwargs: Additional arguments
164
165
Returns:
166
Credentials: The constructed identity pool credentials
167
"""
168
```
169
170
Usage example:
171
172
```python
173
from google.auth import identity_pool
174
175
# Create identity pool credentials
176
credentials = identity_pool.Credentials.from_file(
177
'/path/to/identity-pool-config.json'
178
)
179
180
# With credential source configuration
181
credentials = identity_pool.Credentials(
182
audience='//iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/my-pool/providers/my-provider',
183
subject_token_type='urn:ietf:params:oauth:token-type:id_token',
184
token_url='https://sts.googleapis.com/v1/token',
185
credential_source={
186
'file': '/var/run/secrets/token',
187
'format': {'type': 'text'}
188
}
189
)
190
```
191
192
### External Account Authorized User
193
194
External account credentials for authorized users with refresh tokens.
195
196
```python { .api }
197
class Credentials(google.auth.credentials.Credentials):
198
"""External account authorized user credentials."""
199
200
def __init__(
201
self,
202
token,
203
refresh_token,
204
client_id,
205
client_secret,
206
token_url,
207
**kwargs
208
):
209
"""
210
Initialize external account authorized user credentials.
211
212
Args:
213
token (str): The OAuth 2.0 access token
214
refresh_token (str): The refresh token
215
client_id (str): The OAuth 2.0 client identifier
216
client_secret (str): The OAuth 2.0 client secret
217
token_url (str): The token server endpoint URI
218
"""
219
220
@classmethod
221
def from_file(cls, filename, **kwargs):
222
"""
223
Create credentials from external account authorized user file.
224
225
Args:
226
filename (str): Path to external account authorized user JSON file
227
**kwargs: Additional arguments
228
229
Returns:
230
Credentials: The constructed credentials
231
"""
232
```
233
234
### Pluggable Credentials
235
236
Third-party pluggable credential source for custom external authentication providers.
237
238
```python { .api }
239
class Credentials(google.auth.external_account.Credentials):
240
"""Third-party pluggable credentials."""
241
242
def __init__(
243
self,
244
audience,
245
subject_token_type,
246
token_url,
247
pluggable_source,
248
**kwargs
249
):
250
"""
251
Initialize pluggable credentials.
252
253
Args:
254
audience (str): The STS audience
255
subject_token_type (str): The subject token type
256
token_url (str): The token server endpoint URI
257
pluggable_source (Mapping[str, str]): The pluggable source configuration
258
"""
259
```
260
261
## External Account Configuration
262
263
External account configuration file format:
264
265
```python { .api }
266
ExternalAccountInfo = TypedDict('ExternalAccountInfo', {
267
'type': str, # Always "external_account"
268
'audience': str, # Workload identity pool audience
269
'subject_token_type': str, # Subject token type
270
'token_url': str, # STS token endpoint
271
'credential_source': Dict[str, Any], # Credential source configuration
272
'service_account_impersonation_url': str, # Optional impersonation URL
273
'client_id': str, # Optional client ID
274
'quota_project_id': str, # Optional quota project
275
}, total=False)
276
277
CredentialSource = TypedDict('CredentialSource', {
278
'file': str, # File-based credential source
279
'url': str, # URL-based credential source
280
'headers': Dict[str, str], # Optional headers for URL source
281
'format': Dict[str, str], # Token format configuration
282
'regional_cred_verification_url': str, # AWS regional verification URL
283
}, total=False)
284
```
285
286
## STS (Security Token Service)
287
288
Token exchange functionality for external account flows:
289
290
```python { .api }
291
class Client:
292
"""STS client for token exchange."""
293
294
def __init__(self, token_url):
295
"""
296
Initialize STS client.
297
298
Args:
299
token_url (str): The STS token endpoint URL
300
"""
301
302
def exchange_token(
303
self,
304
request,
305
grant_type,
306
subject_token,
307
subject_token_type,
308
audience,
309
scopes=None,
310
**kwargs
311
):
312
"""
313
Exchange a subject token for a Google access token.
314
315
Args:
316
request (google.auth.transport.Request): HTTP transport
317
grant_type (str): The OAuth 2.0 grant type
318
subject_token (str): The subject token to exchange
319
subject_token_type (str): The subject token type
320
audience (str): The STS audience
321
scopes (Sequence[str]): Optional scopes
322
323
Returns:
324
Mapping[str, str]: The STS token response
325
"""
326
327
def exchange_token(
328
request,
329
token_url,
330
grant_type,
331
subject_token,
332
subject_token_type,
333
audience,
334
**kwargs
335
):
336
"""
337
Exchange subject token for access token via STS.
338
339
Args:
340
request (google.auth.transport.Request): HTTP transport
341
token_url (str): The STS token endpoint
342
grant_type (str): The OAuth 2.0 grant type
343
subject_token (str): The subject token
344
subject_token_type (str): The subject token type
345
audience (str): The STS audience
346
347
Returns:
348
Mapping[str, str]: The token response
349
"""
350
```
351
352
## Error Handling
353
354
```python { .api }
355
class RefreshError(google.auth.exceptions.GoogleAuthError):
356
"""Raised when external account credentials cannot be refreshed."""
357
358
class DefaultCredentialsError(google.auth.exceptions.GoogleAuthError):
359
"""Raised when external account credentials cannot be loaded."""
360
```
361
362
Common external account error scenarios:
363
- Invalid workload identity pool configuration
364
- Subject token retrieval failures
365
- STS token exchange failures
366
- Service account impersonation errors
367
- Network issues accessing external token sources
368
- Invalid credential source configuration
369
- Insufficient permissions for workload identity pool access