wonderwall

wonderwall is an application that implements an OpenID Connect (OIDC) relying party/client in a way that makes it easy to plug into Kubernetes as a sidecar. As such, this is OIDC as a sidecar, or OaaS, or to explain the joke: Oasis - Wonderwall

Features

Wonderwall aims to be compliant with OAuth 2.1, and supports the following:

• OpenID Connect Authorization Code Flow with mandatory use of PKCE, state and nonce
• Client authentication using client assertions (private_key_jwt) as per RFC 7523, Section 2.2.
• RP-initiated logout.
• Front-channel logout.

Wonderwall functions as an optionally intercepting reverse proxy that proxies requests to a downstream host.

By default, it does not actually intercept any requests other than to remove the Authorization header if the user agent does not have a valid session with Wonderwall.

Overview

The image below shows the overall architecture of an application when using Wonderwall as a sidecar:

The sequence diagram below shows the default behavior of Wonderwall:

Generally speaking, the recommended approach when using the Wonderwall sidecar is to put it in front of your backend-for-frontend server that serves your frontend. Otherwise, you might run into issues with the cookie configuration and allowed redirects - these are both effectively restricted to only match the domain and path for your application's ingress.

Endpoints

Wonderwall exposes and owns these endpoints (which means they will never be proxied downstream).

Endpoints that are available for use by applications:

Path	Description
/oauth2/login	Initiates the OpenID Connect Authorization Code flow
/oauth2/logout	Initiates local and global/single-logout
/oauth2/session	Returns the current user's session metadata
/oauth2/session/refresh	Refreshes the tokens for the user's session. Requires the session.refresh flag to be enabled

Endpoints that should be registered at and only be triggered by identity providers:

Path	Description
/oauth2/callback	Handles the callback from the identity provider
/oauth2/logout/callback	Handles the logout callback from the identity provider
/oauth2/logout/frontchannel	Handles global logout request (initiated by identity provider on behalf of another client)

Usage

If the user does not have a valid local session with the sidecar, the request will be proxied as-is without modifications to the upstream host.

In order to obtain a local session, the user must be redirected to the /oauth2/login endpoint, which performs the OpenID Connect Authorization Code Flow.

If the user successfully completed the login flow, the sidecar creates and stores a session. A corresponding session cookie is created and set before finally redirecting user agent to the application. All requests that are forwarded to the application container will now contain an Authorization header with the user's access_token as a Bearer token.

Do note that cookies are set for the most specific subdomain and path (if any) defined in the ingress configuration variable.

Configuration

Wonderwall can be configured using either command-line flags or equivalent environment variables (i.e. -, . -> _ and uppercase), with WONDERWALL_ as prefix. E.g.:

openid.client-id -> WONDERWALL_OPENID_CLIENT_ID

The following flags are available:

--auto-login                               Automatically redirect user to login if the user does not have a valid session for all proxied downstream requests.
--auto-login-ignore-paths strings          Comma separated list of absolute paths to ignore when 'auto-login' is enabled. Supports basic wildcard matching with glob-style single asterisks using the stdlib path.Match. Invalid patterns are ignored.
--bind-address string                      Listen address for public connections. (default "127.0.0.1:3000")
--encryption-key string                    Base64 encoded 256-bit cookie encryption key; must be identical in instances that share session store.
--error-redirect-uri string                URI to redirect user to on errors for custom error handling.
--ingress strings                          Comma separated list of ingresses used to access the main application.
--log-format string                        Log format, either 'json' or 'text'. (default "json")
--log-level string                         Logging verbosity level. (default "info")
--loginstatus.cookie-domain string         The domain that the cookie should be set for.
--loginstatus.cookie-name string           The name of the cookie.
--loginstatus.enabled                      Feature toggle for Loginstatus, a separate service that should provide an opaque token to indicate that a user has been authenticated previously, e.g. by another application in another subdomain.
--loginstatus.resource-indicator string    The resource indicator that should be included in the authorization request to get an audience-restricted token that Loginstatus accepts. Empty means no resource indicator.
--loginstatus.token-url string             The URL to the Loginstatus service that returns an opaque token.
--metrics-bind-address string              Listen address for metrics only. (default "127.0.0.1:3001")
--openid.acr-values string                 Space separated string that configures the default security level (acr_values) parameter for authorization requests.
--openid.client-id string                  Client ID for the OpenID client.
--openid.client-jwk string                 JWK containing the private key for the OpenID client in string format.
--openid.post-logout-redirect-uri string   URI for redirecting the user after successful logout at the Identity Provider.
--openid.provider string                   Provider configuration to load and use, either 'openid', 'azure', 'idporten'. (default "openid")
--openid.scopes strings                    List of additional scopes (other than 'openid') that should be used during the login flow.
--openid.ui-locales string                 Space-separated string that configures the default UI locale (ui_locales) parameter for OAuth2 consent screen.
--openid.well-known-url string             URI to the well-known OpenID Configuration metadata document.
--redis.address string                     Address of Redis. An empty value will use in-memory session storage.
--redis.password string                    Password for Redis.
--redis.tls                                Whether or not to use TLS for connecting to Redis. (default true)
--redis.username string                    Username for Redis.
--session.max-lifetime duration            Max lifetime for user sessions. (default 1h0m0s)
--session.refresh                          Automatically refresh the tokens for user sessions if they are expired, as long as the session exists (indicated by the session max lifetime).
--upstream-host string                     Address of upstream host. (default "127.0.0.1:8080")

