docs: adds docs for supplier based external account credentials

README.md

@@ -472,49 +472,104 @@ 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.
+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
-class TokenSupplier implements IdentityPoolSubjectTokenSupplier {
+import java.io.IOException;
+
+public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {
+
   @Override
-  String getSubjectToken(){
-    // return a valid subject token for the configured identity.
+  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, unexpected 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 cannot be retrieved, 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
-TokenSupplier tokenSupplier = new TokenSupplier();
-  IdentityPoolCredentials identityPoolCredentials =
-      IdentityPoolCredentials.newBuilder()
-          .setSubjectTokenSupplier(tokenSupplier) // Set token supplier.
-          .setAudience(...) // Set GCP audience
-          .setSubjectTokenType(SubjectTokenTypes.JWT) // Set subject token type.
-          .build();
+CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
+IdentityPoolCredentials identityPoolCredentials =
+    IdentityPoolCredentials.newBuilder()
+        .setSubjectTokenSupplier(tokenSupplier) // Set token supplier.
+        .setAudience(...) // Set GCP audience
+        .setSubjectTokenType(SubjectTokenTypes.JWT) // Set subject token type.
+        .build();
 ```
-Where the audience is the url of the [workload pool](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience).
+Where the audience is the URL of the [workload pool](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience).
 
 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.
+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 used while building AWSCredentials to supply
-AWS security credentials which can be exchanged for a GCP access token.
+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 AwsSupplier implements AwsSecurityCredentialsSupplier {
+class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
   @Override
-  AwsSecurityCredentials getAwsSecurityCredentials(){
-    // return valid AwsSecurityCredentials for the configured identity.
+  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 cannot be retrieved, throw IOException.
+      throw new IOException(e);
+    }
   }
 
   @Override
-  String getRegion(){
-    // return the current AWS region, i.e. "us-east-2"
+  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 token cannot be retrieved, 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
-AwsSecurityCredentialsSupplier awsSupplier = new AwsSupplier();
+CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
 AwsCredentials credentials = AwsCredentials.newBuilder()
     .setSubjectTokenType(SubjectTokenTypes.AWS4) // Set subject token type.
     .setAudience(...) // Set GCP audience.
@@ -525,7 +580,7 @@ AwsCredentials credentials = AwsCredentials.newBuilder()
 Where the audience is the url of the [workload pool](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience).
 
 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.
+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.
@@ -761,6 +816,57 @@ 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 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, unexpected 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 cannot be retrieved, 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) // Set token supplier.
+        .setAudience(...) // Set GCP audience
+        .setSubjectTokenType(SubjectTokenTypes.JWT) // Set subject token type.
+        .setWorkforcePoolUserProject(...) // Set workforce pool user project.
+        .build();
+```
+Where the audience is the URL of the [workforce pool](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience).
+
+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.