From 48527e47f84e52efe36c771b05e56095b650d7c8 Mon Sep 17 00:00:00 2001 From: Trong Huu Nguyen Date: Thu, 6 Mar 2025 19:38:58 +0100 Subject: [PATCH] docs: clean up readme --- README.md | 119 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 73 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index e471a91..cbd9baf 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,70 @@ -# wonderwall +# Wonderwall ![anyway here's wonderwall](https://i.imgur.com/NhRLEej.png) -Wonderwall is an application that implements an _OpenID Connect_ (OIDC) relying party/client in a way that makes it -easy to plug into Kubernetes applications as a _sidecar_. +Wonderwall is a reverse proxy that implements an _OpenID Connect_ (OIDC) relying party (or client), primarily for use as a [Kubernetes _sidecar_](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/). -As such, this is OIDC as a sidecar, or OaaS, or to explain the joke: +As such, this is OIDC as a sidecar, or OaaS, or to explain the joke: > _Oasis - Wonderwall_ -Wonderwall functions as a reverse proxy that should be placed in front of your application; intercepting and proxying requests. -It provides endpoints to perform logins and logouts for end users, along with session management - so that your application does not have to. - -Architecturally, Wonderwall is modeled after the backend-for-frontend (BFF) pattern as described in [Best Current Practices - OAuth 2.0 for Browser-Based Apps, section 6.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps#name-backend-for-frontend-bff). - ## 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 +- [OpenID Connect Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) with mandatory use of [PKCE](https://datatracker.ietf.org/doc/html/rfc7636), state and nonce - Client authentication using client assertions (`private_key_jwt`) ([RFC 7523, Section 2.2](https://datatracker.ietf.org/doc/html/rfc7523)) - [OpenID Connect RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html) - [OpenID Connect Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html) - [OAuth 2.0 Pushed Authorization Requests (RFC 9126)](https://datatracker.ietf.org/doc/html/rfc9126) -- Encrypted sessions with XChaCha20-Poly1305, stored using Redis as the backend +- Sessions stored in Redis, encrypted with XChaCha20-Poly1305. - Two deployment modes: - Standalone mode (default) for zero-trust based setups where each application has its own perimeter and client - Single sign-on (SSO) mode for shared authentication across multiple applications on a common domain -## How it works +Wonderwall fits in the backend-for-frontend (BFF) pattern as described in [Best Current Practices - OAuth 2.0 for Browser-Based Apps, section 6.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps#name-backend-for-frontend-bff). -End-user authentication using Wonderwall is fairly straightforward: - -- If the user does _not_ have a valid local session with the sidecar, requests will be proxied to the upstream host as-is without modifications. -- To obtain a local session, the user must be redirected to the `/oauth2/login` endpoint, which will initiate 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 upstream host will now contain an `Authorization` header with the user's `access_token` as a Bearer token, as long as the session is not expired or inactive. -- To log out, the user must be redirected to the `/oauth2/logout` endpoint. - -Detailed documentation can be found in the [documentation](docs) directory: +For further details, see [the documentation directory](docs): - [Architecture](docs/architecture.md) - [Configuration](docs/configuration.md) - [Endpoints](docs/endpoints.md) - [Usage](docs/usage.md) - - [Session Management](docs/sessions.md) +- [Sessions](docs/sessions.md) -## Quickstart +## How it works + +Wonderwall abstracts away the complexities of authentication and session management from your application, +making end-user authentication fairly straightforward. + +### Unauthenticated requests + +If the user does _not_ have a valid session, requests will be proxied to the upstream host as-is without modifications. + +### Log in a user + +To establish a session, redirect the user to the `/oauth2/login` endpoint. +This initiates the OpenID Connect Authorization Code Flow. + +### Authenticated requests + +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. + +As long as the session is valid, the user's access token is attached for all requests to the upstream: + +```http request +GET /some/path HTTP/1.1 +Host: 127.0.0.1:8080 +Authorization: Bearer +``` + +### Log out a user + +To log out, redirect the user to the `/oauth2/logout` endpoint. +This clears the session and redirects the user to the identity provider for single-logout. + +## Quick start See [docker-compose.example.yml](docker-compose.example.yml) for an example setup: @@ -55,22 +72,41 @@ See [docker-compose.example.yml](docker-compose.example.yml) for an example setu docker-compose -f docker-compose.example.yml up ``` -This starts: +### Unauthenticated request -- Wonderwall (port 3000) with Redis as the session storage -- [http-https-echo](https://hub.docker.com/r/mendhak/http-https-echo) (port 4000) as the upstream server -- [mock-oauth2-server](https://github.com/navikt/mock-oauth2-server) as the identity provider +Visit . -Try it out: +The response should be returned as-is from the upstream. +The `authorization` header should not be set. -1. Visit - 1. The response should be returned as-is from the upstream. - 2. The `authorization` header should not be set. -2. Visit - 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 - 1. The `authorization` header should no longer be set in the upstream response. +### Log in + +Visit . + +The `authorization` header should now be set in the upstream response. +The response should also include the decoded JWT from said header. + +### Log out + +Visit . + +The `authorization` header should no longer be set in the upstream response. + +## Development + +Requires Go 1.24. + +Start up dependencies: + +```shell +docker-compose up -d +``` + +Start Wonderwall: + +```shell +make local +``` ## Docker Images @@ -99,12 +135,3 @@ cosign verify-attestation --type cyclonedx \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ europe-north1-docker.pkg.dev/nais-io/nais/images/wonderwall@sha25: ``` - -## Development - -Requires Go 1.24 - -```shell -docker-compose up -d -make local -```