# TokenX reference

## Spec

See the [📚 Nais application reference](/workloads/application/reference/spec.md#tokenx).

## Runtime variables & credentials

Your application will automatically be injected with environment variables at runtime.

| Environment Variable | Description |
| --- | --- |
| `NAIS_TOKEN_EXCHANGE_ENDPOINT` | Used to [🎯 consume an API on behalf of an end-user](/auth/tokenx/how-to/consume.md). |
| `NAIS_TOKEN_INTROSPECTION_ENDPOINT` | Used to [🎯 secure your API with TokenX](/auth/tokenx/how-to/secure.md). |

For further details about these endpoints, see the [OpenAPI specification](/auth/reference.md#openapi-specification).

### Variables for manually validating tokens

These variables are optional and should only be used for [manually validating tokens](#manual-token-validation) when 🎯 [securing your API with TokenX](/auth/tokenx/how-to/secure.md).

| Name | Description |
| :--- | :--- |
| `TOKEN_X_CLIENT_ID` | [Client ID](/auth/explanations.md#client-id) that uniquely identifies the application in TokenX. |
| `TOKEN_X_WELL_KNOWN_URL` | The well-known URL for the [metadata discovery document](/auth/explanations.md#well-known-url-metadata-document). |
| `TOKEN_X_ISSUER` | `issuer` from the [metadata discovery document](/auth/explanations.md#issuer). |
| `TOKEN_X_JWKS_URI` | `jwks_uri` from the [metadata discovery document](/auth/explanations.md#jwks-endpoint-public-keys). |

`TOKEN_X_WELL_KNOWN_URL` is optional if you're using `TOKEN_X_ISSUER` and `TOKEN_X_JWKS_URI` directly.

## Claims

In addition to the [standard claims](/auth/explanations.md#claims-validation), tokens from TokenX include the following claims:

| Claim | Description |
| :--- | :--- |
| `idp` | The original [`issuer`](/auth/explanations.md#issuer) of the subject token |
| `client_id` | The consumer's [`client_id`](/auth/explanations.md#client-id). Follows the naming scheme `<cluster>:<namespace>:<appname>` |

Other claims such as `pid` and `acr` are copied verbatim from the [original token issued by ID-porten](/auth/idporten/reference.md#claims).

### Claim Mappings

Some claims are mapped to a different value for legacy/compatibility reasons.

The table below shows the claim mappings:

| Claim | Original Value | Mapped Value |
| :--- | :--- | :--- |
| `acr` | `idporten-loa-substantial` | `Level3` |
| `acr` | `idporten-loa-high` | `Level4` |

The mappings will be removed at some point in the future.
If you're using the `acr` claim in any way, check for both the original and mapped values.

## Manual token validation

While we recommend using [the `NAIS_TOKEN_INTROSPECTION_ENDPOINT` endpoint for validating tokens](#runtime-variables-credentials),
you can alternatively validate tokens natively within your application.

Manual validation can be useful if you want to avoid the small overhead of an additional network call
and rather depend on a native library within your ecosystem of choice.
You should be familiar with the [auth concepts](/auth/explanations.md).

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

> **Libraries for token validation**
> We recommend using a library in your language of choice to handle all the validation steps described below.
> Here are some recommended libraries:

> - [navikt/oasis](https://github.com/navikt/oasis) (JavaScript)
> - [navikt/token-support](https://github.com/navikt/token-support) (Java / Kotlin)

> Validation is also supported by many popular frameworks:

> - [Ktor](https://ktor.io/docs/server-jwt.html) (Kotlin)
> - [Spring Security](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html) (Java / Kotlin)

To validate the token, start by validating the [signature and standard time-related claims](/auth/explanations.md#token-validation).

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](/auth/explanations.md#well-known-url-metadata-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 the value found in the `TOKEN_X_CLIENT_ID` environment variable.

**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.

**Claims validation**

[Other claims](#claims) may be present in the token.
Your application should validate these other claims according to your own requirements.