feat: Custom Credential Supplier Documentation

auth/README.md

@@ -67,6 +67,51 @@ You can then run `DownscopingExample` via:
 
 	mvn exec:java -Dexec.mainClass=com.google.cloud.auth.samples.DownscopingExample
 
+## Custom Credential Suppliers
+
+If you want to use external credentials (like AWS or Okta) that require custom retrieval logic not supported natively by the library, you can provide a custom supplier implementation.
+
+### Authenticate with Okta (Custom Supplier)
+
+This sample demonstrates how to use a custom `IdentityPoolSubjectTokenSupplier` to fetch an OIDC token from Okta using the Client Credentials flow and exchange it for Google Cloud credentials.
+
+1.  **Set required environment variables:**
+    ```bash
+    export OKTA_DOMAIN="https://your-domain.okta.com"
+    export OKTA_CLIENT_ID="your-client-id"
+    export OKTA_CLIENT_SECRET="your-client-secret"
+    export GCP_WORKLOAD_AUDIENCE="//iam.googleapis.com/projects/123456/locations/global/workloadIdentityPools/my-pool/providers/my-provider"
+    export GCS_BUCKET_NAME="your-bucket-name"
+    # Optional:
+    # export GCP_SERVICE_ACCOUNT_IMPERSONATION_URL="..."
+    ```
+
+2.  **Run the sample:**
+    ```bash
+    mvn exec:java -Dexec.mainClass=com.google.cloud.auth.samples.CustomCredentialSupplierOktaWorkload
+    ```
+
+### Authenticate with AWS (Custom Supplier)
+
+This sample demonstrates how to use the **AWS SDK for Java (v2)** as a custom `AwsSecurityCredentialsSupplier` to bridge AWS credentials (from environment, `~/.aws/credentials`, or EKS/ECS metadata) to Google Cloud Workload Identity.
+
+1.  **Set required environment variables:**
+    ```bash
+    # Google Cloud Config
+    export GCP_WORKLOAD_AUDIENCE="//iam.googleapis.com/projects/123456/locations/global/workloadIdentityPools/my-pool/providers/my-aws-provider"
+    export GCS_BUCKET_NAME="your-bucket-name"
+
+    # AWS Credentials (or use ~/.aws/credentials)
+    export AWS_ACCESS_KEY_ID="your-aws-key"
+    export AWS_SECRET_ACCESS_KEY="your-aws-secret"
+    export AWS_REGION="us-east-1"
+    ```
+
+2.  **Run the sample:**
+    ```bash
+    mvn exec:java -Dexec.mainClass=com.google.cloud.auth.samples.CustomCredentialSupplierAwsWorkload
+    ```
+
 ## Tests
 Run all tests:
 ```

auth/pom.xml

@@ -30,7 +30,7 @@ limitations under the License.
   <parent>
     <groupId>com.google.cloud.samples</groupId>
     <artifactId>shared-configuration</artifactId>
-    <version>1.2.0</version>
+    <version>1.2.2</version>
   </parent>
 
   <properties>
@@ -52,6 +52,13 @@ limitations under the License.
         <type>pom</type>
         <scope>import</scope>
       </dependency>
+      <dependency>
+        <groupId>software.amazon.awssdk</groupId>
+        <artifactId>bom</artifactId>
+        <version>2.25.41</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
     </dependencies>
   </dependencyManagement>
 
@@ -82,6 +89,14 @@ limitations under the License.
       <groupId>com.google.cloud</groupId>
       <artifactId>google-cloud-language</artifactId>
     </dependency>
+    <dependency>
+      <groupId>software.amazon.awssdk</groupId>
+      <artifactId>auth</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>software.amazon.awssdk</groupId>
+      <artifactId>regions</artifactId>
+    </dependency>
     <!-- END dependencies -->
     <dependency>
       <groupId>junit</groupId>

auth/src/main/java/com/google/cloud/auth/samples/CustomCredentialSupplierAwsWorkload.java

@@ -0,0 +1,156 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.auth.samples;
+
+// [START auth_custom_credential_supplier_aws]
+import com.google.auth.oauth2.AwsCredentials;
+import com.google.auth.oauth2.AwsSecurityCredentials;
+import com.google.auth.oauth2.AwsSecurityCredentialsSupplier;
+import com.google.auth.oauth2.ExternalAccountSupplierContext;
+import com.google.auth.oauth2.GoogleCredentials;
+import com.google.cloud.storage.Bucket;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+import java.io.IOException;
+import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
+import software.amazon.awssdk.auth.credentials.AwsSessionCredentials;
+import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
+import software.amazon.awssdk.regions.Region;
+import software.amazon.awssdk.regions.providers.DefaultAwsRegionProviderChain;
+
+// [END auth_custom_credential_supplier_aws]
+
+/**
+ * This sample demonstrates how to use a custom AWS security credentials supplier to authenticate to
+ * Google Cloud Storage using AWS Workload Identity Federation.
+ */
+public class CustomCredentialSupplierAwsWorkload {
+
+  public static void main(String[] args) throws IOException {
+    // The audience for the workload identity federation.
+    // Format: //iam.googleapis.com/projects/<project-number>/locations/global/
+    //         workloadIdentityPools/<pool-id>/providers/<provider-id>
+    String gcpWorkloadAudience = System.getenv("GCP_WORKLOAD_AUDIENCE");
+
+    // The bucket to fetch data from.
+    String gcsBucketName = System.getenv("GCS_BUCKET_NAME");
+
+    // (Optional) The service account impersonation URL.
+    String saImpersonationUrl = System.getenv("GCP_SERVICE_ACCOUNT_IMPERSONATION_URL");
+
+    if (gcpWorkloadAudience == null || gcsBucketName == null) {
+      System.err.println(
+          "Error: GCP_WORKLOAD_AUDIENCE and GCS_BUCKET_NAME environment variables are required.");
+      return;
+    }
+
+    System.out.println("Getting metadata for bucket: " + gcsBucketName + "...");
+    Bucket bucket =
+        authenticateWithAwsCredentials(gcpWorkloadAudience, saImpersonationUrl, gcsBucketName);
+
+    System.out.println(" --- SUCCESS! ---");
+    System.out.printf("Bucket Name: %s%n", bucket.getName());
+    System.out.printf("Bucket Location: %s%n", bucket.getLocation());
+  }
+
+  /**
+   * Authenticates using a custom AWS credential supplier and retrieves bucket metadata.
+   *
+   * @param gcpWorkloadAudience The WIF provider audience.
+   * @param saImpersonationUrl Optional service account impersonation URL.
+   * @param gcsBucketName The GCS bucket name.
+   * @return The Bucket object containing metadata.
+   * @throws IOException If authentication fails.
+   */
+  // [START auth_custom_credential_supplier_aws]
+  public static Bucket authenticateWithAwsCredentials(
+      String gcpWorkloadAudience, String saImpersonationUrl, String gcsBucketName)
+      throws IOException {
+
+    // 1. Instantiate the custom supplier.
+    CustomAwsSupplier customSupplier = new CustomAwsSupplier();
+
+    // 2. Configure the AwsCredentials options.
+    AwsCredentials.Builder credentialsBuilder =
+        AwsCredentials.newBuilder()
+            .setAudience(gcpWorkloadAudience)
+            // This token type indicates that the subject token is an AWS Signature Version 4 signed
+            // request. This is required for AWS Workload Identity Federation.
+            .setSubjectTokenType("urn:ietf:params:aws:token-type:aws4_request")
+            .setAwsSecurityCredentialsSupplier(customSupplier);
+
+    if (saImpersonationUrl != null) {
+      credentialsBuilder.setServiceAccountImpersonationUrl(saImpersonationUrl);
+    }
+
+    GoogleCredentials credentials = credentialsBuilder.build();
+
+    // 3. Use the credentials to make an authenticated request.
+    Storage storage = StorageOptions.newBuilder().setCredentials(credentials).build().getService();
+
+    return storage.get(gcsBucketName);
+  }
+
+  /**
+   * Custom AWS Security Credentials Supplier.
+   *
+   * <p>This implementation resolves AWS credentials and regions using the default provider chains
+   * from the AWS SDK (v2). This supports environment variables, ~/.aws/credentials, and EC2/EKS
+   * metadata.
+   */
+  private static class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
+    private final AwsCredentialsProvider awsCredentialsProvider;
+    private String region;
+
+    public CustomAwsSupplier() {
+      // The AWS SDK handles memoization and refreshing internally.
+      this.awsCredentialsProvider = DefaultCredentialsProvider.create();
+    }
+
+    @Override
+    public String getRegion(ExternalAccountSupplierContext context) {
+      if (this.region == null) {
+        Region awsRegion = new DefaultAwsRegionProviderChain().getRegion();
+        if (awsRegion == null) {
+          throw new IllegalStateException(
+              "Unable to resolve AWS region. Ensure AWS_REGION is set or configured.");
+        }
+        this.region = awsRegion.id();
+      }
+      return this.region;
+    }
+
+    @Override
+    public AwsSecurityCredentials getCredentials(ExternalAccountSupplierContext context) {
+      software.amazon.awssdk.auth.credentials.AwsCredentials credentials =
+          this.awsCredentialsProvider.resolveCredentials();
+
+      if (credentials == null) {
+        throw new IllegalStateException("Unable to resolve AWS credentials.");
+      }
+
+      String sessionToken = null;
+      if (credentials instanceof AwsSessionCredentials) {
+        sessionToken = ((AwsSessionCredentials) credentials).sessionToken();
+      }
+
+      return new AwsSecurityCredentials(
+          credentials.accessKeyId(), credentials.secretAccessKey(), sessionToken);
+    }
+  }
+  // [END auth_custom_credential_supplier_aws]
+}