docs: adding documentation for programmatic auth feature

.readme-partials.yaml

@@ -356,6 +356,55 @@ body: |-
 
   You can now [start using the Auth library](#using-external-identities) to call Google Cloud resources from AWS.
 
+  ### Accessing resources from AWS using a custom AWS security credentials supplier.
+
+  In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements are needed:
+  - A workload identity pool needs to be created.
+  - AWS needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from AWS).
+  - Permission to impersonate a service account needs to be granted to the external identity.
+
+  Follow the detailed [instructions](https://cloud.google.com/iam/docs/access-resources-aws) on how to configure workload identity federation from AWS.
+
+  If you want to use AWS security credentials that cannot be retrieved using methods supported natively by this library,
+  a custom AwsSecurityCredentialsSupplier implementation may be specified when creating an AWS client. The supplier must
+  return valid, unexpired AWS security credentials when called by the GCP credential.
+
+  Note that the client does not cache the returned AWS security credentials, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.
+
+  ```ts
+  class AwsSupplier implements AwsSecurityCredentialsSupplier {
+    async getAwsRegion(context: ExternalAccountSupplierContext): Promise<string> {
+      // Return the current AWS region, i.e. 'us-east-2'.
+    }
+
+    async getAwsSecurityCredentials(
+      context: ExternalAccountSupplierContext
+    ): Promise<AwsSecurityCredentials> {
+      const audience = context.audience;
+      // Return valid AWS security credentials for the requested audience.
+    }
+  }
+
+  const clientOptions = {
+    audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
+    subject_token_type: 'urn:ietf:params:aws:token-type:aws4_request', // Set the subject token type.
+    aws_security_credentials_supplier: new AwsSupplier() // Set the custom supplier.
+  }
+
+  const client = new AwsClient(clientOptions);
+  ```
+
+  Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience) is: `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`
+
+  Where the following variables need to be substituted:
+
+  * `$PROJECT_NUMBER`: The Google Cloud project number.
+  * `$WORKLOAD_POOL_ID`: The workload pool ID.
+  * `$PROVIDER_ID`: The provider ID.
+
+
+  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/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config).
+
   ### Access resources from Microsoft Azure
 
   In order to access Google Cloud resources from Microsoft Azure, the following requirements are needed:
@@ -464,6 +513,44 @@ body: |-
   - `$URL_TO_GET_OIDC_TOKEN`: The URL of the local server endpoint to call to retrieve the OIDC token.
   - `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`.
 
