Consume internal API on behalf of a citizen¶

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

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:

spec:
  tokenx:
    enabled: true

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

Exchange token¶

To exchange a token, you can either:

• exchange tokens with Texas, or
• exchange tokens manually in your application

Exchange tokens with Texas¶

Send a HTTP POST request to the endpoint found in the NAIS_TOKEN_EXCHANGE_ENDPOINT environment variable. The request must have a Content-Type header set to either:

• application/json or
• application/x-www-form-urlencoded

The body of the request should contain the following parameters:

POST ${NAIS_TOKEN_EXCHANGE_ENDPOINT} HTTP/1.1
Content-Type: application/json

{
    "identity_provider": "tokenx",
    "target": "<cluster>:<namespace>:<other-app-name>",
    "user_token": "eyJra..."
}

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

identity_provider=tokenx&
target=<cluster>:<namespace>:<other-app-name>&
user_token=eyJra...

{
    "access_token": "eyJra...",
    "expires_in": 3599,
    "token_type": "Bearer"
}

Your application does not need to validate this token.

Tokens are cached by default with regards to the expires_in field. To forcibly fetch a new token, set the skip_cache=true parameter in the request.

Exchange tokens manually¶

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:

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

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

{
  "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:

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

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:

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

Your application does not need to validate this token.

Error response¶

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

{
  "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...