-
Notifications
You must be signed in to change notification settings - Fork 229
/
README.md
1301 lines (1045 loc) · 64.1 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Google Auth Library
Open source authentication client library for Java.
[](http://github.com/badges/stability-badges)
[](https://img.shields.io/maven-central/v/com.google.auth/google-auth-library-credentials.svg)
- [API Documentation](https://googleapis.dev/java/google-auth-library/latest)
This project consists of 3 artifacts:
- [*google-auth-library-credentials*](#google-auth-library-credentials): contains base classes and
interfaces for Google credentials
- [*google-auth-library-appengine*](#google-auth-library-appengine): contains App Engine
credentials. This artifact depends on the App Engine SDK.
- [*google-auth-library-oauth2-http*](#google-auth-library-oauth2-http): contains a wide variety of
credentials as well as utility methods to create them and to get Application Default Credentials
**Table of contents:**
* [Quickstart](#quickstart)
* [google-auth-library-oauth2-http](#google-auth-library-oauth2-http)
* [Application Default Credentials](#application-default-credentials)
* [ImpersonatedCredentials](#impersonatedcredentials)
* [Workload Identity Federation](#workload-identity-federation)
* [Accessing resources from AWS](#accessing-resources-from-aws)
* [Accessing resources from Azure](#access-resources-from-microsoft-azure)
* [Accessing resources from an OIDC identity provider](#accessing-resources-from-an-oidc-identity-provider)
* [Accessing resources using Executable-sourced credentials](#using-executable-sourced-credentials-with-oidc-and-saml)
* [Accessing resources using a custom supplier for OIDC or SAML](#using-a-custom-supplier-with-oidc-and-saml)
* [Accessing resources using a custom supplier with AWS](#using-a-custom-supplier-with-aws)
* [Configurable Token Lifetime](#configurable-token-lifetime)
* [Workforce Identity Federation](#workforce-identity-federation)
* [Accessing resources using an OIDC or SAML 2.0 identity provider](#accessing-resources-using-an-oidc-or-saml-20-identity-provider)
* [Accessing resources using external account authorized user workforce credentials](#using-external-account-authorized-user-workforce-credentials)
* [Accessing resources using Executable-sourced credentials](#using-executable-sourced-workforce-credentials-with-oidc-and-saml)
* [Accessing resources using a custom supplier for OIDC or SAML](#using-a-custom-supplier-for-workforce-credentials-with-oidc-and-saml)
* [Downscoping with Credential Access Boundaries](#downscoping-with-credential-access-boundaries)
* [Configuring a Proxy](#configuring-a-proxy)
* [Using Credentials with google-http-client](#using-credentials-with-google-http-client)
* [Verifying JWT Tokens](#verifying-a-signature)
* [google-auth-library-credentials](#google-auth-library-credentials)
* [google-auth-library-appengine](#google-auth-library-appengine)
* [CI Status](#ci-status)
* [Contributing](#contributing)
* [License](#license)
## Quickstart
If you are using Maven, add this to your pom.xml file (notice that you can replace
`google-auth-library-oauth2-http` with any of `google-auth-library-credentials` and
`google-auth-library-appengine`, depending on your application needs):
[//]: # ({x-version-update-start:google-auth-library-oauth2-http:released})
```xml
<dependency>
<groupId>com.google.auth</groupId>
<artifactId>google-auth-library-oauth2-http</artifactId>
<version>1.19.0</version>
</dependency>
```
[//]: # ({x-version-update-end})
If you are using Gradle, add this to your dependencies
[//]: # ({x-version-update-start:google-auth-library-oauth2-http:released})
```Groovy
implementation 'com.google.auth:google-auth-library-oauth2-http:1.19.0'
```
[//]: # ({x-version-update-end})
If you are using SBT, add this to your dependencies
[//]: # ({x-version-update-start:google-auth-library-oauth2-http:released})
```Scala
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.19.0"
```
[//]: # ({x-version-update-end})
## google-auth-library-oauth2-http
### Application Default Credentials
This library provides an implementation of
[Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
for Java. Application Default Credentials provide a simple way to get authorization
credentials for use in calling Google APIs.
They are best suited for cases when the call needs to have the same identity and
authorization level for the application independent of the user. This is the recommended
approach to authorize calls to Cloud APIs, particularly when you're building an application
that uses Google Cloud Platform.
Application Default Credentials also support workload identity federation to access
Google Cloud resources from non-Google Cloud platforms including Amazon Web Services (AWS),
Microsoft Azure or any identity provider that supports OpenID Connect (OIDC). Workload
identity federation is recommended for non-Google Cloud environments as it avoids the
need to download, manage and store service account private keys locally, see:
[Workload Identity Federation](#workload-identity-federation).
#### Getting Application Default Credentials
To get Application Default Credentials use `GoogleCredentials.getApplicationDefault()` or
`GoogleCredentials.getApplicationDefault(HttpTransportFactory)`. These methods return the
Application Default Credentials which are used to identify and authorize the whole application. The
following are searched (in order) to find the Application Default Credentials:
1. Credentials file pointed to by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
2. Credentials provided by the Google Cloud SDK `gcloud auth application-default login` command
3. Google App Engine built-in credentials
4. Google Cloud Shell built-in credentials
5. Google Compute Engine built-in credentials
- Skip this check by setting the environment variable `NO_GCE_CHECK=true`
- Customize the GCE metadata server address by setting the environment variable `GCE_METADATA_HOST=<hostname>`
#### Explicit Credential Loading
To get Credentials from a Service Account JSON key use `GoogleCredentials.fromStream(InputStream)`
or `GoogleCredentials.fromStream(InputStream, HttpTransportFactory)`. Note that the credentials must
be refreshed before the access token is available.
```java
GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();
```
### ImpersonatedCredentials
Allows a credentials issued to a user or service account to
impersonate another. The source project using ImpersonatedCredentials must enable the
"IAMCredentials" API. Also, the target service account must grant the orginating principal
the "Service Account Token Creator" IAM role.
```java
String credPath = "/path/to/svc_account.json";
ServiceAccountCredentials sourceCredentials = ServiceAccountCredentials
.fromStream(new FileInputStream(credPath));
sourceCredentials = (ServiceAccountCredentials) sourceCredentials
.createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));
ImpersonatedCredentials targetCredentials = ImpersonatedCredentials.create(sourceCredentials,
"[email protected]", null,
Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"), 300);
Storage storage_service = StorageOptions.newBuilder().setProjectId("project-id")
.setCredentials(targetCredentials).build().getService();
for (Bucket b : storage_service.list().iterateAll())
System.out.println(b);
```
### Workload Identity Federation
Using workload identity federation, your application can access Google Cloud resources from
Amazon Web Services (AWS), Microsoft Azure, or any identity provider that supports OpenID Connect
(OIDC).
Traditionally, applications running outside Google Cloud have used service account keys to access
Google Cloud resources. Using identity federation, your workload can impersonate a service account.
This lets the external workload access Google Cloud resources directly, eliminating the maintenance
and security burden associated with service account keys.
#### Accessing resources from AWS
In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements
are needed:
- A workload identity pool needs to be created.
- AWS needs to be added as an identity provider in the workload identity pool (the Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from AWS).
- Permission to impersonate a service account needs to be granted to the external identity.
Follow the detailed [instructions](https://cloud.google.com/iam/docs/access-resources-aws) on how to
configure workload identity federation from AWS.
After configuring the AWS provider to impersonate a service account, a credential configuration file
needs to be generated. Unlike service account credential files, the generated credential
configuration file contains non-sensitive metadata to instruct the library on how to
retrieve external subject tokens and exchange them for service account access tokens.
The configuration file can be generated by using the [gcloud CLI](https://cloud.google.com/sdk/).
To generate the AWS workload identity configuration, run the following command:
```bash
# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$AWS_PROVIDER_ID \
--service-account $SERVICE_ACCOUNT_EMAIL \
--aws \
--output-file /path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$PROJECT_NUMBER`: The Google Cloud project number.
- `$POOL_ID`: The workload identity pool ID.
- `$AWS_PROVIDER_ID`: The AWS provider ID.
- `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate.
This generates the configuration file in the specified output file.
If you are using [AWS IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html), an additional flag `--enable-imdsv2` needs to be added to the `gcloud iam workload-identity-pools create-cred-config` command:
```bash
gcloud iam workload-identity-pools create-cred-config \
projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$AWS_PROVIDER_ID \
--service-account $SERVICE_ACCOUNT_EMAIL \
--aws \
--output-file /path/to/generated/config.json \
--enable-imdsv2
```
You can now [use the Auth library](#using-external-identities) to call Google Cloud
resources from AWS.
#### Access resources from Microsoft Azure
In order to access Google Cloud resources from Microsoft Azure, the following requirements are
needed:
- A workload identity pool needs to be created.
- Azure needs to be added as an identity provider in the workload identity pool (the Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from Azure).
- The Azure tenant needs to be configured for identity federation.
- Permission to impersonate a service account needs to be granted to the external identity.
Follow the detailed [instructions](https://cloud.google.com/iam/docs/access-resources-azure) on how
to configure workload identity federation from Microsoft Azure.
After configuring the Azure provider to impersonate a service account, a credential configuration
file needs to be generated. Unlike service account credential files, the generated credential
configuration file contains non-sensitive metadata to instruct the library on how to
retrieve external subject tokens and exchange them for service account access tokens.
The configuration file can be generated by using the [gcloud CLI](https://cloud.google.com/sdk/).
To generate the Azure workload identity configuration, run the following command:
```bash
# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$AZURE_PROVIDER_ID \
--service-account $SERVICE_ACCOUNT_EMAIL \
--azure \
--output-file /path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$PROJECT_NUMBER`: The Google Cloud project number.
- `$POOL_ID`: The workload identity pool ID.
- `$AZURE_PROVIDER_ID`: The Azure provider ID.
- `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate.
This generates the configuration file in the specified output file.
You can now [use the Auth library](#using-external-identities) to call Google Cloud
resources from Azure.
#### Accessing resources from an OIDC identity provider
In order to access Google Cloud resources from an identity provider that supports [OpenID Connect (OIDC)](https://openid.net/connect/), the following requirements are needed:
- A workload identity pool needs to be created.
- An OIDC identity provider needs to be added in the workload identity pool (the Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from the identity provider).
- Permission to impersonate a service account needs to be granted to the external identity.
Follow the detailed [instructions](https://cloud.google.com/iam/docs/access-resources-oidc) on how
to configure workload identity federation from an OIDC identity provider.
After configuring the OIDC provider to impersonate a service account, a credential configuration
file needs to be generated. Unlike service account credential files, the generated credential
configuration file contains non-sensitive metadata to instruct the library on how to
retrieve external subject tokens and exchange them for service account access tokens.
The configuration file can be generated by using the [gcloud CLI](https://cloud.google.com/sdk/).
For OIDC providers, the Auth library can retrieve OIDC tokens either from a local file location
(file-sourced credentials) or from a local server (URL-sourced credentials).
**File-sourced credentials**
For file-sourced credentials, a background process needs to be continuously refreshing the file
location with a new OIDC token prior to expiration. For tokens with one hour lifetimes, the token
needs to be updated in the file every hour. The token can be stored directly as plain text or in
JSON format.
To generate a file-sourced OIDC configuration, run the following command:
```bash
# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$OIDC_PROVIDER_ID \
--service-account $SERVICE_ACCOUNT_EMAIL \
--credential-source-file $PATH_TO_OIDC_ID_TOKEN \
# Optional arguments for file types. Default is "text":
# --credential-source-type "json" \
# Optional argument for the field that contains the OIDC credential.
# This is required for json.
# --credential-source-field-name "id_token" \
--output-file /path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$PROJECT_NUMBER`: The Google Cloud project number.
- `$POOL_ID`: The workload identity pool ID.
- `$OIDC_PROVIDER_ID`: The OIDC provider ID.
- `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate.
- `$PATH_TO_OIDC_ID_TOKEN`: The file path used to retrieve the OIDC token.
This generates the configuration file in the specified output file.
**URL-sourced credentials**
For URL-sourced credentials, a local server needs to host a GET endpoint to return the OIDC token.
The response can be in plain text or JSON. Additional required request headers can also be
specified.
To generate a URL-sourced OIDC workload identity configuration, run the following command:
```bash
# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$OIDC_PROVIDER_ID \
--service-account $SERVICE_ACCOUNT_EMAIL \
--credential-source-url $URL_TO_GET_OIDC_TOKEN \
--credential-source-headers $HEADER_KEY=$HEADER_VALUE \
# Optional arguments for file types. Default is "text":
# --credential-source-type "json" \
# Optional argument for the field that contains the OIDC credential.
# This is required for json.
# --credential-source-field-name "id_token" \
--output-file /path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$PROJECT_NUMBER`: The Google Cloud project number.
- `$POOL_ID`: The workload identity pool ID.
- `$OIDC_PROVIDER_ID`: The OIDC provider ID.
- `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate.
- `$URL_TO_GET_OIDC_TOKEN`: The URL of the local server endpoint to call to retrieve the OIDC token.
- `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET
request to `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`.
You can now [use the Auth library](#using-external-identities) to call Google Cloud
resources from an OIDC provider.
#### Using Executable-sourced credentials with OIDC and SAML
**Executable-sourced credentials**
For executable-sourced credentials, a local executable is used to retrieve the 3rd party token.
The executable must handle providing a valid, unexpired OIDC ID token or SAML assertion in JSON format
to stdout.
To use executable-sourced credentials, the `GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES`
environment variable must be set to `1`.
To generate an executable-sourced workload identity configuration, run the following command:
```bash
# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID \
--service-account=$SERVICE_ACCOUNT_EMAIL \
--subject-token-type=$SUBJECT_TOKEN_TYPE \
# The absolute path for the program, including arguments.
# e.g. --executable-command="/path/to/command --foo=bar"
--executable-command=$EXECUTABLE_COMMAND \
# Optional argument for the executable timeout. Defaults to 30s.
# --executable-timeout-millis=$EXECUTABLE_TIMEOUT \
# Optional argument for the absolute path to the executable output file.
# See below on how this argument impacts the library behaviour.
# --executable-output-file=$EXECUTABLE_OUTPUT_FILE \
--output-file /path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$PROJECT_NUMBER`: The Google Cloud project number.
- `$POOL_ID`: The workload identity pool ID.
- `$PROVIDER_ID`: The OIDC or SAML provider ID.
- `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate.
- `$SUBJECT_TOKEN_TYPE`: The subject token type.
- `$EXECUTABLE_COMMAND`: The full command to run, including arguments. Must be an absolute path to the program.
The `--executable-timeout-millis` flag is optional. This is the duration for which
the auth library will wait for the executable to finish, in milliseconds.
Defaults to 30 seconds when not provided. The maximum allowed value is 2 minutes.
The minimum is 5 seconds.
The `--executable-output-file` flag is optional. If provided, the file path must
point to the 3PI credential response generated by the executable. This is useful
for caching the credentials. By specifying this path, the Auth libraries will first
check for its existence before running the executable. By caching the executable JSON
response to this file, it improves performance as it avoids the need to run the executable
until the cached credentials in the output file are expired. The executable must
handle writing to this file - the auth libraries will only attempt to read from
this location. The format of contents in the file should match the JSON format
expected by the executable shown below.
To retrieve the 3rd party token, the library will call the executable
using the command specified. The executable's output must adhere to the response format
specified below. It must output the response to stdout.
A sample successful executable OIDC response:
```json
{
"version": 1,
"success": true,
"token_type": "urn:ietf:params:oauth:token-type:id_token",
"id_token": "HEADER.PAYLOAD.SIGNATURE",
"expiration_time": 1620499962
}
```
A sample successful executable SAML response:
```json
{
"version": 1,
"success": true,
"token_type": "urn:ietf:params:oauth:token-type:saml2",
"saml_response": "...",
"expiration_time": 1620499962
}
```
A sample executable error response:
```json
{
"version": 1,
"success": false,
"code": "401",
"message": "Caller not authorized."
}
```
These are all required fields for an error response. The code and message
fields will be used by the library as part of the thrown exception.
For successful responses, the `expiration_time` field is only required
when an output file is specified in the credential configuration.
Response format fields summary:
* `version`: The version of the JSON output. Currently only version 1 is supported.
* `success`: When true, the response must contain the 3rd party token and token type. The response must also contain
the expiration_time field if an output file was specified in the credential configuration. The executable must also
exit with exit code 0. When false, the response must contain the error code and message fields and exit with a
non-zero value.
* `token_type`: The 3rd party subject token type. Must be *urn:ietf:params:oauth:token-type:jwt*,
*urn:ietf:params:oauth:token-type:id_token*, or *urn:ietf:params:oauth:token-type:saml2*.
* `id_token`: The 3rd party OIDC token.
* `saml_response`: The 3rd party SAML response.
* `expiration_time`: The 3rd party subject token expiration time in seconds (unix epoch time).
* `code`: The error code string.
* `message`: The error message.
All response types must include both the `version` and `success` fields.
* Successful responses must include the `token_type` and one of
`id_token` or `saml_response`. The `expiration_time` field must also be present if an output file was specified in
the credential configuration.
* Error responses must include both the `code` and `message` fields.
The library will populate the following environment variables when the executable is run:
* `GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE`: The audience field from the credential configuration. Always present.
* `GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE`: This expected subject token type. Always present.
* `GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL`: The service account email. Only present when service account impersonation is used.
* `GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE`: The output file location from the credential configuration. Only present when specified in the credential configuration.
These environment variables can be used by the executable to avoid hard-coding these values.
##### Security considerations
The following security practices are highly recommended:
* Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script.
* The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion.
Given the complexity of using executable-sourced credentials, it is recommended to use
the existing supported mechanisms (file-sourced/URL-sourced) for providing 3rd party
credentials unless they do not meet your specific requirements.
You can now [use the Auth library](#using-external-identities) to call Google Cloud
resources from an OIDC or SAML provider.
#### Using a custom supplier with OIDC and SAML
A custom implementation of IdentityPoolSubjectTokenSupplier can be used while building IdentityPoolCredentials
to supply a subject token which can be exchanged for a GCP access token. The supplier must return a valid,
unexpired subject token when called by the GCP credential.
IdentityPoolCredentials do not cache the returned token, so caching logic should be
implemented in the token supplier to prevent multiple requests for the same subject token.
```java
import java.io.IOException;
public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {
@Override
public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
// Any call to the supplier will pass a context object with the requested
// audience and subject token type.
string audience = context.getAudience();
string tokenType = context.getSubjectTokenType();
try {
// Return a valid, unexpired token for the requested audience and token type.
// Note that IdentityPoolCredentials do not cache the subject token so
// any caching logic needs to be implemented in the token supplier.
return retrieveToken(audience, tokenType);
} catch (Exception e) {
// If token is unavailable, throw IOException.
throw new IOException(e);
}
}
private String retrieveToken(string tokenType, string audience) {
// Retrieve a subject token of the requested type for the requested audience.
}
}
```
```java
CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
IdentityPoolCredentials.newBuilder()
.setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
.setAudience(...) // Sets the GCP audience.
.setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
.build();
```
Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience) is:
```//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID```
Where the following variables need to be substituted:
- `$PROJECT_NUMBER`: The Google Cloud project number.
- `$WORKLOAD_POOL_ID`: The workload identity pool ID.
- `$PROVIDER_ID`: The provider ID.
The values for audience, service account impersonation URL, and any other builder field can also be found by
generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config).
#### Using a custom supplier with AWS
A custom implementation of AwsSecurityCredentialsSupplier can be provided when initializing AwsCredentials. If provided, the AwsCredentials instance will defer to the supplier to retrieve AWS security credentials to exchange for a GCP access token.
The supplier must return valid, unexpired AWS security credentials when called by the GCP credential.
AwsCredentials do not cache the returned AWS security credentials or region, so caching logic should be
implemented in the supplier to prevent multiple requests for the same resources.
```java
class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
@Override
AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
// Any call to the supplier will pass a context object with the requested
// audience.
string audience = context.getAudience();
try {
// Return valid, unexpired AWS security credentials for the requested audience.
// Note that AwsCredentials do not cache the AWS security credentials so
// any caching logic needs to be implemented in the credentials' supplier.
return retrieveAwsSecurityCredentials(audience);
} catch (Exception e) {
// If credentials are unavailable, throw IOException.
throw new IOException(e);
}
}
@Override
String getRegion(ExternalAccountSupplierContext context) throws IOException {
try {
// Return a valid AWS region. i.e. "us-east-2".
// Note that AwsCredentials do not cache the region so
// any caching logic needs to be implemented in the credentials' supplier.
return retrieveAwsRegion();
} catch (Exception e) {
// If region is unavailable, throw IOException.
throw new IOException(e);
}
}
private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
// Retrieve Aws security credentials for the requested audience.
}
private String retrieveAwsRegion() {
// Retrieve current AWS region.
}
}
```
```java
CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
.setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
.setAudience(...) // Sets the GCP audience.
.setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
.build();
```
Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience) is:
```//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID```
Where the following variables need to be substituted:
- `$PROJECT_NUMBER`: The Google Cloud project number.
- `$WORKLOAD_POOL_ID`: The workload identity pool ID.
- `$PROVIDER_ID`: The provider ID.
The values for audience, service account impersonation URL, and any other builder field can also be found by
generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config).
#### Configurable Token Lifetime
When creating a credential configuration with workload identity federation using service account impersonation, you can provide an optional argument to configure the service account access token lifetime.
To generate the configuration with configurable token lifetime, run the following command (this example uses an AWS configuration, but the token lifetime can be configured for all workload identity federation providers):
```bash
# Generate an AWS configuration file with configurable token lifetime.
gcloud iam workload-identity-pools create-cred-config \
projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$AWS_PROVIDER_ID \
--service-account $SERVICE_ACCOUNT_EMAIL \
--aws \
--output-file /path/to/generated/config.json \
--service-account-token-lifetime-seconds $TOKEN_LIFETIME
```
Where the following variables need to be substituted:
- `$PROJECT_NUMBER`: The Google Cloud project number.
- `$POOL_ID`: The workload identity pool ID.
- `$AWS_PROVIDER_ID`: The AWS provider ID.
- `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate.
- `$TOKEN_LIFETIME`: The desired lifetime duration of the service account access token in seconds.
The `service-account-token-lifetime-seconds` flag is optional. If not provided, this defaults to one hour.
The minimum allowed value is 600 (10 minutes) and the maximum allowed value is 43200 (12 hours).
If a lifetime greater than one hour is required, the service account must be added as an allowed value in an Organization Policy that enforces the `constraints/iam.allowServiceAccountCredentialLifetimeExtension` constraint.
Note that configuring a short lifetime (e.g. 10 minutes) will result in the library initiating the entire token exchange flow every 10 minutes, which will call the 3rd party token provider even if the 3rd party token is not expired.
### Workforce Identity Federation
[Workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation) lets you use an
external identity provider (IdP) to authenticate and authorize a workforce—a group of users, such as employees,
partners, and contractors—using IAM, so that the users can access Google Cloud services. Workforce identity federation
extends Google Cloud's identity capabilities to support syncless, attribute-based single sign on.
With workforce identity federation, your workforce can access Google Cloud resources using an external
identity provider (IdP) that supports OpenID Connect (OIDC) or SAML 2.0 such as Azure Active Directory (Azure AD),
Active Directory Federation Services (AD FS), Okta, and others.
#### Accessing resources using an OIDC or SAML 2.0 identity provider
In order to access Google Cloud resources from an identity provider that supports [OpenID Connect (OIDC)](https://openid.net/connect/),
the following requirements are needed:
- A workforce identity pool needs to be created.
- An OIDC or SAML 2.0 identity provider needs to be added in the workforce pool.
Follow the detailed [instructions](https://cloud.google.com/iam/docs/configuring-workforce-identity-federation) on how
to configure workforce identity federation.
After configuring an OIDC or SAML 2.0 provider, a credential configuration
file needs to be generated. The generated credential configuration file contains non-sensitive metadata to instruct the
library on how to retrieve external subject tokens and exchange them for GCP access tokens.
The configuration file can be generated by using the [gcloud CLI](https://cloud.google.com/sdk/).
The Auth library can retrieve external subject tokens from a local file location
(file-sourced credentials), from a local server (URL-sourced credentials) or by calling an executable
(executable-sourced credentials).
**File-sourced credentials**
For file-sourced credentials, a background process needs to be continuously refreshing the file
location with a new subject token prior to expiration. For tokens with one hour lifetimes, the token
needs to be updated in the file every hour. The token can be stored directly as plain text or in
JSON format.
To generate a file-sourced OIDC configuration, run the following command:
```bash
# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \
--subject-token-type=urn:ietf:params:oauth:token-type:id_token \
--credential-source-file=$PATH_TO_OIDC_ID_TOKEN \
--workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \
# Optional arguments for file types. Default is "text":
# --credential-source-type "json" \
# Optional argument for the field that contains the OIDC credential.
# This is required for json.
# --credential-source-field-name "id_token" \
--output-file=/path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$WORKFORCE_POOL_ID`: The workforce pool ID.
- `$PROVIDER_ID`: The provider ID.
- `$PATH_TO_OIDC_ID_TOKEN`: The file path used to retrieve the OIDC token.
- `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).
To generate a file-sourced SAML configuration, run the following command:
```bash
# Generate a SAML configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \
--credential-source-file=$PATH_TO_SAML_ASSERTION \
--subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
--workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \
--output-file=/path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$WORKFORCE_POOL_ID`: The workforce pool ID.
- `$PROVIDER_ID`: The provider ID.
- `$PATH_TO_SAML_ASSERTION`: The file path used to retrieve the base64-encoded SAML assertion.
- `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).
These commands generate the configuration file in the specified output file.
**URL-sourced credentials**
For URL-sourced credentials, a local server needs to host a GET endpoint to return the OIDC token.
The response can be in plain text or JSON. Additional required request headers can also be
specified.
To generate a URL-sourced OIDC workforce identity configuration, run the following command:
```bash
# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \
--subject-token-type=urn:ietf:params:oauth:token-type:id_token \
--credential-source-url=$URL_TO_RETURN_OIDC_ID_TOKEN \
--credential-source-headers $HEADER_KEY=$HEADER_VALUE \
--workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \
--output-file=/path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$WORKFORCE_POOL_ID`: The workforce pool ID.
- `$PROVIDER_ID`: The provider ID.
- `$URL_TO_RETURN_OIDC_ID_TOKEN`: The URL of the local server endpoint.
- `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to
`$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`.
- `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).
To generate a URL-sourced SAML configuration, run the following command:
```bash
# Generate a SAML configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \
--subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
--credential-source-url=$URL_TO_GET_SAML_ASSERTION \
--credential-source-headers $HEADER_KEY=$HEADER_VALUE \
--workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \
--output-file=/path/to/generated/config.json
```
These commands generate the configuration file in the specified output file.
Where the following variables need to be substituted:
- `$WORKFORCE_POOL_ID`: The workforce pool ID.
- `$PROVIDER_ID`: The provider ID.
- `$URL_TO_GET_SAML_ASSERTION`: The URL of the local server endpoint.
- `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to
`$URL_TO_GET_SAML_ASSERTION`, e.g. `Metadata-Flavor=Google`.
- `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).
#### Using external account authorized user workforce credentials
[External account authorized user credentials](https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#browser-based-sign-in) allow you to sign in with a web browser to an external identity provider account via the
gcloud CLI and create a configuration for the auth library to use.
To generate an external account authorized user workforce identity configuration, run the following command:
```bash
gcloud auth application-default login --login-config=$LOGIN_CONFIG
```
Where the following variable needs to be substituted:
- `$LOGIN_CONFIG`: The login config file generated with the cloud console or
[gcloud iam workforce-pools create-login-config](https://cloud.google.com/sdk/gcloud/reference/iam/workforce-pools/create-login-config)
This will open a browser flow for you to sign in via the configured third party identity provider
and then will store the external account authorized user configuration at the well known ADC location.
The auth library will then use the provided refresh token from the configuration to generate and refresh
an access token to call Google Cloud services.
Note that the default lifetime of the refresh token is one hour, after which a new configuration will need to be generated from the gcloud CLI.
The lifetime can be modified by changing the [session duration of the workforce pool](https://cloud.google.com/iam/docs/reference/rest/v1/locations.workforcePools), and can be set as high as 12 hours.
#### Using Executable-sourced workforce credentials with OIDC and SAML
**Executable-sourced credentials**
For executable-sourced credentials, a local executable is used to retrieve the 3rd party token.
The executable must handle providing a valid, unexpired OIDC ID token or SAML assertion in JSON format
to stdout.
To use executable-sourced credentials, the `GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES`
environment variable must be set to `1`.
To generate an executable-sourced workforce identity configuration, run the following command:
```bash
# Generate a configuration file for executable-sourced credentials.
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \
--subject-token-type=$SUBJECT_TOKEN_TYPE \
# The absolute path for the program, including arguments.
# e.g. --executable-command="/path/to/command --foo=bar"
--executable-command=$EXECUTABLE_COMMAND \
# Optional argument for the executable timeout. Defaults to 30s.
# --executable-timeout-millis=$EXECUTABLE_TIMEOUT \
# Optional argument for the absolute path to the executable output file.
# See below on how this argument impacts the library behaviour.
# --executable-output-file=$EXECUTABLE_OUTPUT_FILE \
--workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \
--output-file /path/to/generated/config.json
```
Where the following variables need to be substituted:
- `$WORKFORCE_POOL_ID`: The workforce pool ID.
- `$PROVIDER_ID`: The provider ID.
- `$SUBJECT_TOKEN_TYPE`: The subject token type.
- `$EXECUTABLE_COMMAND`: The full command to run, including arguments. Must be an absolute path to the program.
- `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).
The `--executable-timeout-millis` flag is optional. This is the duration for which
the auth library will wait for the executable to finish, in milliseconds.
Defaults to 30 seconds when not provided. The maximum allowed value is 2 minutes.
The minimum is 5 seconds.
The `--executable-output-file` flag is optional. If provided, the file path must
point to the 3rd party credential response generated by the executable. This is useful
for caching the credentials. By specifying this path, the Auth libraries will first
check for its existence before running the executable. By caching the executable JSON
response to this file, it improves performance as it avoids the need to run the executable
until the cached credentials in the output file are expired. The executable must
handle writing to this file - the auth libraries will only attempt to read from
this location. The format of contents in the file should match the JSON format
expected by the executable shown below.
To retrieve the 3rd party token, the library will call the executable
using the command specified. The executable's output must adhere to the response format
specified below. It must output the response to stdout.
Refer to the [using executable-sourced credentials with Workload Identity Federation](#using-executable-sourced-credentials-with-oidc-and-saml)
above for the executable response specification.
#### Using a custom supplier for workforce credentials with OIDC and SAML
A custom implementation of IdentityPoolSubjectTokenSupplier can be used while building IdentityPoolCredentials
to supply a subject token which can be exchanged for a GCP access token. The supplier must return a valid,
unexpired subject token when called by the GCP credential.
IdentityPoolCredentials do not cache the returned token, so caching logic should be
implemented in the token supplier to prevent multiple requests for the same subject token.
```java
import java.io.IOException;
public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {
@Override
public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
// Any call to supplier will pass a context object with the requested
// audience and subject token type.
string audience = context.getAudience();
string tokenType = context.getSubjectTokenType();
try {
// Return a valid, unexpired token for the requested audience and token type.
// Note that the IdentityPoolCredential does not cache the subject token so
// any caching logic needs to be implemented in the token supplier.
return retrieveToken(audience, tokenType);
} catch (Exception e) {
// If token is unavailable, throw IOException.
throw new IOException(e);
}
}
private String retrieveToken(string tokenType, string audience) {
// Retrieve a subject token of the requested type for the requested audience.
}
}
```
```java
CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
IdentityPoolCredentials.newBuilder()
.setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
.setAudience(...) // Sets the GCP audience.
.setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
.setWorkforcePoolUserProject(...) // Sets the workforce pool user project.
.build();
```
Where the audience is:
```//iam.googleapis.com/locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID```
Where the following variables need to be substituted:
- `$WORKFORCE_POOL_ID`: The workforce pool ID.
- `$PROVIDER_ID`: The provider ID.
and the workforce pool user project is the project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).
The values for audience, service account impersonation URL, and any other builder field can also be found by
generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#use_configuration_files_for_sign-in).
##### Security considerations
The following security practices are highly recommended:
* Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script.
* The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion.
Given the complexity of using executable-sourced credentials, it is recommended to use
the existing supported mechanisms (file-sourced/URL-sourced) for providing 3rd party
credentials unless they do not meet your specific requirements.
You can now [use the Auth library](#using-external-identities) to call Google Cloud
resources from an OIDC or SAML provider.
### Using External Identities
External identities can be used with `Application Default Credentials`. In order to use external identities with
Application Default Credentials, you need to generate the JSON credentials configuration file for your external identity
as described above. Once generated, store the path to this file in the`GOOGLE_APPLICATION_CREDENTIALS` environment variable.
```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json
```
The library can now choose the right type of client and initialize credentials from the context
provided in the configuration file.
```java
GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();
String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;
HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));
JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);
HttpResponse response = request.execute();
System.out.println(response.parseAsString());
```
You can also explicitly initialize external account clients using the generated configuration file.
```java
ExternalAccountCredentials credentials =
ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
```
##### Security Considerations
Note that this library does not perform any validation on the token_url, token_info_url,
or service_account_impersonation_url fields of the credential configuration.
It is not recommended to use a credential configuration that you did not
generate with the gcloud CLI unless you verify that the URL fields point to a
googleapis.com domain.
### Downscoping with Credential Access Boundaries
[Downscoping with Credential Access Boundaries](https://cloud.google.com/iam/docs/downscoping-short-lived-credentials)
enables the ability to downscope, or restrict, the Identity and Access Management (IAM) permissions
that a short-lived credential can use for Cloud Storage.
The `DownscopedCredentials` class can be used to produce a downscoped access token from a
`CredentialAccessBoundary` and a source credential. The Credential Access Boundary specifies which
resources the newly created credential can access, as well as an upper bound on the permissions that
are available on each resource. Using downscoped credentials ensures tokens in flight always have
the least privileges (Principle of Least Privilege).
The snippet below shows how to initialize a CredentialAccessBoundary with one AccessBoundaryRule
which specifies that the downscoped token will have readonly access to objects starting with
"customer-a" in bucket "bucket-123":
```java
// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression = "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";
CredentialAccessBoundary.AccessBoundaryRule rule =
CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
.setAvailableResource(availableResource)
.addAvailablePermission(availablePermission)
.setAvailabilityCondition(
CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
.build();
// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
CredentialAccessBoundary.newBuilder().addRule(rule).build();
```
The common pattern of usage is to have a token broker with elevated access generate these downscoped
credentials from higher access source credentials and pass the downscoped short-lived access tokens
to a token consumer via some secure authenticated channel for limited access to Google Cloud Storage
resources.
Using the CredentialAccessBoundary created above in the Token Broker:
```java
// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
.createScoped("https://www.googleapis.com/auth/cloud-platform");
// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
DownscopedCredentials.newBuilder()
.setSourceCredential(credentials)
.setCredentialAccessBoundary(credentialAccessBoundary)
.build();