# ID-porten reference

## Spec

For all possible configuration options, see the [📚 Nais application reference](/workloads/application/reference/spec.md#idporten).

## 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](/auth/idporten/how-to/login.md). |

For further details about this endpoint, 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 application with ID-porten](/auth/idporten/how-to/login.md).

| Name | Description |
| :--- | :--- |
| `IDPORTEN_AUDIENCE` | The expected [audience](/auth/explanations.md#token-validation) for access tokens from ID-porten. |
| `IDPORTEN_WELL_KNOWN_URL` | The URL for ID-porten's [OIDC metadata discovery document](/auth/explanations.md#well-known-url-metadata-document). |
| `IDPORTEN_ISSUER` | `issuer` from the [metadata discovery document](/auth/explanations.md#issuer). |
| `IDPORTEN_JWKS_URI` | `jwks_uri` from the [metadata discovery document](/auth/explanations.md#jwks-endpoint-public-keys). |

`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](https://docs.digdir.no/docs/idporten/oidc/oidc_protocol_access_token#by-value--self-contained-access-token).

- **`acr`**: The [security level](#security-levels) 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](https://docs.digdir.no/docs/idporten/oidc/oidc_protocol_id_token#acr-values).
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:

```yaml
spec:
  idporten:
    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](#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 `IDPORTEN_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 `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:

1. the `IDPORTEN_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 `IDPORTEN_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.