docs: updates README for Pluggable Auth (googleapis#921)

lsirac · renovate-bot · navina · web-flow · commit 23716b82fb30 · 2022-06-24T15:53:14.000-07:00
* feat: Adds Pluggable Auth support to ADC (googleapis#895) * chore(deps): update dependency com.google.http-client:google-http-client-bom to v1.41.5 (googleapis#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 <details> <summary>googleapis/google-http-java-client</summary> ### [`v1.41.5`](https://togithub.com/googleapis/google-http-java-client/blob/HEAD/CHANGELOG.md#&#8203;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) </details> --- ### 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 googleapis#883 (googleapis#889) * feat: Add ability to provide PrivateKey as Pkcs8 encoded string googleapis#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 <stim@google.com> * chore: fix downstream check (googleapis#898) * fix: update branding in ExternalAccountCredentials (googleapis#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 <bot@renovateapp.com> Co-authored-by: Navina Ramesh <navi.trinity@gmail.com> Co-authored-by: Timur Sadykov <stim@google.com> Co-authored-by: Neenu Shaji <Neenu1995@users.noreply.github.com> Co-authored-by: Jeff Williams <jeffrey.l.williams@gmail.com> * feat: finalizes PluggableAuth implementation (googleapis#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 (googleapis#912) * feat: improves pluggable auth error handling * cleanup * fix: consume input stream immediately for Pluggable Auth (googleapis#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 (googleapis#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 <bot@renovateapp.com> Co-authored-by: Navina Ramesh <navi.trinity@gmail.com> Co-authored-by: Timur Sadykov <stim@google.com> Co-authored-by: Neenu Shaji <Neenu1995@users.noreply.github.com> Co-authored-by: Jeff Williams <jeffrey.l.williams@gmail.com> Co-authored-by: Emily Ball <emilyball@google.com>
diff --git 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
