Auth reference¶

Reference documentation for the login proxy provided by Nais.

Enforcement of authenticated sessions is not enabled by default. To enable enforcement of login, specify the following in your application's manifest:

spec:
  login:
    enforce:
      enabled: true

Enforce mode response¶

Responses generated by the enforce mode depends on the type of request.

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

What is a top-level navigation request?

A top-level navigation request is a GET request that fulfills at least one of the following properties:

Has the Fetch metadata request headers Sec-Fetch-Dest=document and Sec-Fetch-Mode=navigate, or
Has an Accept header that includes text/html

Top-level navigation request

GET /some/path

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

Response

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:

What is a non-navigation request?

Non-navigation requests are any requests that aren't considered top-level navigation requests. Examples include:

Non-GET requests, such as POST or PUT requests
Any browser request that uses the Fetch or XMLHttpRequest APIs

Non-navigation request

GET /some/path

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

Response

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.

Enforce mode exclusions¶

Enforce mode 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:
  login:
    enforce:
      enabled: true
      excludePaths:
        - /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.

Example match patterns (click to expand)

/allowed or /allowed/

Trailing slashes in paths and patterns are effectively ignored during matching.

✅ matches:

/allowed
/allowed/

❌ does not match:

/allowed/nope
/allowed/nope/

/public/*

A single asterisk after a slash means any subpath directly below the path, excluding itself and any nested paths.

✅ matches:

/public/a

❌ does not match:

/public
/public/a/b

/public/**

Double asterisks after a slash means any subpath below the path, including itself and any nested paths.

✅ matches:

/public
/public/a
/public/a/b

❌ does not match:

/not/public
/not/public/a

/any*

A single asterisk matches any sequence of characters within a path segment.

✅ matches:

/any
/anything
/anywho

❌ does not match:

/any/thing
/anywho/mst/ve

/a/*/*

✅ matches:

/a/b/c
/a/bee/cee

❌ does not match:

/a
/a/b
/a/b/c/d

/static/**/*.js

✅ matches:

/static/bundle.js
/static/min/bundle.js
/static/vendor/min/bundle.js

❌ does not match:

/static
/static/some.css
/static/min
/static/min/some.css
/static/vendor/min/some.css

Endpoints¶

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

Path	Description	Details
`GET <ingress>/oauth2/login`	Redirect the user agent here to initiate login.	Login endpoint
`GET <ingress>/oauth2/logout`	Redirect the user agent here to initiate logout.	Logout endpoint
`GET <ingress>/oauth2/session`	Must be requested from user agent. Returns the current user's session metadata	Session 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>.test-nais.example
/path for https://test-nais.example/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.

level

The acr_values parameter for the OpenID Connect authentication request.

https://<ingress>/oauth2/login?level=some_acr_value

Value must be declared as supported by the Identity Provider through the acr_values_supported property in the metadata document.

locale

The ui_locales parameter for the OpenID Connect authentication request.

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

Value must be declared as supported by the Identity Provider through the ui_locales_supported property in the metadata document.

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. Usage of this endpoint is optional. It is intended for use by frontend applications to display or handle session state (e.g. timeouts or expirations).

Requests to this endpoint must be sent from the user agent (browser), e.g. using the Fetch API. Credentials must be included in the request, e.g. with credentials: 'include'.

Request

GET /oauth2/session

Response

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.

Session Metadata Field Descriptions (click to expand)

Field	Description
`session.active`	Whether or not the session is active. If `false`, the session cannot be refreshed and the user must be redirected to login to obtain a new session.
`session.created_at`	The timestamp that denotes when the session was first created.
`session.ends_at`	The timestamp that denotes when the session will end. After this point, the session is expired and the user must be redirected to login to obtain a new session.
`session.ends_in_seconds`	The number of seconds until `session.ends_at`.
`session.timeout_at`	The timestamp that denotes when the session will time out. The zero-value, `0001-01-01T00:00:00Z`, means no timeout.
`session.timeout_in_seconds`	The number of seconds until `session.timeout_at`. A value of `-1` means no timeout.
`tokens.expire_at`	The timestamp that denotes when the tokens within the session will expire.
`tokens.expire_in_seconds`	The number of seconds until `tokens.expire_at`.
`tokens.next_auto_refresh_in_seconds`	The number of seconds until the earliest time where the tokens will automatically be refreshed. A value of -1 means that automatic refreshing is not enabled.
`tokens.refreshed_at`	The timestamp that denotes when the tokens within the session was last refreshed.
`tokens.refresh_cooldown`	A boolean indicating whether or not the refresh operation is on cooldown or not.
`tokens.refresh_cooldown_seconds`	The number of seconds until the refresh operation is no longer on cooldown.

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.

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.

The default maximum lifetime is 10 hours.

Auth reference¶

Login proxy¶

Enforce login¶

Enforce mode response¶

Enforce mode exclusions¶

Endpoints¶

Login endpoint¶

Logout endpoint¶

Session endpoint¶

Session management¶

Session lifetime¶