Skip to content

Commit bd6c4b4

Browse files
theodorehu95theodorehu95
authored
Update AIP-4115 with mTLS token binding flow (#1022)
1 parent d7a692f commit bd6c4b4

1 file changed

Lines changed: 86 additions & 86 deletions

File tree

‎aip/auth/4115.md‎

Lines changed: 86 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -5,124 +5,124 @@ state: approved
55
created: 2020-08-13
66
---
77

8-
# Default Credentials From Google Virtual Machines
8+
# Default Credentials For Google Cloud Virtual Environments
99

10-
If the client runs on Google virtual machine instance such as [Google App
11-
Engine][0] or [Compute Engine][1], the auth library **may** obtain the identity
12-
token that is associated with the instance, and use the identity token as the
13-
credential to access Google APIs. By using the instance identity, the users no
14-
longer need to config their credentials explicitly.
10+
If the client runs on Google cloud virtual environments such as [Google Compute Engine (GCE)][0],
11+
[Serverless][1], or [Google Kubernetes Engine (GKE)][2], the auth library **may** leverage
12+
Google’s default mutual TLS (mTLS) credentials and obtain bound tokens for the instance.
13+
The auth library **may** use the default mTLS credentials and bound tokens to access Google APIs.
1514

16-
**Note:** Because this AIP describes guidance and requirements in a
17-
language-neutral way, it uses generic terminology which may be imprecise or
18-
inappropriate in certain languages or environments.
15+
mTLS authentication enables authentication of both client and server identities in a TLS handshake.
16+
Applications running in Google virtual environments can authenticate to Google APIs using X.509
17+
SPIFFE Verifiable Identity Documents (SVIDs). These SVIDs are X.509 certificates that contain SPIFFE
18+
IDs specifying the identity of the certificate owner.
1919

20-
## Guidance
21-
22-
This section describes the general guidance of supporting default credentials
23-
from Google virtual machine environments.
24-
25-
### Application Default Credentials
20+
Bound tokens are access tokens that are bound to some property of the credentials used to establish
21+
the mTLS connection. The advantage of bound tokens is that they can be used over secure channels
22+
established via mTLS credentials with the correct binding information, when appropriate access
23+
policies have been put in place. Therefore, using bound tokens is more secure than bearer tokens,
24+
which can be stolen and adversarially replayed.
2625

27-
Supporting the default credentials from Google virtual machines is considered as
28-
a part of the [Application Default Credential][2]. To understand the overall
29-
credential flow, please read [AIP-4110][2].
26+
This AIP describes the flow of:
3027

31-
### Google Virtual Machine Environments
28+
1. Retrieving a configuration through a metadata server (MDS) endpoint. The configuration specifies
29+
how to access Google’s default mTLS credentials.
30+
2. Requesting bound tokens.
3231

33-
There are typically two types of Google virtual machine environments where the
34-
auth library should obtain the identity token based on the environment type:
32+
**Note:** Because this AIP describes guidance and requirements in a language-neutral way, it uses
33+
generic terminology which may be imprecise or inappropriate in certain languages or environments.
3534

36-
- Google App Engine Standard 1.0 (aka 1st generation)
37-
- Compute Engine
38-
- GCE equivalent runtimes
39-
- Google App Engine Standard 2.0+
40-
- Google App Engine Flex
41-
- Google Cloud Functions
42-
- Cloud Run
43-
- Workload Identity on Google Kubernetes Engine
44-
45-
The auth library **should** depend on the [Google App Engine SDK][3] or well
46-
defined GAE environment variables to detect if the application is running within
47-
the 1st generation Google App Engine environment.
35+
## Guidance
4836

49-
To detect if the application is running on Compute Engine or an equivalent runtime,
50-
the auth library **should** depend on the [Metadata Service Library][4].
37+
### Access Default mTLS Credentials
5138

52-
### Compute Engine or Equivalent Runtime
39+
**Note:** Before trying to use Google’s default mTLS credentials, the client **must** first check if the remote
40+
Google API endpoint supports mTLS. If the remote endpoint does NOT support mTLS, the client **should**
41+
connect to the endpoint using TLS. How to check if an endpoint supports mTLS is out of the scope of this
42+
AIP. If the remote endpoint does support mTLS, the client **should** try to connect using mTLS first
43+
before falling back to TLS. How to find the remote API’s mTLS endpoint is out of the scope of this AIP.
44+
If users enabled [Device Certificate Authentication (DCA)](4), the client **should** give priority to DCA
45+
as mTLS credentials.
5346

54-
If the application runs on a Compute Engine instance (or equivalent runtime),
55-
the auth library can request the following URL to get an access token associated
56-
with instance:
47+
To leverage Google’s default mTLS credentials, the client **should** retrieve configurations from
48+
MDS. The MDS in all virtual environments (GCE, Serverless, and GKE) exposes an HTTP endpoint that
49+
serves a configuration that specifies how to access Google's default mTLS credentials. This endpoint
50+
is called the mTLS configuration endpoint.
5751

52+
The URL of the MDS's mTLS configuration endpoint is:
5853
```
59-
http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token
54+
http://metadata.google.internal/computeMetadata/v1/googleAutoMtlsConfiguration
6055
```
6156

62-
In response, the auth library will usually receive a token in the following JSON
63-
format:
57+
The request to the MDS's mTLS configuration endpoint **should** be an HTTP GET request without any
58+
parameter or payload.
6459

65-
```json
66-
{
67-
"access_token":"YOUR_ACCESS_TOKEN",
68-
"expires_in":3599,
69-
"token_type":"Bearer"
70-
}
71-
```
60+
The response from the MDS's mTLS configuration endpoint **should** contain the following
61+
information:
7262

73-
#### Scopes
74-
Access tokens obtained from the metadata server contain the scopes specified at instance creation.
75-
For example, if an instance is granted only the
76-
https://www.googleapis.com/auth/storage-full scope for Cloud Storage, then the tokens obtained
77-
from the instance's metadata server have only the `storage-full` scope.
63+
* The **Secure Session Agent** address: the client doesn’t have direct access to mTLS credentials.
64+
The Secure Session Agent manages default mTLS credentials. The client can only use mTLS
65+
credentials through the Secure Session Agent. The address can be an IP:port address or a file path
66+
representing a Unix Domain Socket (UDS).
7867

79-
When running on GCE, the metadata server ignores requests for custom scopes.
80-
On GCE equivalent runtimes, clients can request a different set of scopes to the metadata server
81-
using the `scopes` url parameter, e.g.:
68+
The client **must** follow the steps below to access Google’s default mTLS credentials.
8269

83-
```
84-
http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token?scopes=comma-separated-list-of-scopes
85-
```
70+
1. Check if the remote endpoint supports mTLS.
71+
* If yes, go to step (2).
72+
* If not, go to step (3).
73+
2. Send a request to the MDS's mTLS configuration endpoint. If the request is successful and the
74+
response contains a Secure Session Agent address, use the address to access Google's default mTLS
75+
credentials, and go to step (4). If the request fails or the response contains an empty address,
76+
go to step (3).
77+
3. Fall back to TLS [END].
78+
4. Configure the TLS library to use the Secure Session Agent ([example][3]) for client authentication
79+
during the mTLS handshake.
8680

87-
The auth library **should** allow the caller to optionally specify a list of custom scopes,
88-
and add the `scopes` parameter to the request when needed.
89-
Depending on the runtime environment, the request for custom scopes will be transparently
90-
ignored by the server (GCE) or fulfilled (GCE equivalent).
81+
### Request Bound Tokens
9182

92-
### Google App Engine Standard 1.0 Runtime
83+
To access Google APIs with bound tokens, the client **should** request tokens from MDS. The MDS in
84+
all virtual environments (GCE, Serverless, and GKE) exposes an HTTP endpoint that serves access tokens.
85+
This endpoint is called the access token endpoint.
9386

94-
If the application runs on a App Engine Standard 1st generation instance, the
95-
auth library **should** rely on the [Google App Engine SDK][3] to retrieve the
96-
access token. Here is [one example][5] in Go. Essentially the SDK relies on the
97-
underlying App Engine Identity service to generate the token.
87+
The URL of the MDS's access token endpoint is:
88+
```
89+
http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token
90+
```
9891

99-
Like GCE equivalent runtimes, the auth library can specify scopes when requesting the
100-
token in the App Engine Standard 1.0 runtime.
92+
The request to the MDS's access token endpoint **should** be an HTTP GET request. The request **may**
93+
have a “scopes” URL parameter with a list of comma-separated scopes. The auth library **should** allow
94+
the caller to optionally specify a list of custom scopes, and add the “scopes” parameter to the request
95+
when needed. Depending on the runtime environment, the request for custom scopes **may** be transparently
96+
ignored or fulfilled by the server.
10197

102-
Sample code of getting the access token in Go:
98+
The response from the MDS's access token endpoint **should** contain an access token in the following
99+
JSON format:
103100

104-
```go
105-
import "google.golang.org/appengine"
106-
...
107-
token, exp, err := appengine.AccessToken(context, scopes...)
108-
...
101+
```json
102+
{
103+
"access_token": "YOUR_ACCESS_TOKEN",
104+
"expires_in": 3599,
105+
"token_type": "Bearer"
106+
}
109107
```
110108

111-
### Token Expiration
109+
The client **must** follow the steps below to request new access tokens for Google APIs if existing
110+
tokens expire.
112111

113-
The access tokens expire after a short period of time. The auth library **must**
114-
get a new token if the existing token expires.
112+
1. Send an HTTP request to the MDS access token endpoint, retrieve the access token from the response
113+
and go to step (2).
114+
2. Attach the token from step (1) to the request to Google APIs.
115115

116116
## Changelog
117117

118118
- **2020-12-14**: Replace note on scopes with more detailed discussion.
119119
- **2021-07-13**: Clarify GCE equivalent runtimes
120+
- **2023-02-16**: Add mTLS configuration endpoint and unify the token binding flow.
120121

121122
<!-- prettier-ignore-start -->
122-
[0]: https://cloud.google.com/appengine
123-
[1]: https://cloud.google.com/compute
124-
[2]: ./4110
125-
[3]: https://cloud.google.com/appengine/downloads
126-
[4]: https://developers.google.com/analytics/devguides/reporting/metadata/v3/libraries
127-
[5]: https://godoc.org/google.golang.org/appengine#AccessToken
123+
[0]: https://cloud.google.com/compute
124+
[1]: https://cloud.google.com/serverless
125+
[2]: https://cloud.google.com/kubernetes-engine
126+
[3]: https://github.com/google/s2a-go/tree/main/example
127+
[4]: https://google.aip.dev/auth/4114
128128
<!-- prettier-ignore-end -->

0 commit comments

Comments
 (0)