or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

adc.md crypto.md external-identity.md index.md oauth2.md service-accounts.md token-management.md

tile.json

External Identity Federation

Support for workload identity federation allowing authentication from external identity providers (AWS, Azure, OIDC) to access Google Cloud resources without storing service account keys.

Capabilities

Base External Account Client

Abstract base class for external identity provider authentication.

/**
 * Base class for external account clients using workload identity federation
 * Supports STS token exchange to get Google Cloud access tokens
 */
abstract class BaseExternalAccountClient extends AuthClient {
  constructor(options: BaseExternalAccountClientOptions);
  
  /** Get access token via STS token exchange */
  getAccessToken(): Promise<{ token?: string | null; res?: GaxiosResponse }>;
  
  /** Retrieve subject token from external provider (abstract) */
  abstract retrieveSubjectToken(): Promise<string>;
  
  /** Get project ID */
  getProjectId(): Promise<string | null>;
  
  /** Get service account email for impersonation */
  getServiceAccountEmail(): Promise<string | null>;
}

interface BaseExternalAccountClientOptions {
  /** Audience for STS token exchange */
  audience?: string;
  /** Subject token type */
  subject_token_type?: string;
  /** Token URL for STS exchange */
  token_url?: string;
  /** Service account impersonation URL */
  service_account_impersonation_url?: string;
  /** Client ID */
  client_id?: string;
  /** Quota project ID */
  quota_project_id?: string;
  /** Universe domain */
  universe_domain?: string;
}

interface SharedExternalAccountClientOptions {
  /** Credential source configuration */
  credential_source?: { [key: string]: any };
  /** OAuth2 scopes */
  scopes?: string | string[];
}

interface ExternalAccountSupplierContext {
  /** STS audience */
  audience: string;
  /** Subject token type */
  subject_token_type: string;
}

interface IamGenerateAccessTokenResponse {
  /** Generated access token */
  accessToken: string;
  /** Token expiry time */
  expireTime: string;
}

AWS Client

Client for AWS workload identity federation.

/**
 * AWS workload identity federation client
 * Allows AWS resources to authenticate to Google Cloud
 */
class AwsClient extends BaseExternalAccountClient {
  constructor(options: AwsClientOptions);
  
  /** Retrieve AWS subject token for STS exchange */
  retrieveSubjectToken(): Promise<string>;
}

interface AwsClientOptions extends BaseExternalAccountClientOptions, SharedExternalAccountClientOptions {
  /** AWS credential source configuration */
  credential_source?: {
    /** AWS environment ID */
    environment_id?: string;
    /** AWS regional credential verification URL */
    regional_cred_verification_url?: string;
    /** AWS region */
    region?: string;
    /** AWS security credentials supplier */
    security_credentials_supplier?: AwsSecurityCredentialsSupplier;
  };
}

interface AwsSecurityCredentials {
  /** AWS access key ID */
  accessKeyId: string;
  /** AWS secret access key */
  secretAccessKey: string;
  /** AWS session token */
  sessionToken?: string;
}

type AwsSecurityCredentialsSupplier = (context: ExternalAccountSupplierContext) => Promise<AwsSecurityCredentials>;

Usage Examples:

import { AwsClient } from "google-auth-library";

// AWS workload identity federation
const awsClient = new AwsClient({
  audience: '//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider',
  subject_token_type: 'urn:ietf:params:aws:token-type:aws4_request',
  token_url: 'https://sts.googleapis.com/v1/token',
  credential_source: {
    environment_id: 'aws1',
    region: 'us-east-1',
    regional_cred_verification_url: 'https://sts.us-east-1.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15'
  },
  service_account_impersonation_url: 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com:generateAccessToken'
});

// Get access token
const { token } = await awsClient.getAccessToken();

// Use with Google Cloud APIs
const response = await awsClient.request({
  url: 'https://storage.googleapis.com/storage/v1/b',
  params: { project: 'my-project' }
});

Identity Pool Client

Client for generic external identity pools.

/**
 * Identity Pool workload identity federation client
 * Supports OIDC and SAML identity providers
 */
class IdentityPoolClient extends BaseExternalAccountClient {
  constructor(options: IdentityPoolClientOptions);
  
  /** Retrieve subject token from identity provider */
  retrieveSubjectToken(): Promise<string>;
}

interface IdentityPoolClientOptions extends BaseExternalAccountClientOptions, SharedExternalAccountClientOptions {
  /** Identity provider credential source */
  credential_source?: {
    /** File path to subject token */
    file?: string;
    /** URL to retrieve subject token */
    url?: string;
    /** Headers for URL request */
    headers?: { [key: string]: string };
    /** Subject token field name */
    format?: {
      type: 'json' | 'text';
      subject_token_field_name?: string;
    };
  };
}

type SubjectTokenSupplier = (context: ExternalAccountSupplierContext) => Promise<string>;

Usage Examples:

import { IdentityPoolClient } from "google-auth-library";

// File-based subject token
const identityPoolClient = new IdentityPoolClient({
  audience: '//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider',
  subject_token_type: 'urn:ietf:params:oauth:token-type:jwt',
  token_url: 'https://sts.googleapis.com/v1/token',
  credential_source: {
    file: '/path/to/subject-token.txt'
  }
});

// URL-based subject token
const identityPoolClient = new IdentityPoolClient({
  audience: '//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider',
  subject_token_type: 'urn:ietf:params:oauth:token-type:jwt',
  token_url: 'https://sts.googleapis.com/v1/token',
  credential_source: {
    url: 'http://metadata.service/token',
    headers: {
      'Metadata-Flavor': 'my-provider'
    },
    format: {
      type: 'json',
      subject_token_field_name: 'access_token'
    }
  }
});

