[AIP-4117] Document changes for AWS IMDSv2 (#910)

For AWS EC2 instances that are using IMDSv2, a session token needs to be added to metadata endpoint requests. This PR documents the changes to the gcloud command to generate the config and how the auth libraries use the new imdsv2_session_token_url.

Author: sai-sunder-s

aip/auth/4117.md

@@ -62,6 +62,18 @@ The following values would need to be replaced:
   impersonate.
 - **FILEPATH**: File to save configuration to.
 
+If you are using [AWS IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html),
+an additional flag `--enable-imdsv2` should be added to the [`gcloud iam workload-identity-pools create-cred-config`](/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config) command:
+
+```bash
+$ gcloud iam workload-identity-pools create-cred-config \
+    projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID \
+    --service-account=$SERVICE_ACCOUNT_EMAIL \
+    --aws \
+    --enable-imdsv2 \
+    --output-file=$FILEPATH.json
+```
+
 The external identities configuration file can be used with
 [Application Default Credentials][6]. In order to use external identities with
 Application Default Credentials, the full path to this file should be stored
@@ -178,6 +190,7 @@ endpoint.
 | region_url                     | Yes      | This URL should be used to determine the current AWS region needed for the signed request construction. |
 | url                            | No       | This AWS metadata server URL should be used to retrieve the access key, secret key and security token needed to sign the `GetCallerIdentity` request. The $ROLE_NAME should be retrieved from calling this endpoint without any parameter and then calling again with the returned role name appended to this URL: http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE_NAME |
 | regional_cred_verification_url | Yes      | This defines the regional AWS `GetCallerIdentity` action URL. This URL should be used to determine the AWS account ID and its roles. This should not actually be called by the Auth libraries. It should be called on the STS token server. The region should be substituted by SDK, e.g. `sts.eu-west-1.amazonaws`.com. |
+| imdsv2_session_token_url       | No       | Presence of this URL enforces the auth libraries to fetch a Session Token from AWS. This field is required for EC2 instances using IMDSv2. This Session Token would later be used while making calls to the metadata enpoint. |
 
 The JSON file for AWS configuration files should have the following form:
 
@@ -192,7 +205,8 @@ The JSON file for AWS configuration files should have the following form:
     "environment_id": "aws1",
     "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone",
     "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials",
-    "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"
+    "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15",
+    "imdsv2_session_token_url": "http://169.254.169.254/latest/api/token"
   }
 }
 ```
@@ -204,6 +218,8 @@ The auth libraries and applications **must** follow the steps below:
 - Inspect the version in the environment ID. If this is a newer unexpected
   error, trigger an error that the auth library needs to be updated to handle
   this type of credentials.
+- If **imdsv2_session_token_url** is available, then fetch session token
+  from **imdsv2_session_token_url**.
 - Check the environment variables in the following order (`AWS_REGION` and
   then the `AWS_DEFAULT_REGION`) to determine the AWS region. If found, skip
   using the AWS metadata server to determine this value.