wonderwall/README.md

wonderwall

wonderwall is an application that implements OpenID Connect 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

About

Wonderwall currently implements a client that follows ID-porten's preferred setup:

• OpenID Connect Authorization Code Flow with mandatory use of PKCE, state and nonce - aiming to be compliant with OAuth 2.1.
• Validation of id_token in accordance with the OpenID Connect Core specifications.
• Client authentication with the authorization server as per RFC 7523, Section 2.2.
• Support for RP-initiated logout.
• Support for front-channel logout.

Endpoints

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

• /oauth2/login redirects the user to ID-porten to perform the OpenID Connect Authorization Code Flow.
• /oauth2/callback handles callbacks from ID-porten as part of the OpenID Connect Authorization Code Flow.
• /oauth2/logout triggers self-initiated/RP-initiated logout.
• /oauth2/logout/frontchannel implements front-channel logout.

Functionality

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.

Usage

In order to initiate authenticated user sessions, the user must be redirected to the /oauth2/login endpoint, which performs the OIDC Auth Code flow. The user will then be redirected back to the downstream application, with the Authorization header containing a Bearer access token. As long as the user has an active session with Wonderwall, all further requests to the downstream application will have the Authorization header set.

Development

Requirements

• Go 1.17

Configuration

Required

• IDPORTEN_CLIENT_ID
  Client ID for the client at ID-porten.
• IDPORTEN_CLIENT_JWK
  Private key belonging to the client in JWK format.
• IDPORTEN_REDIRECT_URI
  Valid pre-registered redirect URI that ID-porten should redirect the user to as part of the authentication flow.
  For example: http://localhost:8090/oauth2/callback
• IDPORTEN_WELL_KNOWN_URL
  Well-known OpenID Configuration endpoint for ID-porten: https://docs.digdir.no/oidc_func_wellknown.html.

Optional

Wonderwall can be configured using either command-line flags or equivalent environment variables (i.e. -, . -> _ and uppercase).

Build with make wonderwall and run ./bin/wonderwall --help to see the available flags.