Skip to content

Commit 0c28e69

Browse files
committed
address review comments
1 parent 152e83d commit 0c28e69

File tree

1 file changed

+13
-9
lines changed

1 file changed

+13
-9
lines changed

content/en/docs/reference/access-authn-authz/service-accounts-admin.md

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -163,22 +163,22 @@ Hence `kubectl get tokenreview` is not a valid command.
163163
#### Schema for service account private claims
164164

165165
The schema for the Kubernetes-specific claims within JWT tokens is not currently documented,
166-
however the relevant code area can be found in [the serviceaccount package]() in the Kubernetes codebase.
166+
however the relevant code area can be found in
167+
[the serviceaccount package](https://github.com/kubernetes/kubernetes/blob/d8919343526597e0788a1efe133c70d9a0c07f69/pkg/serviceaccount/claims.go#L56-L68)
168+
in the Kubernetes codebase.
167169

168-
[the serviceaccount package]: https://github.com/kubernetes/kubernetes/blob/d8919343526597e0788a1efe133c70d9a0c07f69/pkg/serviceaccount/claims.go#L56-L68
169-
170-
You can inspect a JWT using standard JWT decoding tools, an example of a JWT for the
170+
You can inspect a JWT using standard JWT decoding tool. Below is an example of a JWT for the
171171
`my-serviceaccount` ServiceAccount, bound to a Pod object named `my-pod` which is scheduled
172172
to the Node `my-node`, in the `default` namespace:
173173

174174
```json
175175
{
176176
"aud": [
177-
"https://kubernetes.default.svc.cluster.local"
177+
"https://my-audience.example.com"
178178
],
179179
"exp": 1729605240,
180180
"iat": 1729601640,
181-
"iss": "https://kubernetes.default.svc.cluster.local",
181+
"iss": "https://my-cluster.example.com",
182182
"jti": "aed34954-b33a-4142-b1ec-389d6bbb4936",
183183
"kubernetes.io": {
184184
"namespace": "default",
@@ -201,24 +201,28 @@ to the Node `my-node`, in the `default` namespace:
201201
```
202202

203203
{{< note >}}
204+
The `aud` and `iss` fields in this JWT may differ between different Kubernetes clusters depending
205+
on your configuration.
206+
204207
The presence of both the `pod` and `node` claim implies that this token is bound
205-
to a *Pod* object. When verifying Pod bound ServiceAccount tokens, the apiserver **does not**
208+
to a *Pod* object. When verifying Pod bound ServiceAccount tokens, the API server **does not**
206209
verify the existence of the referenced Node object.
207210
{{< /note >}}
208211

209212
Services that run outside of Kubernetes and want to perform offline validation of JWTs may
210213
use this schema, along with a compliant JWT validator configured with OpenID Discovery information
211-
from the kube-apiserver, to verify presented JWTs without requiring use of the TokenReview API.
214+
from the API server, to verify presented JWTs without requiring use of the TokenReview API.
212215

213216
Services that verify JWTs in this way **do not verify** the claims embedded in the JWT token to be
214217
current and still valid.
215218
This means if the token is bound to an object, and that object no longer exists, the token will still
216-
be considered valid (until the configured token expiry).
219+
be considered valid (until the configured token expires).
217220

218221
Clients that require assurance that a token's bound claims are still valid **MUST** use the TokenReview
219222
API to present the token to the `kube-apiserver` for it to verify and expand the embedded claims, using
220223
similar steps to the [Verifying and inspecting private claims](#verifying-and-inspecting-private-claims)
221224
section above, but with a [supported client library](/docs/reference/using-api/client-libraries/).
225+
For more information on JWTs and their structure, see the [JSON Web Token RFC](https://datatracker.ietf.org/doc/html/rfc7519).
222226

223227
## Bound service account token volume mechanism {#bound-service-account-token-volume}
224228

0 commit comments

Comments
 (0)