+  ### Accessing resources from an OIDC or SAML2.0 identity provider using a custom supplier
+
+  If you want to use OIDC or SAML2.0 that cannot be retrieved using methods supported natively by this library,
+  a custom SubjectTokenSupplier implementation may be specified when creating an identity pool client. The supplier must
+  return a valid, unexpired subject token when called by the GCP credential.
+
+  Note that the client does not cache the returned subject token, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.
+
+  ```ts
+  class CustomSupplier implements SubjectTokenSupplier {
+    async getSubjectToken(
+      context: ExternalAccountSupplierContext
+    ): Promise<string> {
+      const audience = context.audience;
+      const subjectTokenType = context.subjectTokenType;
+      // Return a valid subject token for the requested audience and subject token type.
+    }
+  }
+
+  const clientOptions = {
+    audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
+    subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type.
+    subject_token_supplier: new CustomSupplier() // Set the custom supplier.
+  }
+
+  const client = new CustomSupplier(clientOptions);
+  ```
+
+  Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience) is: `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`
+
+  Where the following variables need to be substituted:
+
+  * `$PROJECT_NUMBER`: The Google Cloud project number.
+  * `$WORKLOAD_POOL_ID`: The workload pool ID.
+  * `$PROVIDER_ID`: The provider ID.
+
+  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/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config).
+
   #### Using External Account Authorized User workforce credentials
 
   [External account authorized user credentials](https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#browser-based-sign-in) allow you to sign in with a web browser to an external identity provider account via the
@@ -842,6 +929,45 @@ body: |-
   You can now [use the Auth library](#using-external-identities) to call Google Cloud
   resources from an OIDC or SAML provider.
 
+  ### Accessing resources from an OIDC or SAML2.0 identity provider using a custom supplier
+
+  If you want to use OIDC or SAML2.0 that cannot be retrieved using methods supported natively by this library,
+  a custom SubjectTokenSupplier implementation may be specified when creating an identity pool client. The supplier must
+  return a valid, unexpired subject token when called by the GCP credential.
+
+  Note that the client does not cache the returned subject token, so caching logic should be implemented in the supplier to prevent multiple requests for the same resources.
+
+  ```ts
+  class CustomSupplier implements SubjectTokenSupplier {
+    async getSubjectToken(
+      context: ExternalAccountSupplierContext
+    ): Promise<string> {
+      const audience = context.audience;
+      const subjectTokenType = context.subjectTokenType;
+      // Return a valid subject token for the requested audience and subject token type.
+    }
+  }
+
+  const clientOptions = {
+    audience: '//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience.
+    subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type.
+    subject_token_supplier: new CustomSupplier() // Set the custom supplier.
+  }
+
+  const client = new CustomSupplier(clientOptions);
+  ```
+
+  Where the audience is: `//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID`
+
+  Where the following variables need to be substituted:
+
+  * `WORKFORCE_POOL_ID`: The worforce pool ID.
+  * `$PROVIDER_ID`: The provider ID.
+
+  and the workforce pool user project is the project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project).
+
+  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).
+
   ### Using External Identities
 
   External identities (AWS, Azure and OIDC-based providers) can be used with `Application Default Credentials`.

src/auth/awsclient.ts

@@ -26,24 +26,46 @@ import {originalOrCamelOptions, SnakeToCamelObject} from '../util';
  * AWS credentials JSON interface. This is used for AWS workloads.
  */
 export interface AwsClientOptions extends BaseExternalAccountClientOptions {
+  /**
+   * Object containing options to retrieve AWS security credentials. A valid credential
+   * source or a aws security credentials supplier should be specified.
+   */
   credential_source?: {
+    /**
+     * AWS environment ID. Currently only 'AWS1' is supported.
+     */
     environment_id: string;
-    // Region can also be determined from the AWS_REGION or AWS_DEFAULT_REGION
-    // environment variables.
+    /**
+     * The EC2 metadata URL to retrieve the current AWS region from. If this is
+     * not provided, the region should be present in the AWS_REGION or AWS_DEFAULT_REGION
+     * environment variables.
+     */
     region_url?: string;
-    // The url field is used to determine the AWS security credentials.
-    // This is optional since these credentials can be retrieved from the
-    // AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN
-    // environment variables.
+    /**
+     * The EC2 metadata URL to retrieve AWS security credentials. If this is not provided,
+     * the credentials should be present in the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
+     * and AWS_SESSION_TOKEN environment variables.
+     */
     url?: string;
+    /**
+     * The regional GetCallerIdentity action URL, used to determine the account
+     * ID and its roles.
+     */
     regional_cred_verification_url: string;
-    // The imdsv2 session token url is used to fetch session token from AWS
-    // which is later sent through headers for metadata requests. If the
-    // field is missing, then session token won't be fetched and sent with
-    // the metadata requests.
-    // The session token is required for IMDSv2 but optional for IMDSv1
+    /**
+     *  The imdsv2 session token url is used to fetch session token from AWS
+     *  which is later sent through headers for metadata requests. If the
+     *  field is missing, then session token won't be fetched and sent with
+     *  the metadata requests.
+     *  The session token is required for IMDSv2 but optional for IMDSv1
+     */
     imdsv2_session_token_url?: string;
   };
+  /**
+   * The AWS security credentials supplier to call to retrieve the AWS region
+   * and AWS security credentials. Either this or a valid credential source
+   * must be specified.
+   */
   aws_security_credentials_supplier?: AwsSecurityCredentialsSupplier;
 }
 

