TokenX reference

Spec

See the Nais application reference.

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.
NAIS_TOKEN_INTROSPECTION_ENDPOINT	Used to secure your API with TokenX.

For further details about these endpoints, see the OpenAPI specification.

Variables for manually validating tokens

These variables are optional and should only be used for manually validating tokens when securing your API with TokenX.

Name	Description
TOKEN_X_CLIENT_ID	Client ID that uniquely identifies the application in TokenX.
TOKEN_X_WELL_KNOWN_URL	The well-known URL for the metadata discovery document.
TOKEN_X_ISSUER	issuer from the metadata discovery document.
TOKEN_X_JWKS_URI	jwks_uri from the metadata discovery document.

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, tokens from TokenX include the following claims:

Claim	Description
idp	The original issuer of the subject token
client_id	The consumer's client_id. Follows the naming scheme <cluster>:<namespace>:<appname>

Other claims such as pid are copied verbatim from the original token issued by ID-porten.

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

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 (JavaScript)
• navikt/token-support (Java / Kotlin)

Validation is also supported by many popular frameworks:

• Ktor (Kotlin)
• Spring Security (Java / Kotlin)

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

Other Token Claims

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

See the TokenX claims reference for details.