diff options
| -rw-r--r-- | share/man/DEVELOPMENT.md | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/share/man/DEVELOPMENT.md b/share/man/DEVELOPMENT.md new file mode 100644 index 0000000..3e21bf7 --- /dev/null +++ b/share/man/DEVELOPMENT.md @@ -0,0 +1,59 @@ +# Development + +Sparkle uses [Envoy proxy](https://www.envoyproxy.io/) to redirect +unauthenticated requests to the GitLab Identity Provider and then retrieves an +`id_token`, `access_token` and `refresh_token` using an OpenID Connect workflow +to inject these tokens as cookies before forwarding the request to Sparkle. + +This flow allows Sparkle to focus on application logic without needing to +directly manage session cookies, exchange a refresh token for a new access token +and directly access the `client_id` and `client_secret`. + +```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 is injected into envoy and sparkle via environment variables. +Please see the [Envoy installation documentation](https://www.envoyproxy.io/docs/envoy/latest/start/install) +to install the appropriate version of Envoy on your operating system. The version +of envoy that you need to install can be found in the `Dockerfile` in the root +of this repository. + +## Usage + +* **Run Sparkle + Envoy on the host machine:** + + ```bash + $ make run + ``` + +* **Run Sparkle + Envoy in Docker:** + + ```bash + $ make run-image + ``` + |