// Get access token
const { token } = await identityPoolClient.getAccessToken();

External Account Authorized User Client

Client for external account authorized users.

/**
 * External account authorized user client
 * For users authenticated via external identity providers
 */
class ExternalAccountAuthorizedUserClient extends AuthClient {
  constructor(options: ExternalAccountAuthorizedUserClientOptions);
  
  /** Get access token */
  getAccessToken(): Promise<{ token?: string | null; res?: GaxiosResponse }>;
  
  /** Refresh access token */
  refreshAccessToken(): Promise<RefreshAccessTokenResponse>;
}

interface ExternalAccountAuthorizedUserClientOptions {
  /** Client ID */
  client_id?: string;
  /** Client secret */
  client_secret?: string;
  /** Refresh token */
  refresh_token?: string;
  /** Token URL */
  token_url?: string;
  /** Revoke URL */
  revoke_url?: string;
  /** Quota project ID */
  quota_project_id?: string;
}

Pluggable Authentication

Support for pluggable authentication via external executables.

/**
 * Pluggable authentication client using external executables
 */
class PluggableAuthClient extends BaseExternalAccountClient {
  constructor(options: PluggableAuthClientOptions);
  
  /** Retrieve subject token from executable */
  retrieveSubjectToken(): Promise<string>;
}

interface PluggableAuthClientOptions extends BaseExternalAccountClientOptions {
  /** Credential source with executable configuration */
  credential_source?: {
    /** Executable configuration */
    executable?: {
      /** Command to execute */
      command?: string;
      /** Command timeout in milliseconds */
      timeout_millis?: number;
      /** Output file path */
      output_file?: string;
    };
  };
}

interface ExecutableError {
  /** Error code */
  code?: string;
  /** Error message */
  message?: string;
}

STS Credentials

Security Token Service (STS) credential operations.

/**
 * STS credentials for token exchange
 */
class StsCredentials {
  constructor(tokenExchangeEndpoint: string, resource?: string, audience?: string);
  
  /** Exchange external token for Google Cloud access token */
  exchangeToken(
    subjectToken: string,
    subjectTokenType: string,
    requestedTokenType?: string,
    audience?: string,
    scopes?: string[]
  ): Promise<StsCredentialsResponse>;
}

interface StsCredentialsResponse {
  /** Access token */
  access_token: string;
  /** Token type */
  token_type: string;
  /** Expires in seconds */
  expires_in: number;
  /** Refresh token */
  refresh_token?: string;
  /** Scope */
  scope?: string;
}

Executable-Based Authentication

Support for executable-based authentication using custom scripts or programs to retrieve third-party credentials.

/**
 * Pluggable authentication client using external executables
 * Allows workload identity federation via custom scripts that return subject tokens
 */
class PluggableAuthClient extends BaseExternalAccountClient {
  constructor(options: PluggableAuthClientOptions);
  
  /** Retrieve subject token from external executable */
  retrieveSubjectToken(): Promise<string>;
}

interface PluggableAuthClientOptions extends BaseExternalAccountClientOptions {
  /** Credential source with executable configuration */
  credential_source: {
    executable: {
      /** Command to execute (required) */
      command: string;
      /** Command timeout in milliseconds (default: 30000, min: 5000, max: 120000) */
      timeout_millis?: number;
      /** Output file path for caching responses */
      output_file?: string;
    };
  };
}

/**
 * Error thrown by executable during authentication
 */
class ExecutableError extends Error {
  /** The exit code returned by the executable */
  readonly code: string;
  
  constructor(message: string, code: string);
}

Usage Examples:

import { PluggableAuthClient } from "google-auth-library";

// Before using executable-based authentication, set environment variable
process.env.GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES = '1';

// Configure pluggable auth client with executable
const pluggableClient = new PluggableAuthClient({
  audience: '//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider',
  subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
  token_url: 'https://sts.googleapis.com/v1/token',
  credential_source: {
    executable: {
      command: '/path/to/token-provider.sh --audience={audience}',
      timeout_millis: 10000,
      output_file: '/tmp/cached-token.json'
    }
  },
  service_account_impersonation_url: 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com:generateAccessToken'
});

// Get access token (executes the script)
try {
  const { token } = await pluggableClient.getAccessToken();
  console.log('Access token obtained from executable');
} catch (error) {
  if (error instanceof ExecutableError) {
    console.error(`Executable failed with code ${error.code}: ${error.message}`);
  }
}

Executable Response Format:

The executable must output JSON to STDOUT in the following format:

OIDC Success Response:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620433341
}

SAML2 Success Response:

{
  "version": 1,
  "success": true,  
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620433341
}

Error Response:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Authentication failed"
}

Environment Variables Available to Executable:

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: STS audience
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: Subject token type
GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE: Always "0" (interactive mode not supported)
GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: Service account email (if impersonation configured)
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Output file path (if configured)

Error Handling

Common external identity federation errors:

Invalid audience: Workload identity pool audience is incorrect
Subject token expired: External provider token has expired
Permission denied: Service account impersonation not allowed
Provider not found: Workload identity provider doesn't exist
Executable errors: Custom script failures or configuration issues

try {
  const awsClient = new AwsClient(options);
  const { token } = await awsClient.getAccessToken();
} catch (error) {
  if (error.message.includes('Invalid audience')) {
    console.error('Check workload identity pool audience configuration');
  } else if (error.response?.status === 403) {
    console.error('Service account impersonation permission denied');
  }
}

Version

Tile

Files

external-identity.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

External Identity Federation

Capabilities

Base External Account Client

AWS Client

Identity Pool Client

External Account Authorized User Client

Pluggable Authentication

STS Credentials

Executable-Based Authentication

Error Handling

external-identity.mddocs/