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

* 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://github.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://github.com/googleapis/google-http-java-client/blob/HEAD/CHANGELOG.md#&#8203;1415-httpsgithubcomgoogleapisgoogle-http-java-clientcomparev1414v1415-2022-03-21)

[Compare Source](https://github.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.

---

 - [ ] <!-- rebase-check -->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 <[email protected]>

* 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 <[email protected]>
Co-authored-by: Navina Ramesh <[email protected]>
Co-authored-by: Timur Sadykov <[email protected]>
Co-authored-by: Neenu Shaji <[email protected]>
Co-authored-by: Jeff Williams <[email protected]>

* 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 <[email protected]>
Co-authored-by: Navina Ramesh <[email protected]>
Co-authored-by: Timur Sadykov <[email protected]>
Co-authored-by: Neenu Shaji <[email protected]>
Co-authored-by: Jeff Williams <[email protected]>
Co-authored-by: Emily Ball <[email protected]>

Author: 7 people

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