ID-porten reference¶

Spec¶

For all possible configuration options, see the Nais application reference.

Runtime variables & credentials¶

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

Environment Variable	Description
`NAIS_TOKEN_INTROSPECTION_ENDPOINT`	Used to secure your application with ID-porten.

For further details about this endpoint, 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 application with ID-porten.

Name	Description
`IDPORTEN_AUDIENCE`	The expected audience for access tokens from ID-porten.
`IDPORTEN_WELL_KNOWN_URL`	The URL for ID-porten's OIDC metadata discovery document.
`IDPORTEN_ISSUER`	`issuer` from the metadata discovery document.
`IDPORTEN_JWKS_URI`	`jwks_uri` from the metadata discovery document.

IDPORTEN_WELL_KNOWN_URL is optional if you're using IDPORTEN_ISSUER and IDPORTEN_JWKS_URI directly.

Claims¶

Notable claims in tokens from ID-porten. For a complete list of claims, see the Access Token Reference in ID-porten.

acr: The security level used when authenticating the end-user.
pid: "Personidentifikator". The Norwegian national ID number (fødselsnummer/d-nummer) of the authenticated end user.

Locales¶

ID-porten supports a few different locales for the user interface during authentication.

Valid values shown below:

Value	Description
`nb`	Norwegian Bokmål
`nn`	Norwegian Nynorsk
`en`	English
`se`	Sámi

Set the query parameter locale when redirecting the user to login:

https://<ingress>/oauth2/login?locale=en

Security levels¶

ID-porten classifies different user authentication methods into security levels of assurance. This is reflected in the acr claim for the user's JWTs issued by ID-porten.

Valid values, in increasing order of assurance levels:

Value	Description	Notes
`idporten-loa-substantial`	a substantial level of assurance, e.g. MinID	Also known as `Level3`
`idporten-loa-high`	a high level of assurance, e.g. BankID, Buypass, Commfides, etc.	Also known as `Level4`

To configure a default value for all login requests:

app.yaml

spec:
  idporten:
    enabled: true
    sidecar:
      enabled: true
      level: idporten-loa-high

The default value is idporten-loa-high.

Nais ensures that the user's authentication level matches or exceeds the level configured by the application. If lower, the user is considered unauthenticated.

For runtime control of the value, set the query parameter level when redirecting the user to login:

https://<ingress>/oauth2/login?level=idporten-loa-high

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:

the IDPORTEN_ISSUER environment variable, or
the issuer property from the metadata discovery document. The document is found at the endpoint pointed to by the IDPORTEN_WELL_KNOWN_URL environment variable.

Audience Validation

Validate that the aud claim is equal to the IDPORTEN_AUDIENCE 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:

the IDPORTEN_JWKS_URI environment variable, or
the jwks_uri property from the metadata discovery document. The document is found at the endpoint pointed to by the IDPORTEN_WELL_KNOWN_URL environment variable.

Claims Validation

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