Secure your API with TokenX¶

This how-to guides you through the steps required to secure your API using TokenX:

Grant access to consumers¶

Specify inbound access policies to authorize your consumers:

spec:
  tokenx:
    enabled: true
  accessPolicy:
    inbound:
      rules:
        - application: app-1  # same namespace and cluster

        - application: app-2  # same cluster
          namespace: team-a

        - application: app-3
          namespace: team-b
          cluster: prod-gcp

The above configuration authorizes the following applications:

• application app-1 running in the same namespace and same cluster as your application
• application app-2 running in the namespace team-a in the same cluster
• application app-3 running in the namespace team-b in the cluster prod-gcp

Now that you have granted access to your consumers, they can now exchange tokens for new tokens that target your application. You will need to validate these tokens in your application.

Validate tokens¶

Verify incoming requests from consumers by validating the JWT Bearer token in the Authorization header.

To validate a token, you can either:

• validate tokens with Texas, or
• validate JWTs manually in your application

Validate with Texas¶

Send a HTTP POST request to the endpoint found in the NAIS_TOKEN_INTROSPECTION_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_INTROSPECTION_ENDPOINT} HTTP/1.1
Content-Type: application/json

{
    "identity_provider": "tokenx",
    "token": "eyJra..."
}

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

identity_provider=tokenx&
token=eyJra...

The response is always a HTTP 200 OK response with a JSON body.

It always contains the active field, which is a boolean value that indicates whether the token is valid or not.

Success response¶

If the token is valid, the response will additionally contain all the token's claims:

{
    "active": true,
    "exp": 1730980893,
    "iat": 1730977293,
    ...
}

Claims are copied verbatim from the token to the response.

Error response¶

If the token is invalid, the only additional field in the response is the error field:

{
    "active": false,
    "error": "token is expired"
}

The error field contains a human-readable error message that describes why the token is invalid.

Validate JWT manually¶

Validating a JWT involves a number of steps. These steps are outlined and described below in a language- and framework-agnostic way.

To validate the token, start by validating the signature and standard time-related claims.

Additionally, perform the following validations:

Issuer Validation

Validate that the iss claim has a value that is equal to either:

1. the TOKEN_X_ISSUER environment variable, or
2. the issuer property from the metadata discovery document. The document is found at the endpoint pointed to by the TOKEN_X_WELL_KNOWN_URL environment variable.

Audience Validation

Validate that the aud claim is equal to TOKEN_X_CLIENT_ID.

Signature Validation

Validate that the token is signed with a public key published at the JWKS endpoint. This endpoint URI can be found in one of two ways:

1. the TOKEN_X_JWKS_URI environment variable, or
2. the jwks_uri property from the metadata discovery document. The document is found at the endpoint pointed to by the TOKEN_X_WELL_KNOWN_URL environment variable.

Other Token Claims

Other claims may be present in the token. Validation of these claims is optional.

See the TokenX claims reference for details.