Boolean flags/options are by default set to false unless noted otherwise.

At minimum, the following configuration must be provided:

• openid.client-id
• openid.client-jwk
• openid.well-known-url
• ingress

ID-porten

When the openid.provider flag is set to idporten, the following environment variables are bound to the required openid flags described previously:

• IDPORTEN_CLIENT_ID
  Client ID for the client at ID-porten.
• IDPORTEN_CLIENT_JWK
  Private key belonging to the client in JWK format.
• IDPORTEN_WELL_KNOWN_URL
  Well-known OpenID Configuration endpoint for ID-porten: https://docs.digdir.no/oidc_func_wellknown.html.

The default values for the following flags are also changed:

Flag	Value
openid.acr-values	Level4
openid.ui-locales	nb

Azure AD

When the openid.provider flag is set to azure, the following environment variables are bound to the required flags described previously:

• AZURE_APP_CLIENT_ID
  Client ID for the client at Azure AD.
• AZURE_APP_CLIENT_JWK
  Private key belonging to the client in JWK format.
• AZURE_APP_WELL_KNOWN_URL
  Well-known OpenID Configuration endpoint for Azure AD.

Session Management

Sessions are stored server-side; we only store a session identifier at the end-user's user agent. For production use, we strongly recommend setting up and connecting to Redis.

Sessions can be configured with a maximum lifetime with the session.max-lifetime flag, which accepts Go duration strings (e.g. 10h, 5m, 30s, etc.).

There's also an endpoint that returns metadata about the user's session as a JSON object at /oauth2/session. This endpoint will respond with HTTP status codes on errors:

• 401 Unauthorized - no session cookie or matching session found (e.g. user is not authenticated, or has logged out)
• 500 Internal Server Error - the session store is unavailable, or Wonderwall 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, e.g:

{
  "session": {
    "created_at": "2022-08-31T06:58:38.724717899Z", 
    "ends_at": "2022-08-31T16:58:38.724717899Z",
    "ends_in_seconds": 14658
  },
  "tokens": {
    "expire_at": "2022-08-31T14:03:47.318251953Z",
    "refreshed_at": "2022-08-31T12:53:58.318251953Z",
    "expire_in_seconds": 4166
  }
}

Most of these fields should be self-explanatory, but we'll be explicit with their description:

Field	Description
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.
session.ends_in_seconds	The number of seconds until the session ends.
tokens.expire_at	The timestamp that denotes when the tokens within the session will expire.
tokens.refreshed_at	The timestamp that denotes when the tokens within the session was last refreshed.
tokens.expire_in_seconds	The number of seconds until the tokens expire.

Refresh Tokens

Tokens within the session will usually expire before the session itself. If you've configured a longer session lifetime, you'll probably want to use refresh tokens to avoid redirecting end-users to the /oauth2/login endpoint whenever the access tokens have expired. This can be enabled by using the session.refresh flag.

If session refresh is enabled, tokens will at the earliest be automatically renewed 5 minutes before they expire. This happens whenever the end-user visits any path that is proxied to the upstream application.

The session.refresh flag also enables a new endpoint:

• /oauth2/session/refresh - manually refreshes the tokens for the user's session, and returns the metadata like in /oauth2/session described previously

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

Additionally, the metadata object returned by both the /oauth2/session and /oauth2/session/refresh endpoints now contain three new fields in addition to the previous fields:

Field	Description
tokens.next_auto_refresh_in_seconds	The number of seconds until the earliest time where the tokens will automatically be 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.

Note that the refresh operation has a default cooldown period of 1 minute, which may be shorter depending on the token lifetime of the tokens returned by the identity provider. In other words, a request to the /oauth2/sesion/refresh endpoint will only trigger a refresh the cooldown is not active.

Development

Requirements

• Go 1.19

Binary

make wonderwall and ./bin/wonderwall

See configuration.

Docker Compose

See the docker-compose file for an example setup:

• Requires an environment variable WONDERWALL_OPENID_CLIENT_JWK with a private JWK.
  • This can be acquired from https://mkjwk.org.
  • Set the environment variable in an .env file that Docker Compose automatically detects and uses
  • Environment variables can be finicky with escaping, so try to wrap the value with single quotation marks.
    • E.g. WONDERWALL_OPENID_CLIENT_JWK='{ "p": "_xCP...", ... }'.
• You need to be able to reach host.docker.internal to reach the identity provider mock, so make sure you have 127.0.0.1 host.docker.internal in your /etc/hosts file.
• By default, the setup will use the latest available pre-built image.
  • If you want to will build a fresh binary from the cloned source, replace the following

services:
  ...
  wonderwall:
    image: ghcr.io/nais/wonderwall:latest

with

services:
  ...
  wonderwall:
    build: .

Run docker-compose up. This starts:

• Wonderwall
• Redis as the session storage
• mock-oauth2-server as an identity provider
• http-https-echo as a dummy upstream server

Try it out:

1. Visit http://localhost:3000
   1. The response should be returned as-is from the upstream.
   2. The authorization header should not be set.
2. Visit http://localhost:3000/oauth2/login
   1. The authorization header should now be set in the upstream response.
   2. The response should also include the decoded JWT from said header.
3. Visit http://localhost:3000/oauth2/logout
   1. The authorization header should no longer be set in the upstream response.