From 23716b82fb3000f5210bb5604127aad7ef52cb76 Mon Sep 17 00:00:00 2001
From: Leo <39062083+lsirac@users.noreply.github.com>
Date: Fri, 24 Jun 2022 15:53:14 -0700
Subject: [PATCH] docs: updates README for Pluggable Auth (#921)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* feat: Adds Pluggable Auth support to ADC (#895)
* chore(deps): update dependency com.google.http-client:google-http-client-bom to v1.41.5 (#896)
[![WhiteSource Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)
This PR contains the following updates:
| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [com.google.http-client:google-http-client-bom](https://togithub.com/googleapis/google-http-java-client) | `1.41.4` -> `1.41.5` | [![age](https://badges.renovateapi.com/packages/maven/com.google.http-client:google-http-client-bom/1.41.5/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/maven/com.google.http-client:google-http-client-bom/1.41.5/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/maven/com.google.http-client:google-http-client-bom/1.41.5/compatibility-slim/1.41.4)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/maven/com.google.http-client:google-http-client-bom/1.41.5/confidence-slim/1.41.4)](https://docs.renovatebot.com/merge-confidence/) |
---
### Release Notes
googleapis/google-http-java-client
### [`v1.41.5`](https://togithub.com/googleapis/google-http-java-client/blob/HEAD/CHANGELOG.md#1415-httpsgithubcomgoogleapisgoogle-http-java-clientcomparev1414v1415-2022-03-21)
[Compare Source](https://togithub.com/googleapis/google-http-java-client/compare/v1.41.4...v1.41.5)
---
### Configuration
📅 **Schedule**: At any time (no schedule defined).
🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.
â™» **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 **Ignore**: Close this PR and you won't be reminded about this update again.
---
- [ ] If you want to rebase/retry this PR, click this checkbox.
---
This PR has been generated by [WhiteSource Renovate](https://renovate.whitesourcesoftware.com). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/google-auth-library-java).
* feat: Add ability to provide PrivateKey as Pkcs8 encoded string #883 (#889)
* feat: Add ability to provide PrivateKey as Pkcs8 encoded string #883
This change adds a new method `setPrivateKeyString` in `ServiceAccountCredentials.Builder` to accept Pkcs8 encoded string representation of private keys.
Co-authored-by: Timur Sadykov
* chore: fix downstream check (#898)
* fix: update branding in ExternalAccountCredentials (#893)
These changes align the Javadoc comments with the branding that Google uses externally:
+ STS -> Security Token Service
+ GCP -> Google Cloud
+ Remove references to a Google-internal token type
Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/google-auth-library-java/issues/new/choose) before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
- [ ] Ensure the tests and linter pass: Tests are failing, but I don't think that was caused by the changes in this PR
- [ ] Code coverage does not decrease (if any source code was changed): n/a
- [ ] Appropriate docs were updated (if necessary): n/a
* feat: Adds the ExecutableHandler interface for Pluggable Auth
* feat: Adds a Pluggable Auth specific exception
* feat: Adds new PluggableAuthCredentials class that plug into ADC
* feat: Adds unit tests for PluggableAuthCredentials and ExternalAccountCredentials
* Add units tests for GoogleCredentials
* fix: update javadoc/comments
* fix: A concrete ExecutableOptions implementation is not needed
* review: javadoc changes + constants
Co-authored-by: WhiteSource Renovate
Co-authored-by: Navina Ramesh
Co-authored-by: Timur Sadykov
Co-authored-by: Neenu Shaji
Co-authored-by: Jeff Williams
* feat: finalizes PluggableAuth implementation (#906)
* Adds ExecutableResponse class
* Adds unit tests for ExecutableResponse
* Adds 3rd party executable handler
* Adds unit tests for PluggableAuthHandler
* Fix build issues
* don't fail on javadoc errors
* feat: Improve Pluggable Auth error handling (#912)
* feat: improves pluggable auth error handling
* cleanup
* fix: consume input stream immediately for Pluggable Auth (#915)
* feat: improves pluggable auth error handling
* cleanup
* fix: consume input stream immediately so that the spawned process will not hang if the STDOUT buffer is filled.
* fix: fix merge
* fix: review comments
* fix: refactor to keep ImpersonatedCredentials final (#917)
* fix: adds more documentation for InternalProcessBuilder and moves it to the bottom of the file
* fix: keep ImpersonatedCredentials final
* feat: documents pluggable auth in README
* fix: provider
* fix: update table of contents
* fix: update
Co-authored-by: WhiteSource Renovate
Co-authored-by: Navina Ramesh
Co-authored-by: Timur Sadykov
Co-authored-by: Neenu Shaji
Co-authored-by: Jeff Williams
Co-authored-by: Emily Ball
---
README.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 129 insertions(+)
diff --git a/README.md b/README.md
index 9370e67e8..b03d5aeb4 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,10 @@ credentials as well as utility methods to create them and to get Application Def
* [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)
* [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)
@@ -323,6 +327,131 @@ 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.
+
+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.
+ * `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`, `expiration_time`, and one of
+ `id_token` or `saml_response`.
+ * 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_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 External Identities
External identities (AWS, Azure, and OIDC-based providers) can be used with