feat: Add AWS Session Token to Metadata Requests

README.md

@@ -406,6 +406,11 @@ Where the following variables need to be substituted:
 
 This will generate the configuration file in the specified output file.
 
+If you want to use the AWS IMDSv2 flow, you can add the field below to the credential_source in your AWS ADC configuration file:
+"aws_session_token_url": "http://169.254.169.254/latest/api/token"
+
+The gcloud create-cred-config command will be updated to support this soon.
+
 You can now [start using the Auth library](#using-external-identities) to call Google Cloud resources from AWS.
 
 ### Access resources from Microsoft Azure

linkinator.config.json

@@ -3,7 +3,8 @@
   "skip": [
     "https://codecov.io/gh/googleapis/",
     "www.googleapis.com",
-    "img.shields.io"
+    "img.shields.io",
+    "http://169.254.169.254/latest/api/token%22"
   ],
   "silent": true,
   "concurrency": 10

src/auth/awsclient.ts

@@ -19,7 +19,7 @@ import {
   BaseExternalAccountClient,
   BaseExternalAccountClientOptions,
 } from './baseexternalclient';
-import {RefreshOptions} from './oauth2client';
+import {RefreshOptions, Headers} from './oauth2client';
 
 /**
  * AWS credentials JSON interface. This is used for AWS workloads.
@@ -36,6 +36,12 @@ export interface AwsClientOptions extends BaseExternalAccountClientOptions {
     // environment variables.
     url?: string;
     regional_cred_verification_url: string;
+    // The aws 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 IDMSv2 but optional for IDMSv1
+    aws_session_token_url?: string;
   };
 }
 
@@ -62,6 +68,7 @@ export class AwsClient extends BaseExternalAccountClient {
   private readonly regionUrl?: string;
   private readonly securityCredentialsUrl?: string;
   private readonly regionalCredVerificationUrl: string;
+  private readonly awsSessionTokenUrl?: string;
   private awsRequestSigner: AwsRequestSigner | null;
   private region: string;
 
@@ -86,6 +93,7 @@ export class AwsClient extends BaseExternalAccountClient {
     this.securityCredentialsUrl = options.credential_source.url;
     this.regionalCredVerificationUrl =
       options.credential_source.regional_cred_verification_url;
+    this.awsSessionTokenUrl = options.credential_source.aws_session_token_url;
     const match = this.environmentId?.match(/^(aws)(\d+)$/);
     if (!match || !this.regionalCredVerificationUrl) {
       throw new Error('No valid AWS "credential_source" provided');
@@ -106,22 +114,32 @@ export class AwsClient extends BaseExternalAccountClient {
    * this uses a serialized AWS signed request to the STS GetCallerIdentity
    * endpoint.
    * The logic is summarized as:
-   * 1. Retrieve AWS region from availability-zone.
-   * 2a. Check AWS credentials in environment variables. If not found, get
+   * 1. If aws_session_token_url is provided in the credential source, then
+   *    fetch the aws session token and include it in the headers of the
+   *    metadata requests. This is a requirement for IDMSv2 but optional
+   *    for IDMSv1.
+   * 2. Retrieve AWS region from availability-zone.
+   * 3a. Check AWS credentials in environment variables. If not found, get
    *     from security-credentials endpoint.
-   * 2b. Get AWS credentials from security-credentials endpoint. In order
+   * 3b. Get AWS credentials from security-credentials endpoint. In order
    *     to retrieve this, the AWS role needs to be determined by calling
    *     security-credentials endpoint without any argument. Then the
    *     credentials can be retrieved via: security-credentials/role_name
-   * 3. Generate the signed request to AWS STS GetCallerIdentity action.
-   * 4. Inject x-goog-cloud-target-resource into header and serialize the
+   * 4. Generate the signed request to AWS STS GetCallerIdentity action.
+   * 5. Inject x-goog-cloud-target-resource into header and serialize the
    *    signed request. This will be the subject-token to pass to GCP STS.
    * @return A promise that resolves with the external subject token.
    */
   async retrieveSubjectToken(): Promise<string> {
     // Initialize AWS request signer if not already initialized.
     if (!this.awsRequestSigner) {
-      this.region = await this.getAwsRegion();
+      const metadataHeaders: Headers = {};
+      if (this.awsSessionTokenUrl) {
+        metadataHeaders['x-aws-ec2-metadata-token'] =
+          await this.getAwsSessionToken();
+      }
+
+      this.region = await this.getAwsRegion(metadataHeaders);
       this.awsRequestSigner = new AwsRequestSigner(async () => {
         // Check environment variables for permanent credentials first.
         // https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html
@@ -137,12 +155,15 @@ export class AwsClient extends BaseExternalAccountClient {
           };
         }
         // Since the role on a VM can change, we don't need to cache it.
-        const roleName = await this.getAwsRoleName();
+        const roleName = await this.getAwsRoleName(metadataHeaders);
         // Temporary credentials typically last for several hours.
         // Expiration is returned in response.
         // Consider future optimization of this logic to cache AWS tokens
         // until their natural expiration.
-        const awsCreds = await this.getAwsSecurityCredentials(roleName);
+        const awsCreds = await this.getAwsSecurityCredentials(
+          roleName,
+          metadataHeaders
+        );
         return {
           accessKeyId: awsCreds.AccessKeyId,
           secretAccessKey: awsCreds.SecretAccessKey,
@@ -197,10 +218,21 @@ export class AwsClient extends BaseExternalAccountClient {
     );
   }
 
+  private async getAwsSessionToken(): Promise<string> {
+    const opts: GaxiosOptions = {
+      url: this.awsSessionTokenUrl,
+      method: 'PUT',
+      responseType: 'text',
+      headers: {'x-aws-ec2-metadata-token-ttl-seconds': '21600'},
+    };
+    const response = await this.transporter.request<string>(opts);
+    return response.data;
+  }
+
   /**
    * @return A promise that resolves with the current AWS region.
    */
-  private async getAwsRegion(): Promise<string> {
+  private async getAwsRegion(headers: Headers): Promise<string> {
     // Priority order for region determination:
     // AWS_REGION > AWS_DEFAULT_REGION > metadata server.
     if (process.env['AWS_REGION'] || process.env['AWS_DEFAULT_REGION']) {
@@ -216,6 +248,7 @@ export class AwsClient extends BaseExternalAccountClient {
       url: this.regionUrl,
       method: 'GET',
       responseType: 'text',
+      headers: headers,
     };
     const response = await this.transporter.request<string>(opts);
     // Remove last character. For example, if us-east-2b is returned,
@@ -227,7 +260,7 @@ export class AwsClient extends BaseExternalAccountClient {
    * @return A promise that resolves with the assigned role to the current
    *   AWS VM. This is needed for calling the security-credentials endpoint.
    */
-  private async getAwsRoleName(): Promise<string> {
+  private async getAwsRoleName(headers: Headers): Promise<string> {
     if (!this.securityCredentialsUrl) {
       throw new Error(
         'Unable to determine AWS role name due to missing ' +
@@ -238,6 +271,7 @@ export class AwsClient extends BaseExternalAccountClient {
       url: this.securityCredentialsUrl,
       method: 'GET',
       responseType: 'text',
+      headers: headers,
     };
     const response = await this.transporter.request<string>(opts);
     return response.data;
@@ -251,11 +285,13 @@ export class AwsClient extends BaseExternalAccountClient {
    *   needed for creating the GetCallerIdentity signed request.
    */
   private async getAwsSecurityCredentials(
-    roleName: string
+    roleName: string,
+    headers: Headers
   ): Promise<AwsSecurityCredentials> {
     const response = await this.transporter.request<AwsSecurityCredentials>({
       url: `${this.securityCredentialsUrl}/${roleName}`,
       responseType: 'json',
+      headers: headers,
     });
     return response.data;
   }

test/test.awsclient.ts

@@ -44,6 +44,7 @@ describe('AwsClient', () => {
   const secretAccessKey = awsSecurityCredentials.SecretAccessKey;
   const token = awsSecurityCredentials.Token;
   const awsRole = 'gcp-aws-role';
+  const awsSessionToken = 'sessiontoken';
   const audience = getAudience();
   const metadataBaseUrl = 'http://169.254.169.254';
   const awsCredentialSource = {
@@ -265,6 +266,47 @@ describe('AwsClient', () => {
         scope.done();
       });
 
+      it('should resolve on success with aws session token', async () => {
+        const scopes: nock.Scope[] = [];
+        scopes.push(
+          nock(metadataBaseUrl, {
+            reqheaders: {'x-aws-ec2-metadata-token-ttl-seconds': '21600'},
+          })
+            .put('/latest/api/token')
+            .reply(200, awsSessionToken)
+        );
+
+        scopes.push(
+          nock(metadataBaseUrl, {
+            reqheaders: {'x-aws-ec2-metadata-token': awsSessionToken},
+          })
+            .get('/latest/meta-data/placement/availability-zone')
+            .reply(200, `${awsRegion}b`)
+            .get('/latest/meta-data/iam/security-credentials')
+            .reply(200, awsRole)
+            .get(`/latest/meta-data/iam/security-credentials/${awsRole}`)
+            .reply(200, awsSecurityCredentials)
+        );
+
+        const credentialSourceWithSessionTokenUrl = Object.assign(
+          {aws_session_token_url: `${metadataBaseUrl}/latest/api/token`},
+          awsCredentialSource
+        );
+        const awsOptionsWithSessionTokenUrl = {
+          type: 'external_account',
+          audience,
+          subject_token_type: 'urn:ietf:params:aws:token-type:aws4_request',
+          token_url: getTokenUrl(),
+          credential_source: credentialSourceWithSessionTokenUrl,
+        };
+
+        const client = new AwsClient(awsOptionsWithSessionTokenUrl);
+        const subjectToken = await client.retrieveSubjectToken();
+
+        assert.deepEqual(subjectToken, expectedSubjectToken);
+        scopes.forEach(scope => scope.done());
+      });
+
       it('should resolve on success with permanent creds', async () => {
         const permanentAwsSecurityCredentials = Object.assign(
           {},