blob: 5c72d91bad3cffc46431d7ab87b02ba80137e6af (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
|
# Development
Sparkle uses [Envoy Proxy](https://www.envoyproxy.io/) to manage authentication
via GitLab's Identity Provider (IdP). When a user makes a request without valid
authentication cookies, Envoy redirects the request to the IdP. It then completes
an OpenID Connect (OIDC) flow to obtain an `id_token`, `access_token`, and
`refresh_token`, sets them as cookies, and forwards the request to Sparkle.
This architecture enables Sparkle to focus solely on application logic, without needing to:
* Handle session cookies manually,
* Exchange refresh tokens for new access tokens, or
* Access client credentials like `client_id` or `client_secret` directly.
## Request Flow Overview
```plaintext
+-------------+ +---------------+ +-----------------+ +-------+
| User-Agent | | Proxy (:1000) | | Sparkle (:8080) | | (IdP) |
+-------------+ +---------------+ +-----------------+ +-------+
| | | |
|---> HTTP Request ----------> | |
| (no or invalid cookie) | | |
| | | |
|<--- 302 Redirect to IdP ---| | |
| | | |
|---------------------------->----------------------------------------------------------------->|
| Auth Request (Login) | | |
| | | |
|<------------------------------------------------------------------ Auth Response (Grant) -----|
| | | |
|---> Callback to Proxy ---->| | |
| (code or token) | | |
| |---> Exchange Grant for Token ----------------------------------->|
| | | |
| |<--- ID / Access Token -------------------------------------------|
| | | |
| |---> Forward Request --->| |
| | (Set-Cookie headers) | |
| | | |
| |<--- Response ----------------------| |
|<--- Final Response --------| | |
```
## Configuration
Both Envoy and Sparkle are configured via environment variables. You can copy the
`.env` file to `.env.local` and fill in the required values:
```bash
cp .env .env.local
```
The following environment variables must be defined:
| Variable Name | Description |
| ---------------------- | ------------------------------------------------ |
| `APP_ENV` | Sparkle environment (default: `development`) |
| `OAUTH_CLIENT_ID` | The client ID registered with GitLab IdP |
| `OAUTH_CLIENT_SECRET` | The corresponding client secret |
| `OIDC_ISSUER` | The issuer URL (e.g., `http://gdk.test:3000`) |
Follow these instructions to [create a user-owned application](https://docs.gitlab.com/integration/oauth_provider/#create-a-user-owned-application)
and set the `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`.
You can refer to the `Dockerfile` in the root of this repository to determine the
exact version of Envoy required. To install Envoy locally, follow the [official
installation guide](https://www.envoyproxy.io/docs/envoy/latest/start/install).
To install [dumb-init](https://github.com/Yelp/dumb-init) see the
[documentation](https://github.com/Yelp/dumb-init).
Sparkle uses the following Envoy Filters:
* [envoy.filters.http.oauth2](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/oauth2_filter)
* [envoy.filters.http.router](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter)
## Usage
You can run Sparkle and Envoy either natively or in Docker:
* **Run Sparkle + Envoy on the host machine:**
```bash
$ make run
```
* **Run Sparkle + Envoy in Docker:**
```bash
$ make run-image
```
|
