github/wonderwall
1
0
Fork 0
mirror of https://github.com/nais/wonderwall.git synced 2026-08-23 21:16:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clean up readme

Browse Source
This commit is contained in:
Trong Huu Nguyen
2025-04-02 11:53:25 +02:00
parent 22d35f073c
commit 48527e47f8
1 changed files with 73 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+73 -46
View File
@@ -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 <access_token>
```
### 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 <http://localhost:3000>.
Try it out:
The response should be returned as-is from the upstream.
The `authorization` header should not be set.
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.
### Log in
Visit <http://localhost:3000/oauth2/login>.
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 <http://localhost:3000/oauth2/logout>.
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:<shasum>
```
## Development
Requires Go 1.24
```shell
docker-compose up -d
make local
```