Consume internal API on behalf of a citizen¶

This how-to guides you through the steps required to consume an API secured with TokenX:

Configure your application
Exchange token with TokenX
Consume the API using the token

Prerequisites¶

Your application receives requests with a citizen subject token in the Authorization header
- The subject token can either be from ID-porten or from TokenX itself
The API you're consuming has granted access to your application

Configure your application¶

Enable TokenX in your application:

app.yaml

spec:
  tokenx:
    enabled: true

Depending on how you communicate with the API you're consuming, configure the appropriate outbound access policies.

Exchange token¶

Create client assertion¶

To perform a token exchange, your application must authenticate itself. To do so, create a client assertion.

Sign the client assertion with your applications private key contained within the TOKEN_X_PRIVATE_JWK environment variable.

The assertion must contain the following claims:

Claim	Example Value	Description
`sub`	`dev-gcp:my-team:app-a`	The subject of the token. Set to the `TOKEN_X_CLIENT_ID` environment variable.
`iss`	`dev-gcp:my-team:app-a`	The issuer of the token. Set to the `TOKEN_X_CLIENT_ID` environment variable.
`aud`	`https://tokenx.dev-gcp.nav.cloud.nais.io/token`	The audience of the token. Set to the `TOKEN_X_TOKEN_ENDPOINT` environment variable.
`jti`	`83c580a6-b479-426d-876b-267aa9848e2f`	The JWT ID of the token. Used to uniquely identify a token. Set this to a UUID or similar.
`nbf`	`1597783152`	`nbf` stands for not before. Set to now.
`iat`	`1597783152`	`iat` stands for issued at. Set to now.
`exp`	`1597783182`	`exp` is the expiration time of the token. Between 1 and 120 seconds after now. Typically 30 seconds is fine.

Additionally, the headers of the assertion must contain the following parameters:

Parameter	Value	Description
`kid`	`93ad09a5-70bc-4858-bd26-5ff4a0c5f73f`	The key identifier of the key used to sign the assertion. This identifier is available in the JWK found in `TOKEN_X_PRIVATE_JWK`.
`typ`	`JWT`	Represents the type of this JWT. Set this to `JWT`.
`alg`	`RS256`	Represents the cryptographic algorithm used to secure the JWT. Set this to `RS256`.

Example Client Assertion Values

Header

{
  "kid": "93ad09a5-70bc-4858-bd26-5ff4a0c5f73f",
  "typ": "JWT",
  "alg": "RS256"
}

Payload

{
  "sub": "prod-gcp:namespace-gcp:gcp-app",
  "aud": "https://tokenx.dev-gcp.nav.cloud.nais.io/token",
  "nbf": 1592508050,
  "iss": "prod-gcp:namespace-gcp:gcp-app",
  "exp": 1592508171,
  "iat": 1592508050,
  "jti": "fd9717d3-6889-4b22-89b8-2626332abf14"
}

Create and perform exchange request¶

Now that you have a client assertion, we can use this to exchange the inbound token you received from your consumer.

The token request is an HTTP POST request. It must have the Content-Type header set to application/x-www-form-urlencoded

The body of the request should contain the following parameters:

Parameter	Value	Description
`grant_type`	`urn:ietf:params:oauth:grant-type:token-exchange`	Always `urn:ietf:params:oauth:grant-type:token-exchange`.
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	Always `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
`client_assertion`	`eyJraWQ...`	The client assertion. Token that authenticates your application. It should be unique and only used once.
`subject_token_type`	`urn:ietf:params:oauth:token-type:jwt`	Always `urn:ietf:params:oauth:token-type:jwt`.
`subject_token`	`eyJraWQ...`	The citizen's subject token from the inbound request, either from ID-porten or TokenX. Token that should be exchanged.
`audience`	`<cluster>:<namespace>:<appname>`	The identifier for the target application. Intended audience or recipient of the new token.

Send the request to the token_endpoint, i.e. the URL found in the TOKEN_X_TOKEN_ENDPOINT environment variable.

Example request

POST ${TOKEN_X_TOKEN_ENDPOINT} HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=eY...............&
subject_token_type=urn:ietf:params:oauth:token-type:jwt&
subject_token=eY...............&
audience=prod-gcp:namespace1:app1

Success response¶

TokenX responds with a JSON object that contains the new access token:

Success response body

{
  "access_token" : "eyJraWQiOi..............",
  "expires_in" : 899,
  ...
}

Your application does not need to validate this token.

Cache your tokens

The expires_in field in the response indicates the lifetime of the token in seconds.

Use this field to cache and reuse the token to minimize network latency impact.

A safe cache key for this flow is key = sha256($subject_token + $audience).

Error response¶

If the exchange request is invalid, you will receive a structured error as specified in RFC 8693, Section 2.2.2:

Error response body

{
  "error_description" : "token exchange audience <some-audience> is invalid",
  "error" : "invalid_request"
}

Consume API¶

Once you have acquired a new token, you can finally consume the target API by using the token as a Bearer token:

GET /resource HTTP/1.1

Host: api.example.com
Authorization: Bearer eyJraWQ...