src/auth/baseexternalclient.ts

@@ -74,8 +74,21 @@ const pkg = require('../../../package.json');
  */
 export {DEFAULT_UNIVERSE} from './authclient';
 
+/**
+ * Shared options used to build {@link ExternalAccountClient} and
+ * {@link ExternalAccountAuthorizedUserClient}.
+ */
 export interface SharedExternalAccountClientOptions extends AuthClientOptions {
+  /**
+   *  The Security Token Service audience, which is usually the fully specified
+   *  resource name of the workload or workforce pool provider.
+   */
   audience: string;
+  /**
+   * The Security Token Service token URL used to exchange the third party token
+   * for a GCP access token. If not provided, will default to
+   * 'https://sts.googleapis.com/v1/token'
+   */
   token_url?: string;
 }
 
@@ -109,16 +122,55 @@ export interface ExternalAccountSupplierContext {
  */
 export interface BaseExternalAccountClientOptions
   extends SharedExternalAccountClientOptions {
+  /**
+   * Credential type, should always be 'external_account'.
+   */
   type?: string;
+  /**
+   * The Security Token Service subject token type based on the OAuth 2.0
+   * token exchange spec. Expected values include:
+   * * 'urn:ietf:params:oauth:token-type:jwt'
+   * * 'urn:ietf:params:aws:token-type:aws4_request'
+   * * 'urn:ietf:params:oauth:token-type:saml2'
+   * * 'urn:ietf:params:oauth:token-type:id_token'
+   */
   subject_token_type: string;
+  /**
+   * The URL for the service account impersonation request. This URL is required
+   * for some APIs. If this URL is not available, the access token from the
+   * Security Token Service is used directly.
+   */
   service_account_impersonation_url?: string;
+  /**
+   * Object containing additional options for service account impersonation.
+   */
   service_account_impersonation?: {
+    /**
+     * The desired lifetime of the impersonated service account access token.
+     * If not provided, the default lifetime will be 3600 seconds.
+     */
     token_lifetime_seconds?: number;
   };
+  /**
+   * The endpoint used to retrieve account related information.
+   */
   token_info_url?: string;
+  /**
+   * Client ID of the service account from the console.
+   */
   client_id?: string;
+  /**
+   * Client secret of the service account from the console.
+   */
   client_secret?: string;
+  /**
+   * The workforce pool user project. Required when using a workforce identity
+   * pool.
+   */
   workforce_pool_user_project?: string;
+  /**
+   * The scopes to request during the authorization grant.
+   */
   scopes?: string[];
   /**
    * @example

src/auth/identitypoolclient.ts

@@ -53,17 +53,47 @@ export interface SubjectTokenSupplier {
  */
 export interface IdentityPoolClientOptions
   extends BaseExternalAccountClientOptions {
+  /**
+   * Object containing options to retrieve identity pool credentials. A valid credential
+   * source or a subject token supplier must be specified.
+   */
   credential_source?: {
+    /**
+     * The file location to read the subject token from. Either this or a URL
+     * should be specified.
+     */
     file?: string;
+    /**
+     * The URL to call to retrieve the subject token. Either this or a file
+     * location should be specified.
+     */
     url?: string;
+    /**
+     * Optional headers to send on the request to the specified URL.
+     */
     headers?: {
       [key: string]: string;
     };
+    /**
+     * The format that the subject token is in the file or the URL response.
+     * If not provided, will default to reading the text string directly.
+     */
     format?: {
+      /**
+       * The format type. Can either be 'text' or 'json'.
+       */
       type: SubjectTokenFormatType;
+      /**
+       * The field name containing the subject token value if the type is 'json'.
+       */
       subject_token_field_name?: string;
     };
   };
+  /**
+   * The subject token supplier to call to retrieve the subject token to exchange
+   * for a GCP access token. Either this or a valid credential source should
+   * be specified.
+   */
   subject_token_supplier?: SubjectTokenSupplier;
 }