Auth reference¶

Libraries for mocking¶

• https://github.com/navikt/mock-oauth2-server
• https://github.com/navikt/fakedings - a wrapper around the above mock server

Libraries and frameworks for validating and acquiring tokens¶

Below is a list of some well-known and widely used libraries for handling OAuth, OpenID Connect, and token validation.

JVM¶

• https://github.com/navikt/token-support
• https://ktor.io/docs/jwt.html
• https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/
• https://github.com/pac4j/pac4j
• https://connect2id.com/products/nimbus-oauth-openid-connect-sdk

JavaScript¶

• https://github.com/navikt/oasis
• https://github.com/panva/jose
• https://github.com/panva/node-openid-client

See also https://jwt.io/libraries for a non-comprehensive list for many other various languages.

Token generators¶

In some cases, you want to locally develop and test against a secured API in the development environments. You will need a token to access said API.

See the respective identity provider pages for details on acquiring such tokens:

• Entra ID
• TokenX

Login proxy¶

Reference documentation for the login proxy provided by NAIS. Supported identity providers:

• Entra ID for logging in employees.
• ID-porten for logging in citizens.

Autologin¶

Autologin is not enabled by default. To enable autologin:

spec:
  idporten:
    sidecar:
      autoLogin: true

spec:
  azure:
    sidecar:
      autoLogin: true

Autologin response¶

Responses returned by autologin depends on the type of request.

Top-level navigation requests result in a HTTP 302 Found response.

GET /some/path

Sec-Fetch-Dest: document
Sec-Fetch-Mode: navigate
Referer: https://<ingress>/original/path

HTTP/2 302 Found
Location: https://<ingress>/oauth2/login?redirect=/original/path

This automatically redirects the user to the login endpoint. To preserve the user's original location, the redirect parameter is set to the request's Referer header. If the Referer header is empty, the matching ingress context path is used.

Non-navigation requests result in an equivalent response, but with the HTTP 401 Unauthorized status code:

GET /some/path

Sec-Fetch-Dest: empty
Sec-Fetch-Mode: cors
Referer: https://<ingress>/original/path

HTTP/2 401 Unauthorized
Content-Type: application/json

{"error": "unauthenticated, please log in"}

Ensure that your frontend code handles HTTP 401 responses and appropriately notifies the user and/or redirects them to the login endpoint.

Autologin exclusions¶

Autologin matches all paths for your application's ingresses, except the following:

• /oauth2/**
• spec.prometheus.path (if defined)
• spec.liveness.path (if defined)
• spec.readiness.path (if defined)

You can exclude additional paths by exact match or wildcard patterns:

spec:
  idporten:
    sidecar:
      autoLogin: true
      autoLoginIgnorePaths:
        - /exact/path
        - /api/v1/*
        - /api/**

spec:
  azure:
    sidecar:
      autoLogin: true
      autoLoginIgnorePaths:
        - /exact/path
        - /api/v1/*
        - /api/**

The paths must be absolute paths. The match patterns use glob-style matching:

• Trailing slashes in paths and patterns are ignored.
• A single asterisk (/*) is non-recursive. This matches any subpath directly below the path, excluding itself and any nested paths.
• Double asterisks (/**) is recursive. This matches any subpath below the path, including itself and any nested paths.

Endpoints¶

The following endpoints are available under your application's ingress:

Login endpoint¶

This endpoint initiates the authentication flow. It is available at:

https://<ingress>/oauth2/login

To log in an end-user, redirect them to this endpoint. After login, they are by default redirected back to the matching context path for your application's ingress:

• / for https://<app>.nav.no
• /path for https://nav.no/path

Supported query parameters:

redirect

Overrides the default redirect:

https://<ingress>/oauth2/login?redirect=/some/path

Value must be an URL encoded absolute path.

prompt

Prompts the user to select an account at the identity provider. Useful for switching between multiple accounts.

https://<ingress>/oauth2/login?prompt=select_account

Value must be select_account.

Logout endpoint¶

This endpoint triggers single-logout. It is available at:

https://<ingress>/oauth2/logout

To log out an end-user, redirect them to this endpoint. After logout, they are by default redirected back to a preconfigured URL.

Supported query parameters:

redirect

Overrides the default redirect:

https://<ingress>/oauth2/logout?redirect=/some/path

Value must be an URL encoded absolute path.

Session endpoint¶

This endpoint returns metadata about the end-user's session as a JSON object. Requests to this endpoint must be triggered from the user agent.

GET /oauth2/session

HTTP/2 200 OK
Content-Type: application/json

{
  "session": {
    "active": true,
    "created_at": "2022-08-31T06:58:38.724717899Z", 
    "ends_at": "2022-08-31T16:58:38.724717899Z",
    "ends_in_seconds": 14658,
    "timeout_at": "0001-01-01T00:00:00Z",
    "timeout_in_seconds": -1
  },
  "tokens": {
    "expire_at": "2022-08-31T14:03:47.318251953Z",
    "expire_in_seconds": 4166
    "next_auto_refresh_in_seconds": -1,
    "refreshed_at": "2022-08-31T12:53:58.318251953Z",
    "refresh_cooldown": false,
    "refresh_cooldown_seconds": 0
  }
}

The table below describes the different fields in the JSON response.

This endpoint will respond with the following HTTP status codes on errors:

• HTTP 401 Unauthorized - no session cookie or matching session found, or maximum lifetime reached
• HTTP 500 Internal Server Error - the login proxy wasn't able to process the request

Otherwise, an HTTP 200 OK is returned with the metadata with the application/json as the Content-Type.

Note that this endpoint will still return HTTP 200 OK for inactive sessions, as long as the session is not expired. This allows application to display errors before redirecting the user to login on timeouts. The HTTP status code alone is insufficient to determine the session state.

Session refresh endpoint¶

This endpoint allows for refreshing the end-user's session on demand. Requests to this endpoint must be triggered from the user agent.

Using this endpoint is only necessary when session inactivity timeouts are enabled. The end-user should be prompted to extend their session in accordance with WCAG 2.2.1.

The endpoint will respond with a HTTP 401 Unauthorized if the session is inactive. It is otherwise equivalent to the session endpoint.

POST /oauth2/session/refresh

HTTP/2 200 OK
Content-Type: application/json

{
  "session": {
    "active": true,
    "created_at": "2022-08-31T06:58:38.724717899Z", 
    "ends_at": "2022-08-31T16:58:38.724717899Z",
    "ends_in_seconds": 14658,
    "timeout_at": "0001-01-01T00:00:00Z",
    "timeout_in_seconds": -1
  },
  "tokens": {
    "expire_at": "2022-08-31T14:03:47.318251953Z",
    "expire_in_seconds": 4166,
    "next_auto_refresh_in_seconds": 3866,
    "refreshed_at": "2022-08-31T12:53:58.318251953Z",
    "refresh_cooldown": true,
    "refresh_cooldown_seconds": 37
  }
}

Session management¶

A user's session can be inspected by requesting the session endpoint from their user agent.

Session lifetime¶

Sessions have a maximum lifetime, after which the user is unauthenticated and must perform a new login.

Session inactivity timeout¶

Sessions may have an inactivity timeout. If enabled, the session is marked as invalid if the timeout has been reached. The timeout is reset each time the user's session is refreshed through the session refresh endpoint.

If inactivity timeout is not enabled, the tokens within the session are automatically refreshed until the session reaches its maximum lifetime.

The durations for maximum lifetime and inactivity timeout are subject to change. Do not hard-code or depend on these exact values in your application. Prefer using the metadata returned by the session endpoint to determine the session's state.