---
README.md | 15 +-
.../auth/oauth2/ExecutableResponse.java | 15 +-
.../auth/oauth2/PluggableAuthCredentials.java | 9 +-
.../auth/oauth2/PluggableAuthHandler.java | 12 +
.../auth/oauth2/ExecutableResponseTest.java | 56 +++--
.../auth/oauth2/PluggableAuthHandlerTest.java | 212 ++++++++++++++++++
6 files changed, 281 insertions(+), 38 deletions(-)
diff --git a/README.md b/README.md
index de8018ac4..8882f7a74 100644
--- a/README.md
+++ b/README.md
@@ -421,11 +421,15 @@ A sample executable error response:
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`: The status of the response. When true, the response must contain the 3rd party token,
- token type, and expiration. 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.
+ * `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.
@@ -435,8 +439,9 @@ Response format fields summary:
* `message`: The error message.
All response types must include both the `version` and `success` fields.
- * Successful responses must include the `token_type`, `expiration_time`, and one of
- `id_token` or `saml_response`.
+ * 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:
diff --git a/oauth2_http/java/com/google/auth/oauth2/ExecutableResponse.java b/oauth2_http/java/com/google/auth/oauth2/ExecutableResponse.java
index 5559b5442..278b71047 100644
--- a/oauth2_http/java/com/google/auth/oauth2/ExecutableResponse.java
+++ b/oauth2_http/java/com/google/auth/oauth2/ExecutableResponse.java
@@ -75,14 +75,11 @@ class ExecutableResponse {
"The executable response is missing the `token_type` field.");
}
- if (!json.containsKey("expiration_time")) {
- throw new PluggableAuthException(
- "INVALID_EXECUTABLE_RESPONSE",
- "The executable response is missing the `expiration_time` field.");
- }
-
this.tokenType = (String) json.get("token_type");
- this.expirationTime = parseLongField(json.get("expiration_time"));
+
+ if (json.containsKey("expiration_time")) {
+ this.expirationTime = parseLongField(json.get("expiration_time"));
+ }
if (SAML_SUBJECT_TOKEN_TYPE.equals(tokenType)) {
this.subjectToken = (String) json.get("saml_response");
@@ -132,9 +129,9 @@ boolean isSuccessful() {
return this.success;
}
- /** Returns true if the subject token is expired or not present, false otherwise. */
+ /** Returns true if the subject token is expired, false otherwise. */
boolean isExpired() {
- return this.expirationTime == null || this.expirationTime <= Instant.now().getEpochSecond();
+ return this.expirationTime != null && this.expirationTime <= Instant.now().getEpochSecond();
}
/** Returns whether the execution was successful and returned an unexpired token. */
diff --git a/oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java b/oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java
index e3506c080..7fba136a4 100644
--- a/oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java
+++ b/oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java
@@ -54,9 +54,9 @@
* Both OIDC and SAML are supported. The executable must adhere to a specific response format
* defined below.
*
- *
The executable should print out the 3rd party token to STDOUT in JSON format. This is not
- * required when an output_file is specified in the credential source, with the expectation being
- * that the output file will contain the JSON response instead.
+ *
The executable must print out the 3rd party token to STDOUT in JSON format. When an
+ * output_file is specified in the credential configuration, the executable must also handle writing
+ * the JSON response to this file.
*
*
* OIDC response sample:
@@ -85,6 +85,9 @@
* "message": "Error message."
* }
*
+ * The `expiration_time` field in the JSON response is only required for successful
+ * responses when an output file was specified in the credential configuration.
+ *
* The auth libraries will populate certain environment variables that will be accessible by the
* executable, such as: GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE, GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE,
* GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE, GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL, and
diff --git a/oauth2_http/java/com/google/auth/oauth2/PluggableAuthHandler.java b/oauth2_http/java/com/google/auth/oauth2/PluggableAuthHandler.java
index 24b0978cd..6d62d6911 100644
--- a/oauth2_http/java/com/google/auth/oauth2/PluggableAuthHandler.java
+++ b/oauth2_http/java/com/google/auth/oauth2/PluggableAuthHandler.java
@@ -112,6 +112,18 @@ public String retrieveTokenFromExecutable(ExecutableOptions options) throws IOEx
executableResponse = getExecutableResponse(options);
}
+ // If an output file is specified, successful responses must contain the `expiration_time`
+ // field.
+ if (options.getOutputFilePath() != null
+ && !options.getOutputFilePath().isEmpty()
+ && executableResponse.isSuccessful()
+ && executableResponse.getExpirationTime() == null) {
+ throw new PluggableAuthException(
+ "INVALID_EXECUTABLE_RESPONSE",
+ "The executable response must contain the `expiration_time` field for successful responses when an "
+ + "output_file has been specified in the configuration.");
+ }
+
// The executable response includes a version. Validate that the version is compatible
// with the library.
if (executableResponse.getVersion() > EXECUTABLE_SUPPORTED_MAX_VERSION) {
diff --git a/oauth2_http/javatests/com/google/auth/oauth2/ExecutableResponseTest.java b/oauth2_http/javatests/com/google/auth/oauth2/ExecutableResponseTest.java
index b6f85684a..7c8fec60d 100644
--- a/oauth2_http/javatests/com/google/auth/oauth2/ExecutableResponseTest.java
+++ b/oauth2_http/javatests/com/google/auth/oauth2/ExecutableResponseTest.java
@@ -60,12 +60,27 @@ void constructor_successOidcResponse() throws IOException {
assertTrue(response.isSuccessful());
assertTrue(response.isValid());
- assertEquals(1, response.getVersion());
+ assertEquals(EXECUTABLE_SUPPORTED_MAX_VERSION, response.getVersion());
assertEquals(TOKEN_TYPE_OIDC, response.getTokenType());
assertEquals(ID_TOKEN, response.getSubjectToken());
assertEquals(
Instant.now().getEpochSecond() + EXPIRATION_DURATION, response.getExpirationTime());
- assertEquals(1, response.getVersion());
+ }
+
+ @Test
+ void constructor_successOidcResponseMissingExpirationTimeField_notExpired() throws IOException {
+ GenericJson jsonResponse = buildOidcResponse();
+ jsonResponse.remove("expiration_time");
+
+ ExecutableResponse response = new ExecutableResponse(jsonResponse);
+
+ assertTrue(response.isSuccessful());
+ assertTrue(response.isValid());
+ assertFalse(response.isExpired());
+ assertEquals(EXECUTABLE_SUPPORTED_MAX_VERSION, response.getVersion());
+ assertEquals(TOKEN_TYPE_OIDC, response.getTokenType());
+ assertEquals(ID_TOKEN, response.getSubjectToken());
+ assertNull(response.getExpirationTime());
}
@Test
@@ -81,17 +96,33 @@ void constructor_successSamlResponse() throws IOException {
Instant.now().getEpochSecond() + EXPIRATION_DURATION, response.getExpirationTime());
}
+ @Test
+ void constructor_successSamlResponseMissingExpirationTimeField_notExpired() throws IOException {
+ GenericJson jsonResponse = buildSamlResponse();
+ jsonResponse.remove("expiration_time");
+
+ ExecutableResponse response = new ExecutableResponse(jsonResponse);
+
+ assertTrue(response.isSuccessful());
+ assertTrue(response.isValid());
+ assertFalse(response.isExpired());
+ assertEquals(EXECUTABLE_SUPPORTED_MAX_VERSION, response.getVersion());
+ assertEquals(TOKEN_TYPE_SAML, response.getTokenType());
+ assertEquals(SAML_RESPONSE, response.getSubjectToken());
+ assertNull(response.getExpirationTime());
+ }
+
@Test
void constructor_validErrorResponse() throws IOException {
ExecutableResponse response = new ExecutableResponse(buildErrorResponse());
assertFalse(response.isSuccessful());
assertFalse(response.isValid());
- assertTrue(response.isExpired());
+ assertFalse(response.isExpired());
assertNull(response.getSubjectToken());
assertNull(response.getTokenType());
assertNull(response.getExpirationTime());
- assertEquals(1, response.getVersion());
+ assertEquals(EXECUTABLE_SUPPORTED_MAX_VERSION, response.getVersion());
assertEquals("401", response.getErrorCode());
assertEquals("Caller not authorized.", response.getErrorMessage());
}
@@ -189,23 +220,6 @@ void constructor_successResponseMissingTokenTypeField_throws() {
exception.getMessage());
}
- @Test
- void constructor_successResponseMissingExpirationTimeField_throws() {
- GenericJson jsonResponse = buildOidcResponse();
- jsonResponse.remove("expiration_time");
-
- PluggableAuthException exception =
- assertThrows(
- PluggableAuthException.class,
- () -> new ExecutableResponse(jsonResponse),
- "Exception should be thrown.");
-
- assertEquals(
- "Error code INVALID_EXECUTABLE_RESPONSE: The executable response is missing the "
- + "`expiration_time` field.",
- exception.getMessage());
- }
-
@Test
void constructor_samlResponseMissingSubjectToken_throws() {
GenericJson jsonResponse = buildSamlResponse();
diff --git a/oauth2_http/javatests/com/google/auth/oauth2/PluggableAuthHandlerTest.java b/oauth2_http/javatests/com/google/auth/oauth2/PluggableAuthHandlerTest.java
index 4e630d49c..d751c403f 100644
--- a/oauth2_http/javatests/com/google/auth/oauth2/PluggableAuthHandlerTest.java
+++ b/oauth2_http/javatests/com/google/auth/oauth2/PluggableAuthHandlerTest.java
@@ -51,7 +51,9 @@
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
+import java.util.Arrays;
import java.util.HashMap;
+import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;
import javax.annotation.Nullable;
@@ -218,6 +220,216 @@ void retrieveTokenFromExecutable_errorResponse_throws() throws InterruptedExcept
assertEquals("Caller not authorized.", e.getErrorDescription());
}
+ @Test
+ void retrieveTokenFromExecutable_successResponseWithoutExpirationTimeField()
+ throws InterruptedException, IOException {
+ TestEnvironmentProvider environmentProvider = new TestEnvironmentProvider();
+ environmentProvider.setEnv("GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES", "1");
+
+ // Expected environment mappings.
+ HashMap expectedMap = new HashMap<>();
+ expectedMap.putAll(DEFAULT_OPTIONS.getEnvironmentMap());
+
+ Map currentEnv = new HashMap<>();
+
+ // Mock executable handling.
+ Process mockProcess = Mockito.mock(Process.class);
+ when(mockProcess.waitFor(anyLong(), any(TimeUnit.class))).thenReturn(true);
+ when(mockProcess.exitValue()).thenReturn(EXIT_CODE_SUCCESS);
+
+ // Remove expiration_time from the executable responses.
+ GenericJson oidcResponse = buildOidcResponse();
+ oidcResponse.remove("expiration_time");
+
+ GenericJson samlResponse = buildSamlResponse();
+ samlResponse.remove("expiration_time");
+
+ List responses = Arrays.asList(oidcResponse, samlResponse);
+ for (int i = 0; i < responses.size(); i++) {
+ when(mockProcess.getInputStream())
+ .thenReturn(
+ new ByteArrayInputStream(
+ responses.get(i).toString().getBytes(StandardCharsets.UTF_8)));
+
+ InternalProcessBuilder processBuilder =
+ buildInternalProcessBuilder(
+ currentEnv, mockProcess, DEFAULT_OPTIONS.getExecutableCommand());
+
+ PluggableAuthHandler handler = new PluggableAuthHandler(environmentProvider, processBuilder);
+
+ // Call retrieveTokenFromExecutable().
+ String token = handler.retrieveTokenFromExecutable(DEFAULT_OPTIONS);
+
+ verify(mockProcess, times(i + 1)).destroy();
+ verify(mockProcess, times(i + 1))
+ .waitFor(
+ eq(Long.valueOf(DEFAULT_OPTIONS.getExecutableTimeoutMs())),
+ eq(TimeUnit.MILLISECONDS));
+
+ if (responses.get(i).equals(oidcResponse)) {
+ assertEquals(ID_TOKEN, token);
+ } else {
+ assertEquals(SAML_RESPONSE, token);
+ }
+
+ // Current env map should have the mappings from options.
+ assertEquals(2, currentEnv.size());
+ assertEquals(expectedMap, currentEnv);
+ }
+ }
+
+ @Test
+ void
+ retrieveTokenFromExecutable_successResponseWithoutExpirationTimeFieldWithOutputFileSpecified_throws()
+ throws InterruptedException, IOException {
+ TestEnvironmentProvider environmentProvider = new TestEnvironmentProvider();
+ environmentProvider.setEnv("GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES", "1");
+
+ // Options with output file specified.
+ ExecutableOptions options =
+ new ExecutableOptions() {
+ @Override
+ public String getExecutableCommand() {
+ return "/path/to/executable";
+ }
+
+ @Override
+ public Map getEnvironmentMap() {
+ return ImmutableMap.of();
+ }
+
+ @Override
+ public int getExecutableTimeoutMs() {
+ return 30000;
+ }
+
+ @Override
+ public String getOutputFilePath() {
+ return "/path/to/output/file";
+ }
+ };
+
+ // Mock executable handling.
+ Process mockProcess = Mockito.mock(Process.class);
+ when(mockProcess.waitFor(anyLong(), any(TimeUnit.class))).thenReturn(true);
+ when(mockProcess.exitValue()).thenReturn(EXIT_CODE_SUCCESS);
+
+ // Remove expiration_time from the executable responses.
+ GenericJson oidcResponse = buildOidcResponse();
+ oidcResponse.remove("expiration_time");
+
+ GenericJson samlResponse = buildSamlResponse();
+ samlResponse.remove("expiration_time");
+
+ List responses = Arrays.asList(oidcResponse, samlResponse);
+ for (int i = 0; i < responses.size(); i++) {
+ when(mockProcess.getInputStream())
+ .thenReturn(
+ new ByteArrayInputStream(
+ responses.get(i).toString().getBytes(StandardCharsets.UTF_8)));
+
+ InternalProcessBuilder processBuilder =
+ buildInternalProcessBuilder(new HashMap<>(), mockProcess, options.getExecutableCommand());
+
+ PluggableAuthHandler handler = new PluggableAuthHandler(environmentProvider, processBuilder);
+
+ // Call retrieveTokenFromExecutable() should throw an exception as the STDOUT response
+ // is missing
+ // the `expiration_time` field and an output file was specified in the configuration.
+ PluggableAuthException exception =
+ assertThrows(
+ PluggableAuthException.class,
+ () -> handler.retrieveTokenFromExecutable(options),
+ "Exception should be thrown.");
+
+ assertEquals(
+ "Error code INVALID_EXECUTABLE_RESPONSE: The executable response must contain the "
+ + "`expiration_time` field for successful responses when an output_file has been specified in the"
+ + " configuration.",
+ exception.getMessage());
+
+ verify(mockProcess, times(i + 1)).destroy();
+ verify(mockProcess, times(i + 1))
+ .waitFor(eq(Long.valueOf(options.getExecutableTimeoutMs())), eq(TimeUnit.MILLISECONDS));
+ }
+ }
+
+ @Test
+ void retrieveTokenFromExecutable_successResponseInOutputFileMissingExpirationTimeField_throws()
+ throws InterruptedException, IOException {
+ TestEnvironmentProvider environmentProvider = new TestEnvironmentProvider();
+ environmentProvider.setEnv("GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES", "1");
+
+ // Build output_file.
+ File file = File.createTempFile("output_file", /* suffix= */ null, /* directory= */ null);
+ file.deleteOnExit();
+
+ // Options with output file specified.
+ ExecutableOptions options =
+ new ExecutableOptions() {
+ @Override
+ public String getExecutableCommand() {
+ return "/path/to/executable";
+ }
+
+ @Override
+ public Map getEnvironmentMap() {
+ return ImmutableMap.of();
+ }
+
+ @Override
+ public int getExecutableTimeoutMs() {
+ return 30000;
+ }
+
+ @Override
+ public String getOutputFilePath() {
+ return file.getAbsolutePath();
+ }
+ };
+
+ // Mock executable handling that does nothing since we are using the output file.
+ Process mockProcess = Mockito.mock(Process.class);
+ InternalProcessBuilder processBuilder =
+ buildInternalProcessBuilder(new HashMap<>(), mockProcess, options.getExecutableCommand());
+
+ // Remove expiration_time from the executable responses.
+ GenericJson oidcResponse = buildOidcResponse();
+ oidcResponse.remove("expiration_time");
+
+ GenericJson samlResponse = buildSamlResponse();
+ samlResponse.remove("expiration_time");
+
+ List responses = Arrays.asList(oidcResponse, samlResponse);
+ for (GenericJson json : responses) {
+ OAuth2Utils.writeInputStreamToFile(
+ new ByteArrayInputStream(json.toString().getBytes(StandardCharsets.UTF_8)),
+ file.getAbsolutePath());
+
+ PluggableAuthHandler handler = new PluggableAuthHandler(environmentProvider, processBuilder);
+
+ // Call retrieveTokenFromExecutable() which should throw an exception as the output file
+ // response is missing
+ // the `expiration_time` field.
+ PluggableAuthException exception =
+ assertThrows(
+ PluggableAuthException.class,
+ () -> handler.retrieveTokenFromExecutable(options),
+ "Exception should be thrown.");
+
+ assertEquals(
+ "Error code INVALID_EXECUTABLE_RESPONSE: The executable response must contain the "
+ + "`expiration_time` field for successful responses when an output_file has been specified in the"
+ + " configuration.",
+ exception.getMessage());
+
+ // Validate executable not invoked.
+ verify(mockProcess, times(0)).destroyForcibly();
+ verify(mockProcess, times(0))
+ .waitFor(eq(Long.valueOf(options.getExecutableTimeoutMs())), eq(TimeUnit.MILLISECONDS));
+ }
+ }
+
@Test
void retrieveTokenFromExecutable_withOutputFile_usesCachedResponse()
throws IOException, InterruptedException {
From 7f2c535ab7c842a672d6761f4cd80df88e1a37ed Mon Sep 17 00:00:00 2001
From: Leo <39062083+lsirac@users.noreply.github.com>
Date: Fri, 5 Aug 2022 11:10:58 -0700
Subject: [PATCH 8/9] feat: workforce identity federation for pluggable auth
(#959)
* feat: add workforce support to ADC with pluggable auth
* feat: document workforce identity federation
---
README.md | 212 +++++++++++++++++-
.../oauth2/ExternalAccountCredentials.java | 1 +
.../ExternalAccountCredentialsTest.java | 71 ++++--
3 files changed, 262 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index 8882f7a74..762929749 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,9 @@ credentials as well as utility methods to create them and to get Application Def
* [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)
+ * [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 Executable-sourced credentials](#using-executable-sourced-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)
@@ -446,6 +449,7 @@ All response types must include both the `version` and `success` 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.
@@ -453,7 +457,7 @@ These environment variables can be used by the executable to avoid hard-coding t
##### 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.
+ * 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
@@ -463,13 +467,207 @@ 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
+### Workforce Identity Federation
-External identities (AWS, Azure, and OIDC-based providers) 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.
+[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 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.
+
+##### 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
diff --git a/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java b/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java
index 85af46335..0d6f3419b 100644
--- a/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java
+++ b/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java
@@ -401,6 +401,7 @@ static ExternalAccountCredentials fromJson(
.setQuotaProjectId(quotaProjectId)
.setClientId(clientId)
.setClientSecret(clientSecret)
+ .setWorkforcePoolUserProject(userProject)
.build();
}
return IdentityPoolCredentials.newBuilder()
diff --git a/oauth2_http/javatests/com/google/auth/oauth2/ExternalAccountCredentialsTest.java b/oauth2_http/javatests/com/google/auth/oauth2/ExternalAccountCredentialsTest.java
index 1b2b53a1c..75b88dcfa 100644
--- a/oauth2_http/javatests/com/google/auth/oauth2/ExternalAccountCredentialsTest.java
+++ b/oauth2_http/javatests/com/google/auth/oauth2/ExternalAccountCredentialsTest.java
@@ -196,8 +196,7 @@ void fromJson_identityPoolCredentialsWorkforce() {
assertEquals("subjectTokenType", credential.getSubjectTokenType());
assertEquals(STS_URL, credential.getTokenUrl());
assertEquals("tokenInfoUrl", credential.getTokenInfoUrl());
- assertEquals(
- "userProject", ((IdentityPoolCredentials) credential).getWorkforcePoolUserProject());
+ assertEquals("userProject", credential.getWorkforcePoolUserProject());
assertNotNull(credential.getCredentialSource());
}
@@ -235,6 +234,30 @@ void fromJson_pluggableAuthCredentials() {
assertNull(source.getOutputFilePath());
}
+ @Test
+ void fromJson_pluggableAuthCredentialsWorkforce() {
+ ExternalAccountCredentials credential =
+ ExternalAccountCredentials.fromJson(
+ buildJsonPluggableAuthWorkforceCredential(), OAuth2Utils.HTTP_TRANSPORT_FACTORY);
+
+ assertTrue(credential instanceof PluggableAuthCredentials);
+ assertEquals(
+ "//iam.googleapis.com/locations/global/workforcePools/pool/providers/provider",
+ credential.getAudience());
+ assertEquals("subjectTokenType", credential.getSubjectTokenType());
+ assertEquals(STS_URL, credential.getTokenUrl());
+ assertEquals("tokenInfoUrl", credential.getTokenInfoUrl());
+ assertEquals("userProject", credential.getWorkforcePoolUserProject());
+
+ assertNotNull(credential.getCredentialSource());
+
+ PluggableAuthCredentialSource source =
+ (PluggableAuthCredentialSource) credential.getCredentialSource();
+ assertEquals("command", source.getCommand());
+ assertEquals(30000, source.getTimeoutMs()); // Default timeout is 30s.
+ assertNull(source.getOutputFilePath());
+ }
+
@Test
void fromJson_pluggableAuthCredentials_allExecutableOptionsSet() {
GenericJson json = buildJsonPluggableAuthCredential();
@@ -502,25 +525,35 @@ void exchangeExternalCredentialForAccessToken_withInternalOptions() throws IOExc
@Test
void exchangeExternalCredentialForAccessToken_workforceCred_expectUserProjectPassedToSts()
throws IOException {
- ExternalAccountCredentials credential =
+ ExternalAccountCredentials identityPoolCredential =
ExternalAccountCredentials.fromJson(
buildJsonIdentityPoolWorkforceCredential(), transportFactory);
- StsTokenExchangeRequest stsTokenExchangeRequest =
- StsTokenExchangeRequest.newBuilder("credential", "subjectTokenType").build();
+ ExternalAccountCredentials pluggableAuthCredential =
+ ExternalAccountCredentials.fromJson(
+ buildJsonPluggableAuthWorkforceCredential(), transportFactory);
- AccessToken accessToken =
- credential.exchangeExternalCredentialForAccessToken(stsTokenExchangeRequest);
+ List credentials =
+ Arrays.asList(identityPoolCredential, pluggableAuthCredential);
- assertEquals(transportFactory.transport.getAccessToken(), accessToken.getTokenValue());
+ for (int i = 0; i < credentials.size(); i++) {
+ StsTokenExchangeRequest stsTokenExchangeRequest =
+ StsTokenExchangeRequest.newBuilder("credential", "subjectTokenType").build();
- // Validate internal options set.
- Map query =
- TestUtils.parseQuery(transportFactory.transport.getLastRequest().getContentAsString());
- GenericJson internalOptions = new GenericJson();
- internalOptions.setFactory(OAuth2Utils.JSON_FACTORY);
- internalOptions.put("userProject", "userProject");
- assertEquals(internalOptions.toString(), query.get("options"));
+ AccessToken accessToken =
+ credentials.get(i).exchangeExternalCredentialForAccessToken(stsTokenExchangeRequest);
+
+ assertEquals(transportFactory.transport.getAccessToken(), accessToken.getTokenValue());
+
+ // Validate internal options set.
+ Map query =
+ TestUtils.parseQuery(transportFactory.transport.getLastRequest().getContentAsString());
+ GenericJson internalOptions = new GenericJson();
+ internalOptions.setFactory(OAuth2Utils.JSON_FACTORY);
+ internalOptions.put("userProject", "userProject");
+ assertEquals(internalOptions.toString(), query.get("options"));
+ assertEquals(i + 1, transportFactory.transport.getRequests().size());
+ }
}
@Test
@@ -813,6 +846,14 @@ private GenericJson buildJsonPluggableAuthCredential() {
return json;
}
+ private GenericJson buildJsonPluggableAuthWorkforceCredential() {
+ GenericJson json = buildJsonPluggableAuthCredential();
+ json.put(
+ "audience", "//iam.googleapis.com/locations/global/workforcePools/pool/providers/provider");
+ json.put("workforce_pool_user_project", "userProject");
+ return json;
+ }
+
static class TestExternalAccountCredentials extends ExternalAccountCredentials {
static class TestCredentialSource extends IdentityPoolCredentials.IdentityPoolCredentialSource {
protected TestCredentialSource(Map credentialSourceMap) {
From 79fffe2877d25f1ec751b257c93c71923f5ba27a Mon Sep 17 00:00:00 2001
From: "release-please[bot]"
<55107282+release-please[bot]@users.noreply.github.com>
Date: Tue, 9 Aug 2022 18:22:12 +0000
Subject: [PATCH 9/9] chore(main): release 1.10.0 (#962)
:robot: I have created a release *beep* *boop*
---
## [1.10.0](https://github.com/googleapis/google-auth-library-java/compare/v1.9.0...v1.10.0) (2022-08-05)
### Features
* workforce identity federation for pluggable auth ([#959](https://github.com/googleapis/google-auth-library-java/issues/959)) ([7f2c535](https://github.com/googleapis/google-auth-library-java/commit/7f2c535ab7c842a672d6761f4cd80df88e1a37ed))
### Bug Fixes
* updates executable response spec for executable-sourced credentials ([#955](https://github.com/googleapis/google-auth-library-java/issues/955)) ([48ff83d](https://github.com/googleapis/google-auth-library-java/commit/48ff83dc68e29dcae07fdea963cbbe5525f86a89))
### Documentation
* **samples:** added auth samples and tests ([#927](https://github.com/googleapis/google-auth-library-java/issues/927)) ([32c717f](https://github.com/googleapis/google-auth-library-java/commit/32c717fdf1a721f3e7ca3d75f03fcc229923689c))
---
This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
---
CHANGELOG.md | 17 +++++++++++++++++
appengine/pom.xml | 2 +-
bom/pom.xml | 2 +-
credentials/pom.xml | 2 +-
oauth2_http/pom.xml | 2 +-
pom.xml | 2 +-
versions.txt | 12 ++++++------
7 files changed, 28 insertions(+), 11 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 25e44203b..12e9025c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,22 @@
# Changelog
+## [1.10.0](https://github.com/googleapis/google-auth-library-java/compare/v1.9.0...v1.10.0) (2022-08-05)
+
+
+### Features
+
+* workforce identity federation for pluggable auth ([#959](https://github.com/googleapis/google-auth-library-java/issues/959)) ([7f2c535](https://github.com/googleapis/google-auth-library-java/commit/7f2c535ab7c842a672d6761f4cd80df88e1a37ed))
+
+
+### Bug Fixes
+
+* updates executable response spec for executable-sourced credentials ([#955](https://github.com/googleapis/google-auth-library-java/issues/955)) ([48ff83d](https://github.com/googleapis/google-auth-library-java/commit/48ff83dc68e29dcae07fdea963cbbe5525f86a89))
+
+
+### Documentation
+
+* **samples:** added auth samples and tests ([#927](https://github.com/googleapis/google-auth-library-java/issues/927)) ([32c717f](https://github.com/googleapis/google-auth-library-java/commit/32c717fdf1a721f3e7ca3d75f03fcc229923689c))
+
## [1.9.0](https://github.com/googleapis/google-auth-library-java/compare/v1.8.1...v1.9.0) (2022-08-02)
diff --git a/appengine/pom.xml b/appengine/pom.xml
index 6fff828c5..38b1ccf49 100644
--- a/appengine/pom.xml
+++ b/appengine/pom.xml
@@ -5,7 +5,7 @@
com.google.auth
google-auth-library-parent
- 1.9.1-SNAPSHOT
+ 1.10.0
../pom.xml
diff --git a/bom/pom.xml b/bom/pom.xml
index 77d8f99f4..00a8dac17 100644
--- a/bom/pom.xml
+++ b/bom/pom.xml
@@ -3,7 +3,7 @@
4.0.0
com.google.auth
google-auth-library-bom
- 1.9.1-SNAPSHOT
+ 1.10.0
pom
Google Auth Library for Java BOM
diff --git a/credentials/pom.xml b/credentials/pom.xml
index c1d4f46ff..c88dfebdd 100644
--- a/credentials/pom.xml
+++ b/credentials/pom.xml
@@ -4,7 +4,7 @@
com.google.auth
google-auth-library-parent
- 1.9.1-SNAPSHOT
+ 1.10.0
../pom.xml
diff --git a/oauth2_http/pom.xml b/oauth2_http/pom.xml
index 8aadf3e73..a604d4986 100644
--- a/oauth2_http/pom.xml
+++ b/oauth2_http/pom.xml
@@ -5,7 +5,7 @@
com.google.auth
google-auth-library-parent
- 1.9.1-SNAPSHOT
+ 1.10.0
../pom.xml
diff --git a/pom.xml b/pom.xml
index 10171892d..20554ffad 100644
--- a/pom.xml
+++ b/pom.xml
@@ -3,7 +3,7 @@
4.0.0
com.google.auth
google-auth-library-parent
- 1.9.1-SNAPSHOT
+ 1.10.0
pom
Google Auth Library for Java
Client libraries providing authentication and
diff --git a/versions.txt b/versions.txt
index d8f0ea5fd..4ebc557bd 100644
--- a/versions.txt
+++ b/versions.txt
@@ -1,9 +1,9 @@
# Format:
# module:released-version:current-version
-google-auth-library:1.9.0:1.9.1-SNAPSHOT
-google-auth-library-bom:1.9.0:1.9.1-SNAPSHOT
-google-auth-library-parent:1.9.0:1.9.1-SNAPSHOT
-google-auth-library-appengine:1.9.0:1.9.1-SNAPSHOT
-google-auth-library-credentials:1.9.0:1.9.1-SNAPSHOT
-google-auth-library-oauth2-http:1.9.0:1.9.1-SNAPSHOT
+google-auth-library:1.10.0:1.10.0
+google-auth-library-bom:1.10.0:1.10.0
+google-auth-library-parent:1.10.0:1.10.0
+google-auth-library-appengine:1.10.0:1.10.0
+google-auth-library-credentials:1.10.0:1.10.0
+google-auth-library-oauth2-http:1.10.0:1.10.0