[AIP-4117] Adding documentation for configurable token lifetime (aip-…

…dev#938)

Adding documentation for configurable token lifetime for workload identity pools and ADC creation. Also reformatting header types so the table of contents is correct.

aip/auth/4117.md

@@ -74,6 +74,20 @@ $ gcloud iam workload-identity-pools create-cred-config \
     --output-file=$FILEPATH.json
 ```
 
+If you wish to configure the service account access token lifetime,
+an additional flag `--service-account-token-lifetime-seconds` should be added to the [`gcloud iam workload-identity-pools create-cred-config`](/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config) command (this example uses an AWS configuration, but the token lifetime can be configured for all workload identity federation providers):
+
+```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 \
+    --service-account-token-lifetime-seconds=$TOKEN_LIFETIME \
+    --output-file=$FILEPATH.json
+```
+
+The service-account-token-lifetime-seconds flag is optional. If not provided, this defaults to one hour. The minimum allowed value is 600 (10 minutes) and the maximum allowed value is 43200 (12 hours). If a lifetime greater than one hour is required, the service account must be added as an allowed value in an Organization Policy that enforces the `constraints/iam.allowServiceAccountCredentialLifetimeExtension` constraint.
+
 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
@@ -119,7 +133,7 @@ scoped_credentials = credentials.with_scopes(
     ['https://www.googleapis.com/auth/cloud-platform'])
 ```
 
-### Expected Behavior
+## Expected Behavior
 
 The auth libraries should use the information in the JSON configuration file to
 retrieve the external credentials and exchange them for Google access tokens
@@ -136,6 +150,7 @@ All external account JSON files must share the following fields:
 | audience                          | Yes      | This is the STS audience which contains the resource name for the workload identity pool and the provider identifier in that pool. |
 | subject_token_type                | Yes      | This is the STS subject token type based on the [OAuth 2.0 token exchange spec][7]. |
 | service_account_impersonation_url | No       | This is the URL for the service account impersonation request. If this is not available, the STS returned access token should be directly used without impersonation. |
+| service_account_impersonation.*   | No       | This object defines additional service account impersonation options. Only one field is currently supported: “token_lifetime_seconds": This is the requested access token lifetime, e.g. `2800`.  |
 | token_url                         | Yes      | This is the STS token exchange endpoint. |
 | credential_source.*               | Yes      | This object defines the mechanism used to retrieve the external credential from the local environment so that it can be exchanged for a GCP access token via the STS endpoint. |
 
@@ -176,8 +191,11 @@ types of external account credentials:
     `https://www.googleapis.com/auth/cloud-platform` or IAM scope
     `https://www.googleapis.com/auth/iam`) are required in the underlying
     access token.
+  - The service account access token lifetime also needs to be provided for this endpoint. The value in
+    **service_account_impersonation.token_lifetime_seconds** will be used if it
+    was provided, otherwise it will default to 1 hour.
 
-#### Determining the subject token in AWS
+### Determining the subject token in AWS
 
 External account configuration JSON files should contain the following
 information in the `credential_source` object to facilitate retrieval of AWS
@@ -274,7 +292,7 @@ The auth libraries and applications **must** follow the steps below:
   ```
   For the AWS token, STS requires a special header `x-goog-cloud-endpoint` to recognize that the token is for a specific workload identity provider.
 
-#### Determining the subject token in Microsoft Azure and URL-sourced credentials
+### Determining the subject token in Microsoft Azure and URL-sourced credentials
 
 External account configuration JSON files should contain the following
 information in the `credential_source` object to facilitate retrieval of Azure
@@ -347,7 +365,7 @@ The auth libraries and applications **must** follow the steps below:
   - Parse the file as JSON and then retrieve the external credential from
     the field name based on the value of **subject_token_field_name**.
 
-#### Determining the subject token in file-sourced credentials
+### Determining the subject token in file-sourced credentials
 
 External account configuration JSON files contain the following information
 in the `credential_source` object to facilitate retrieval of file-sourced
@@ -391,7 +409,7 @@ The auth libraries and applications **must** follow the steps below:
     the field name based on the value of **subject_token_field_name**.
 
 
-#### Determining the subject token in executable-sourced credentials
+### Determining the subject token in executable-sourced credentials
 
 External account configuration JSON files contain the following information
 in the `credential_source` object to facilitate retrieval of executable-sourced
@@ -512,6 +530,7 @@ The auth libraries and applications **must** follow the steps below:
 
 - **2021-12-10**: Add AIP for External Account Credentials (AIP 4117).
 - **2022-05-18**: Document executable-sourced credentials (AIP 4117).
+- **2022-08-31**: Document configurable token lifetime (AIP 4117).
 
 <!-- prettier-ignore-start -->
 [0]: https://cloud.google.com/iam/docs/configuring-workload-identity-federation#aws