Skip to content

Commit 0295465

Browse files
cesarghalicesarghali
authored
Fix indentation issues in AIP 4118 and 4119 (#947)
1 parent 363aa43 commit 0295465

2 files changed

Lines changed: 103 additions & 92 deletions

File tree

‎aip/auth/4118.md‎

Lines changed: 44 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,9 @@ describes the general guidance of supporting such authentication.
2929
On Google Cloud, workload credentials should be provisioned using one of the
3030
following methods:
3131

32-
- [Set up service security with Envoy][3].
33-
- [Set up service security with proxyless gRPC][4].
32+
- [Set up service security with Envoy][3].
33+
34+
- [Set up service security with proxyless gRPC][4].
3435

3536
In order for workload credentials to be properly used, the auth libraries
3637
**must** support the automatic switching of the service endpoint to its mTLS
@@ -44,14 +45,14 @@ added as a **"cert_configs"** type as follows:
4445

4546
```json
4647
{
47-
“version”: 1
48+
"version": 1
4849
"cert_configs": {
4950
"workload": {
5051
"cert_path": "path/to/cert/file"
5152
"key_path": "path/to/key/file"
52-
“workload_identity_provider”: “...”
53+
"workload_identity_provider": "..."
5354
"authenticate_as_identity_type": "gsa/native"
54-
“service_account_email”: “...”
55+
"service_account_email": "..."
5556
},
5657
"keychain": {
5758
...
@@ -78,15 +79,16 @@ environment variable.
7879
The following lists the fields of the **"workload"** certificate info type that
7980
are relevant to workload credentials:
8081

81-
- **"cert_path"**: The specified value will be used as the full path to locate
82-
the workload certificate file. This file **must** contain a PEM-encoded
83-
X.509 certificate chain (ordered from leaf to root) where the leaf
84-
certificate is a valid X.509 SVID. The chain __may__ consist of only the
85-
leaf certificate.
86-
- **"key_path"**: The specified value will be used as the full path to locate
87-
the workload private key file. This file must contain a PEM-formatted
88-
private key associated with the X.509 certificate specified by
89-
**“cert_path”**.
82+
- **"cert_path"**: The specified value will be used as the full path to locate
83+
the workload certificate file. This file **must** contain a PEM-encoded
84+
X.509 certificate chain (ordered from leaf to root) where the leaf
85+
certificate is a valid X.509 SVID. The chain __may__ consist of only the
86+
leaf certificate.
87+
88+
- **"key_path"**: The specified value will be used as the full path to locate
89+
the workload private key file. This file must contain a PEM-formatted
90+
private key associated with the X.509 certificate specified by
91+
**“cert_path”**.
9092

9193
The description of the **"workload_identity_provider"**,
9294
**"authenticate_as_identity_type"** and **"service_account_email"** fields can
@@ -103,30 +105,34 @@ Support for mTLS authentication to Google APIs using workload credentials
103105
**must** give priority to user mTLS endpoint override via client options. The
104106
auth libraries **must** follow the steps below:
105107

106-
- Locate the workload certificate and private key files using the above
107-
config file. If one of these files is not present, mTLS using workload
108-
credentials may be disabled. The auth libraries **must** check that the
109-
public and private keys in the certificate and key files match before
110-
passing them to the TLS library.
111-
- Occasional mismatches may happen, since during certificate rotation the
112-
client library may read the two files while another process is replacing
113-
them. In that case, the library **must** retry reading the certificate
114-
and private key files and checking their match status, up to a maximum
115-
of four attempts. The library **should** wait for 5 seconds between
116-
attempts.
117-
- If the certificate and private key files are loaded in memory (as
118-
opposed to being read from disk for every mTLS connection), the auth
119-
libraries **must** periodically reload them (at least every 10 minutes
120-
or when the certificate expires) to refresh their copies in memory after
121-
the infrastructure rotates them. Refreshing the credentials **must** be
122-
done in a background thread and not upon usage.
123-
- Configure the TLS library to use the found, and matched, certificate and
124-
key for client authentication during the TLS handshake.
125-
- If the user specifies the endpoint override via client options, use it as is
126-
and connect to the specified endpoint using mTLS.
127-
- If the user does not specify the endpoint override, use the default mTLS
128-
endpoint if the certificate and key files exist and the default regular
129-
endpoint otherwise.
108+
- Locate the workload certificate and private key files using the above
109+
config file. If one of these files is not present, mTLS using workload
110+
credentials may be disabled. The auth libraries **must** check that the
111+
public and private keys in the certificate and key files match before
112+
passing them to the TLS library.
113+
114+
- Occasional mismatches may happen, since during certificate rotation the
115+
client library may read the two files while another process is replacing
116+
them. In that case, the library **must** retry reading the certificate
117+
and private key files and checking their match status, up to a maximum
118+
of four attempts. The library **should** wait for 5 seconds between
119+
attempts.
120+
- If the certificate and private key files are loaded in memory (as
121+
opposed to being read from disk for every mTLS connection), the auth
122+
libraries **must** periodically reload them (at least every 10 minutes
123+
or when the certificate expires) to refresh their copies in memory after
124+
the infrastructure rotates them. Refreshing the credentials **must** be
125+
done in a background thread and not upon usage.
126+
127+
- Configure the TLS library to use the found, and matched, certificate and
128+
key for client authentication during the TLS handshake.
129+
130+
- If the user specifies the endpoint override via client options, use it as is
131+
and connect to the specified endpoint using mTLS.
132+
133+
- If the user does not specify the endpoint override, use the default mTLS
134+
endpoint if the certificate and key files exist and the default regular
135+
endpoint otherwise.
130136

131137
Note that mTLS 1.3 **must** be the only supported version to preserve client
132138
identity and certificate confidentiality.

‎aip/auth/4119.md‎

Lines changed: 59 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -46,14 +46,14 @@ default location of this file can be changed using the
4646

4747
```json
4848
{
49-
“version”: 1
49+
"version": 1
5050
"cert_configs": {
5151
"workload": {
5252
"cert_path": "path/to/cert/file"
5353
"key_path": "path/to/key/file"
54-
“workload_identity_provider”: “...”
54+
"workload_identity_provider": "..."
5555
"authenticate_as_identity_type": "gsa/native"
56-
“service_account_email”: “...”
56+
"service_account_email": "..."
5757
},
5858
"keychain": {
5959
...
@@ -73,75 +73,80 @@ default location of this file can be changed using the
7373

7474
The following lists the fields relevant to mTLS token binding configuration:
7575

76-
- **"workload_identity_provider"**: The specified value will be used to
77-
populate the request to Security Token Service (STS) to request
78-
identity-bound access tokens. This value refers to the fully qualified name
79-
of the workload identity pool and identity provider configured in IAM. The
80-
specified value **must** be of the following format.
76+
- **"workload_identity_provider"**: The specified value will be used to
77+
populate the request to Security Token Service (STS) to request
78+
identity-bound access tokens. This value refers to the fully qualified name
79+
of the workload identity pool and identity provider configured in IAM. The
80+
specified value **must** be of the following format.
8181

8282
```
8383
"workload_identity_provider":"//iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_identifier>/providers/<provider_identifier>"
8484
```
8585

86-
- **"authenticate_as_identity_type"**: This field specifies what identity is
87-
used to authenticate to Google APIs. The value can be set to `gsa` or
88-
`native`, where `gsa` is the GCP service account of the workload, e.g., the
89-
GCP service account of a GCE VM, and `native` is the native workload
90-
identity, e.g., the GKE pod kubernetes service account. If not specified,
91-
the default value is `gsa`.
92-
93-
- **"service_account_email"**: If set, the specified value will be used to
94-
populate the request to the IAM Credentials service to request
95-
identity-bound access tokens. This value refers to the service account email
96-
to be used for resource access. If not set, the service account email will
97-
be determined automatically by querying the following Metadata Service
98-
endpoint:
99-
`http://metadata/computeMetadata/v1/instance/service-accounts/default/email`.
100-
The value of this field is only relevant if
101-
**"authenticate_as_identity_type"** is set to `gsa`.
86+
- **"authenticate_as_identity_type"**: This field specifies what identity is
87+
used to authenticate to Google APIs. The value can be set to `gsa` or
88+
`native`, where `gsa` is the GCP service account of the workload, e.g., the
89+
GCP service account of a GCE VM, and `native` is the native workload
90+
identity, e.g., the GKE pod kubernetes service account. If not specified,
91+
the default value is `gsa`.
92+
93+
- **"service_account_email"**: If set, the specified value will be used to
94+
populate the request to the IAM Credentials service to request
95+
identity-bound access tokens. This value refers to the service account email
96+
to be used for resource access. If not set, the service account email will
97+
be determined automatically by querying the following Metadata Service
98+
endpoint:
99+
`http://metadata/computeMetadata/v1/instance/service-accounts/default/email`.
100+
The value of this field is only relevant if
101+
**"authenticate_as_identity_type"** is set to `gsa`.
102102

103103
The description of the **"cert_path"** and **"key_path"** fields can be found in
104104
[Mutual Authentication Using Workload Credentials][2].
105105

106106
To enable using token binding when communicating with Google APIs the following
107107
conditions are required:
108108

109-
- [Mutual Authentication Using Workload Credentials][2] **must** be enabled.
110-
- The **"workload_identity_provider"** **must** be present,
111-
**"authenticate_as_identity_type"** __may__ be set and
112-
**"service_account_email"** __may__ be set in the **"workload"**
113-
section of the **"~/.config/gcloud/certificate_config.json"** configuration
114-
file.
109+
- [Mutual Authentication Using Workload Credentials][2] **must** be enabled.
110+
111+
- The **"workload_identity_provider"** **must** be present,
112+
**"authenticate_as_identity_type"** __may__ be set and
113+
**"service_account_email"** __may__ be set in the **"workload"**
114+
section of the **"~/.config/gcloud/certificate_config.json"** configuration
115+
file.
115116

116117
### Expected Behavior
117118

118119
To support the usage of identity-bound access tokens, the auth libraries
119120
**must** follow the steps below when sending requests to Google APIs:
120121

121-
1. Connect to the mTLS endpoint of the [STS API][3] using the workload
122-
credentials provisioned as described in [Mutual Authentication Using
123-
Workload Credentials][2]. This endpoint **must** be
124-
`sts.mtls.googleapis.com`.
125-
1. Send an HTTP request to STS’s [ExchangeToken][5] method requesting an
126-
identity-bound token using the information in the
127-
**"workload_identity_provider"** field in the
128-
**"~/.config/gcloud/certificate_config.json"** configuration file. The
129-
scope of the requested token **must** be
130-
`https://www.googleapis.com/auth/iam`.
131-
1. Connect to the mTLS endpoint of the [IAM Credentials Service API][4] using
132-
the workload credentials provisioned as described in [Mutual Authentication
133-
Using Workload Credentials][2]. This endpoint **must** be
134-
`iamcredentials.mtls.googleapis.com`.
135-
1. If **"authenticate_as_identity_type"** is set to `gsa`, send an HTTP
136-
request to the IAM Credentials Service’s [GenerateAccessToken][6] method
137-
requesting an identity bound token asserting the service account email in
138-
the **"service_account_email"** field in the
139-
**"~/.config/gcloud/certificate_config.json"** configuration file. The
140-
scope of this token **must** be the same scope defined by the user for
141-
accessing the requested Google API.
142-
1. Attach the returned token in Step 4 to the request. Note that this request
143-
**must** be sent over an mTLS channel using the same workload credentials
144-
in Step 1.
122+
1. Connect to the mTLS endpoint of the [STS API][3] using the workload
123+
credentials provisioned as described in [Mutual Authentication Using
124+
Workload Credentials][2]. This endpoint **must** be
125+
`sts.mtls.googleapis.com`.
126+
127+
1. Send an HTTP request to STS’s [ExchangeToken][5] method requesting an
128+
identity-bound token using the information in the
129+
**"workload_identity_provider"** field in the
130+
**"~/.config/gcloud/certificate_config.json"** configuration file. The
131+
scope of the requested token **must** be
132+
`https://www.googleapis.com/auth/iam`.
133+
134+
1. Connect to the mTLS endpoint of the [IAM Credentials Service API][4] using
135+
the workload credentials provisioned as described in [Mutual Authentication
136+
Using Workload Credentials][2]. This endpoint **must** be
137+
`iamcredentials.mtls.googleapis.com`.
138+
139+
1. If **"authenticate_as_identity_type"** is set to `gsa`, send an HTTP
140+
request to the IAM Credentials Service’s [GenerateAccessToken][6] method
141+
requesting an identity bound token asserting the service account email in
142+
the **"service_account_email"** field in the
143+
**"~/.config/gcloud/certificate_config.json"** configuration file. The
144+
scope of this token **must** be the same scope defined by the user for
145+
accessing the requested Google API.
146+
147+
1. Attach the returned token in Step 4 to the request. Note that this request
148+
**must** be sent over an mTLS channel using the same workload credentials
149+
in Step 1.
145150

146151
<!-- prettier-ignore-start -->
147152
[0]: https://google.aip.dev/auth/4110

0 commit comments

Comments
 (0)