mirror of
https://github.com/nais/wonderwall.git
synced 2026-05-11 02:47:05 +00:00
11f860d5dd
Co-Authored-By: Morten Lied Johansen <morten.lied.johansen@nav.no> Co-Authored-By: Sindre Rødseth Hansen <sindre.rodseth.hansen@nav.no>
67 lines
2.9 KiB
Markdown
67 lines
2.9 KiB
Markdown
# 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](https://docs.digdir.no/oidc_guide_idporten.html):
|
|
|
|
- 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](https://datatracker.ietf.org/doc/html/rfc7523).
|
|
- Support for [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html).
|
|
- Support for [front-channel logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html).
|
|
|
|
### 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.
|