| Method | Path | Description |
|---|---|---|
GET |
/.well-known/oauth-authorization-server |
Advertises the token endpoint, supported grants, and JWKS URI. |
GET |
/jwks |
Serves STS signing public keys. |
POST |
/token |
Accepts form-encoded requests for an access token for one target. |
STS supports only token exchange. The discovery document advertises:
{
"grant_types_supported": [
"urn:ietf:params:oauth:grant-type:token-exchange"
]
}STS accepts subject tokens from two kinds of issuers:
- Internal issuers: the Kubernetes issuers that STS trusts for client authentication.
- External issuers: issuers configured in
authorizationServer.externalIssuers.
Token exchange requires a projected Kubernetes service account token as client_assertion.
STS uses its issuer, namespace, and service account name to find the registered client.
Nais Application and NaisJob workloads get a token automatically at NAIS_SERVICE_ACCOUNT_TOKEN_PATH.
For raw Kubernetes workloads, mount a projected token:
apiVersion: v1
kind: ServiceAccount
metadata:
name: my-workload
namespace: namespace1
---
apiVersion: v1
kind: Pod
metadata:
name: my-workload
namespace: namespace1
spec:
serviceAccountName: my-workload
containers:
- name: my-workload
image: my-image
volumeMounts:
- name: nais-token
mountPath: /var/run/secrets/nais.io
readOnly: true
volumes:
- name: nais-token
projected:
sources:
- serviceAccountToken:
path: token
audience: nais
expirationSeconds: 600audiencemust matchauthorizationServer.expectedAudience(normallynais).- Keep
expirationSecondswithinauthorizationServer.maxClientAuthTokenLifetime(default1h).
For reference, a decoded projected service account token can contain:
{
"iss": "https://issuer.example.com/env1",
"sub": "system:serviceaccount:namespace1:my-workload",
"aud": ["nais"],
"iat": 1790000000,
"exp": 1790000600,
"kubernetes.io": {
"namespace": "namespace1",
"serviceaccount": { "name": "my-workload" }
}
}The timestamps are illustrative; Kubernetes sets them when it issues the token.
Send a subject JWT from an accepted issuer, or an STS access token from a previous token exchange.
Send exactly one target client ID in audience.
The target's authorization policy must allow the requesting client; it supplies the roles in the issued token.
STS verifies the subject token's signature, issuer, subject, and timestamps.
To get a token without user context, send the client's own service account token as both client_assertion and subject_token.
When the subject token is from STS, its aud must contain the requesting client ID.
In this example, subject_token is a signed JWT from the accepted issuer https://identity.example.com.
Its decoded claims appear beside the issued token below.
POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=<projected-service-account-token>&
audience=env1%3Anamespace1%3Atarget&
subject_token=<subject-JWT>&
subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt&
requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_tokenThe body has line breaks for readability. Send the encoded parameters on one line.
| Field | Description | Example value |
|---|---|---|
grant_type |
Token exchange grant. | urn:ietf:params:oauth:grant-type:token-exchange |
client_assertion_type |
JWT bearer assertion type. | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
client_assertion |
The projected service account token. | <projected-service-account-token> |
audience |
One target client ID whose policy lists the requesting client as a consumer. | env1:namespace1:target |
subject_token |
JWT to exchange from an accepted issuer, or a previous STS token exchange. | <subject-JWT> |
subject_token_type |
Type of the incoming subject token. | urn:ietf:params:oauth:token-type:jwt |
requested_token_type |
Type of the requested token. | urn:ietf:params:oauth:token-type:access_token |
{
"access_token": "<signed-STS-JWT>",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 900
}In this example, STS configures identity as the alias for https://identity.example.com.
The decoded tokens compare as follows (timestamps and token IDs are illustrative):
| Subject token | Exchanged token |
|---|---|
| |
STS starts with the subject token's claims, then sets these values in the exchanged token:
| Claim | Value in exchanged token | Changes compared to subject token claim |
|---|---|---|
iss |
STS issuer. | Replaces the subject token's issuer. |
aud |
Target client ID from the request's audience. |
Replaces the subject token's audience. |
client_id |
Requesting client ID. | Added, or replaces an existing value. |
jti |
New token ID. | Added, or replaces an existing value. |
iat, nbf, exp |
New validity times. | Added, or replace existing values. |
urn:nais:roles |
Roles from the target's policy for the requesting client. | Added, or replaces an existing value. |
urn:nais:idp |
Issuer URL of the first subject token exchanged. | Added on the first exchange; retained on later STS exchanges. |
urn:nais:idp_alias |
Short, stable alias for that issuer. | Added on the first exchange; retained on later STS exchanges. |
urn:nais:call_chain |
Client IDs in exchange order, oldest first. | Added; appends the requesting client ID to a prior STS call chain. |
The sub claim and other claims, such as department and act in the example, keep their values.
Workloads can use urn:nais:idp_alias to distinguish original issuers without depending on their exact URLs.
urn:nais:call_chain lists the client IDs that performed each exchange, oldest first.
STS preserves the chain from STS-issued subject tokens as history, not as authorization policy input. It ignores any urn:nais:call_chain in external subject tokens. A malformed chain in an STS-issued subject token starts a new chain.
STS does not add or extend act; RFC 8693 reserves it for delegation with an actor_token, which STS does not support.
Only client_id and urn:nais:call_chain identify the clients that requested tokens.
STS authenticated each of these clients and checked the target's authorization policy for it.
Use them to authorize the caller.
The sub claim, urn:nais:idp, urn:nais:idp_alias, and other claims copied from the subject token describe the subject token.
STS verifies that a trusted issuer signed that token, but not that the token belongs to the requesting client.
Do not use these claims to identify or authorize the caller.
urn:nais:idp_alias is the environment's clientAuthIssuerAlias (default kubernetes)
when the original subject token came from an internal issuer.
urn:nais:idp then contains that Kubernetes issuer.
Client env1:namespace1:target uses the exchanged token above as its subject_token to request a token for env1:namespace1:next-target.
The requesting client is appended to the previous urn:nais:call_chain array:
| Subject token | Exchanged token |
|---|---|
| |
Error responses follow RFC 6749, section 5.2.
{
"error": "invalid_client",
"error_description": "client assertion is invalid: token has expired"
}The description names problems in the caller's own input, such as an untrusted issuer or a wrong audience. It does not include internal details. STS logs the full cause.
error |
Cause |
|---|---|
invalid_request |
A request parameter, such as the subject token, is missing or invalid. |
unsupported_grant_type |
STS does not support the grant type. |
invalid_client |
The client assertion is invalid, or the client is unknown. |
invalid_target |
The target is invalid, or the client is not authorized for it. |
server_error |
An internal error occurred. The status is 500. |
Malformed requests use status 400, except for an unsupported content type.
A body that is not application/x-www-form-urlencoded returns 415.
An oversized body returns 400 with invalid_request and the description invalid request body.