Repository navigation
Commit 9a905c4
authored
feat(auth): support GKE agent identity credential bundle for bound tokens and mTLS (#14595)
## Why
GKE delivers agent identity credentials (Pod Certificates) as a single
combined PEM file, holding the certificate chain and a PKCS#8 private
key, at:
```
/var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem
```
The feature branch already handles Cloud Run, where a certificate config
points into the well-known directory. On GKE there is no certificate
config, so neither the transport nor the token side found the
certificate. This is the Java counterpart of
googleapis/google-cloud-python#18559. Background:
go/gke-security-identity/features/agent_identity_diy.md and
go/sdk-mds-bound-token.
## What changes
When **no certificate configuration exists**
(`GOOGLE_API_CERTIFICATE_CONFIG` is unset and there is no
`~/.config/gcloud/certificate_config.json`), a readable, non-empty
bundle now:
- **Transport:** turns on mTLS automatically.
- `MtlsUtils.getWorkloadCertPath` / `useMtlsClientCertificate` return
the bundle path.
- `DefaultMtlsProviderFactory.create()` builds its keystore from the
bundle via a new package-private `X509Provider.createForTransport()`.
- Every GAX transport (`EndpointContext`, gRPC, HTTP/JSON) goes through
that factory.
- **Tokens:** `AgentIdentityUtils` resolves the same bundle, so
`ComputeEngineCredentials` requests tokens bound to the certificate the
transport presents.
- With `GOOGLE_API_USE_CLIENT_CERTIFICATE=true`, the bundle takes
precedence over the Cloud Run well-known files for the same reason.
**Kept unchanged:**
- `GOOGLE_API_USE_CLIENT_CERTIFICATE=false` and
`GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false` still opt out.
- An explicit or default certificate config (including ECP) always beats
the bundle, on both sides.
- **The bundle is never polled for.** GKE writes it before the container
starts, and polling for a missing file would delay every workload that
isn't an agent.
- **Workload identity federation X.509 is unchanged.** The public
`X509Provider` constructors don't fall back to the bundle. Only the
transport factory does.
- If the bundle disappears during the read (rotation), the transport
reports `CertificateSourceUnavailableException` rather than a generic
`IOException`. If it's briefly missing after a credential was cached,
the token side falls back to the cached credential, but only while the
bundle is still allowed (no certificate configuration has appeared).
**New API:** a public static
`MtlsUtils.hasCertificateConfiguration(...)` on an `@InternalApi` class.
This is additive only.
## Differences from Python (intentional)
- Python also checks
`CLOUDSDK_CONTEXT_AWARE_CERTIFICATE_CONFIG_FILE_PATH`. Java has no
equivalent env var.
- Python temporarily keeps default **ID tokens** unbound on Cloud Run
(when `GOOGLE_API_CERTIFICATE_CONFIG` is set). That gate is temporary
and Python-only, so it isn't copied here. On GKE, both libraries bind ID
tokens by default. #14559 adds the per-target `DISABLE_BOUND_ID_TOKEN`
opt-out.
## Related
- #14556 (HTTP/JSON mTLS fix, merged) enables mTLS over HTTP/JSON
transports.
- #14559 (`DISABLE_BOUND_ID_TOKEN`) is the per-target ID-token opt-out.
## Tests
### Unit tests
- `MtlsUtilsTest`:
- bundle present, absent, a directory, or empty;
- `USE_CLIENT_CERTIFICATE=false`;
- a default config without a workload section (ECP) blocks the bundle;
- an explicit config takes precedence;
- `hasCertificateConfiguration` / `getGkeCredentialBundlePath`.
- `X509ProviderTest`:
- transport provider with cert-first and key-first bundles;
- an explicit config, or an override path, takes precedence;
- unavailable when there is no bundle;
- the public constructor ignores the bundle (WIF).
- `AgentIdentityUtilsTest`:
- implicit discovery with zero sleeps;
- the cached credential stays bound;
- opt-outs, a default gcloud config, and a non-agent cert all leave the
token unbound;
- an empty or absent bundle returns null without polling;
- explicit true finds the bundle, never polls for it, and prefers it
over the Cloud Run files;
- fallback to the cache after the bundle is deleted, and no fallback
once a certificate config has appeared (implicit and explicit paths).
Full `oauth2_http` suite: 1089 tests, 0 failures. `fmt` is clean.
### Live test on GKE
- **Cluster:** a GKE cluster with agent identity enabled.
- **Pods:** the test pods get the agent identity credential bundle at
`/var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem`.
- **Image:** built from this PR's jars merged with #14556, which is
already on the base branch and is required for HTTP/JSON mTLS. It uses
ADC with default settings and no client options.
- **Details:** cluster setup, manifests and full logs are in the
internal links below.
**Checks:**
- **GCS over raw HTTP:** read through `storage.mtls.googleapis.com` with
the transport certificate. The same token on plain
`storage.googleapis.com` gets 401, which proves the token is bound.
- **GAX Resource Manager client:** `getProject` over gRPC and HTTP/JSON.
- **ID tokens:** sent to an agent-to-agent receiver pod. It accepts only
bound tokens over mTLS whose `cnf` matches the client certificate, and
only unbound tokens over plain HTTP.
| Scenario | Token | GAX resolved endpoint | GAX gRPC / HTTP-JSON | GCS
mTLS / plain | ID token mTLS / plain |
|---|---|---|---|---|---|
| Defaults | Bound; `cnf` = bundle leaf = transport cert |
`cloudresourcemanager.mtls.googleapis.com` | ✅ / ✅ | 200 / **401** |
**200** / 401 |
| `GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false` | Unbound | mTLS
endpoint | ✅ / ✅ | 200 / 200 | 401 / **200** |
| `GOOGLE_API_USE_CLIENT_CERTIFICATE=false` | Unbound | plain endpoint |
✅ / ✅ | 200 / 200 | 401 / **200** |
| `GOOGLE_API_USE_CLIENT_CERTIFICATE=true` | Bound (bundle) | mTLS
endpoint | ✅ / ✅ | 200 / **401** | **200** / 401 |
| Pod without agent identity | Unbound, no mTLS | plain endpoint |
authenticated / authenticated | — / authenticated | n/a |
**Timing:** the first token fetch took about 0.5–1s in every scenario. A
pod without the bundle has no polling delay.
**Internal links (Googlers only):**
[setup](https://paste.googleplex.com/5635555912712192) ·
[manifests](https://paste.googleplex.com/6258309762514944) ·
[harness](https://paste.googleplex.com/4882197073494016) ·
[build/run](https://paste.googleplex.com/5942061774274560) ·
[results](https://paste.googleplex.com/5072605959290880)
**Out of scope for this PR (tracked separately):**
- **Leaf-only keystore:** `X509Provider`'s keystore holds only the leaf
certificate, through google-http-client
`SecurityUtils.createMtlsKeyStore`. Google APIs over
`*.mtls.googleapis.com` are unaffected. Agent-to-agent mTLS against a
peer that trusts only the SPIFFE root fails unless the caller presents
the full chain.1 parent 103734a commit 9a905c4
8 files changed
Lines changed: 793 additions & 22 deletions
File tree
- google-auth-library-java/oauth2_http
- javatests/com/google/auth
- mtls
- oauth2
- java/com/google/auth
- mtls
- oauth2
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
40 | 40 | | |
41 | 41 | | |
42 | 42 | | |
43 | | - | |
44 | | - | |
45 | | - | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
46 | 47 | | |
47 | 48 | | |
48 | 49 | | |
| |||
53 | 54 | | |
54 | 55 | | |
55 | 56 | | |
56 | | - | |
| 57 | + | |
57 | 58 | | |
58 | 59 | | |
59 | 60 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
| 36 | + | |
36 | 37 | | |
37 | 38 | | |
38 | 39 | | |
| |||
58 | 59 | | |
59 | 60 | | |
60 | 61 | | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
61 | 73 | | |
62 | 74 | | |
63 | 75 | | |
64 | 76 | | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
65 | 134 | | |
66 | 135 | | |
67 | 136 | | |
| |||
89 | 158 | | |
90 | 159 | | |
91 | 160 | | |
92 | | - | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
93 | 165 | | |
94 | 166 | | |
95 | 167 | | |
96 | 168 | | |
97 | 169 | | |
98 | 170 | | |
99 | | - | |
100 | | - | |
101 | | - | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
102 | 175 | | |
103 | 176 | | |
104 | 177 | | |
| |||
175 | 248 | | |
176 | 249 | | |
177 | 250 | | |
| 251 | + | |
| 252 | + | |
| 253 | + | |
178 | 254 | | |
179 | 255 | | |
180 | | - | |
| 256 | + | |
| 257 | + | |
| 258 | + | |
181 | 259 | | |
182 | 260 | | |
183 | 261 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
38 | 38 | | |
39 | 39 | | |
40 | 40 | | |
| 41 | + | |
41 | 42 | | |
42 | 43 | | |
43 | 44 | | |
| |||
54 | 55 | | |
55 | 56 | | |
56 | 57 | | |
57 | | - | |
| 58 | + | |
| 59 | + | |
58 | 60 | | |
59 | 61 | | |
60 | 62 | | |
| |||
70 | 72 | | |
71 | 73 | | |
72 | 74 | | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
73 | 93 | | |
74 | 94 | | |
75 | 95 | | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
76 | 108 | | |
77 | 109 | | |
78 | 110 | | |
| |||
105 | 137 | | |
106 | 138 | | |
107 | 139 | | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
108 | 144 | | |
109 | 145 | | |
110 | 146 | | |
| |||
114 | 150 | | |
115 | 151 | | |
116 | 152 | | |
117 | | - | |
118 | | - | |
119 | | - | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
120 | 195 | | |
121 | 196 | | |
122 | 197 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
166 | 166 | | |
167 | 167 | | |
168 | 168 | | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
169 | 175 | | |
170 | 176 | | |
171 | 177 | | |
| |||
190 | 196 | | |
191 | 197 | | |
192 | 198 | | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
193 | 209 | | |
194 | 210 | | |
195 | 211 | | |
| |||
0 commit comments