BlueGit

timfa bluegit

Files

bluegit / docs / AUTH.md

AUTH.md

feat: eerste basis van BlueGit
timfa project_87923614_bot_3aff574f6f98414b945a8799374f9092 · pushed by timfa · 3 weeks ago
151aa352 History
AUTH.md 3.4 KiB Download Raw

Koppeling met auth.timfalken.com

De auth-server is geen OpenID-provider. https://auth.timfalken.com/.well-known/openid-configuration geeft 404. De integratie staat op https://auth.timfalken.com/help en, machineleesbaar, op https://auth.timfalken.com/help.json (schema 1.7, dienst account-auth). Verhalenboek op projects.timfalken.com gebruikt dezelfde flow; de README daar noemt dezelfde eindpunten.

Wat een site moet doen

1. Een beheerder registreert het domein op /admin. Het domein is de client_id. Voor BlueGit is dat git.timfalken.com. Het client_secret verschijnt één keer. 2. Het callback-pad is alleen het pad, zonder query. Voor BlueGit: /auth/callback. De volledige redirect-URI is https://git.timfalken.com/auth/callback. Subdomeinen van het geregistreerde domein zijn toegestaan. Een afwijkende poort moet apart geregistreerd worden. 3. De browser gaat naar GET /oauth/authorize met client_id, redirect_uri, response_type=code en een verplichte state. 4. De callback controleert state en wisselt de code server-side:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json
User-Agent: BlueGitAccountClient/0.1

grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&client_secret=…

5. Het antwoord bevat access_token, expires_in (86400) en user met id, username en avatar_url. Geen e-mailadres. 6. GET /api/me met Authorization: Bearer vult is_admin, email_verified en passkey_only aan. is_admin is beheerder van de auth-server, niet van BlueGit. 7. POST /api/session/extend schuift de 24 uur op. POST /api/logout trekt het token in. 8. Elke verbonden site moet een knop hebben waarmee de ingelogde gebruiker meteen zijn gegevens als JSON krijgt. Dat is Account → Gegevens downloaden (GET /settings/export).

BlueGit stuurt op elk server-naar-server-verzoek User-Agent: BlueGitAccountClient/0.1 en Accept: application/json.

Wat BlueGit bewaart

Van het account: het numerieke id, de gebruikersnaam in kleine letters, de avatar-URL, en of die persoon op de auth-server beheerder is. Geen e-mail. Het bearer-token blijft in de sessietabel tot afmelden of verlopen.

SSH-sleutels op de auth-server zijn er voor aanmelden dáár (POST /api/ssh-login/challenge en /verify, namespace timfalken-account). Er is geen API waarmee een verbonden site die sleutels mag ophalen. BlueGit houdt daarom eigen sleutels bij voor git-over-SSH. Ze worden geplakt op de accountpagina.

Configuratie

auth:
  mode: oauth
  base_url: https://auth.timfalken.com
  client_id: git.timfalken.com
  client_secret_file: /etc/bluegit/client_secret
  redirect_path: /auth/callback
  user_agent: BlueGitAccountClient/0.1

Een leeg client_secret valt terug op het bestand, en dat weer op BLUEGIT_AUTH_CLIENT_SECRET.

auth.mode: dev slaat de ronde over en maakt een sessie voor dev_user. De configuratie weigert die modus als base_url op git.timfalken.com staat.

Export

Het JSON-bestand bevat het account, de namen en voorvoegsels van toegangstokens (niet het token zelf), de publieke SSH-sleutels, en de waarden van geheimen van repositories en groepen waarvan deze gebruiker beheerder is. Dat laatste hoort bij "alle persoonsgegevens", en het is de reden dat alleen die gebruiker de route mag aanroepen.

Source
1# Koppeling met auth.timfalken.com
2
3De auth-server is geen OpenID-provider. `https://auth.timfalken.com/.well-known/openid-configuration` geeft 404. De integratie staat op [https://auth.timfalken.com/help](https://auth.timfalken.com/help) en, machineleesbaar, op [https://auth.timfalken.com/help.json](https://auth.timfalken.com/help.json) (schema 1.7, dienst `account-auth`). Verhalenboek op `projects.timfalken.com` gebruikt dezelfde flow; de README daar noemt dezelfde eindpunten.
4
5## Wat een site moet doen
6
71. Een beheerder registreert het domein op `/admin`. Het domein is de `client_id`. Voor BlueGit is dat `git.timfalken.com`. Het `client_secret` verschijnt één keer.
82. Het callback-pad is alleen het pad, zonder query. Voor BlueGit: `/auth/callback`. De volledige redirect-URI is `https://git.timfalken.com/auth/callback`. Subdomeinen van het geregistreerde domein zijn toegestaan. Een afwijkende poort moet apart geregistreerd worden.
93. De browser gaat naar `GET /oauth/authorize` met `client_id`, `redirect_uri`, `response_type=code` en een verplichte `state`.
104. De callback controleert `state` en wisselt de code server-side:
11
12```http
13POST /oauth/token
14Content-Type: application/x-www-form-urlencoded
15Accept: application/json
16User-Agent: BlueGitAccountClient/0.1
17
18grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&client_secret=…
19```
20
215. Het antwoord bevat `access_token`, `expires_in` (86400) en `user` met `id`, `username` en `avatar_url`. Geen e-mailadres.
226. `GET /api/me` met `Authorization: Bearer` vult `is_admin`, `email_verified` en `passkey_only` aan. `is_admin` is beheerder van de auth-server, niet van BlueGit.
237. `POST /api/session/extend` schuift de 24 uur op. `POST /api/logout` trekt het token in.
248. Elke verbonden site moet een knop hebben waarmee de ingelogde gebruiker meteen zijn gegevens als JSON krijgt. Dat is `Account → Gegevens downloaden` (`GET /settings/export`).
25
26BlueGit stuurt op elk server-naar-server-verzoek `User-Agent: BlueGitAccountClient/0.1` en `Accept: application/json`.
27
28## Wat BlueGit bewaart
29
30Van het account: het numerieke id, de gebruikersnaam in kleine letters, de avatar-URL, en of die persoon op de auth-server beheerder is. Geen e-mail. Het bearer-token blijft in de sessietabel tot afmelden of verlopen.
31
32SSH-sleutels op de auth-server zijn er voor aanmelden dáár (`POST /api/ssh-login/challenge` en `/verify`, namespace `timfalken-account`). Er is geen API waarmee een verbonden site die sleutels mag ophalen. BlueGit houdt daarom eigen sleutels bij voor git-over-SSH. Ze worden geplakt op de accountpagina.
33
34## Configuratie
35
36```yaml
37auth:
38 mode: oauth
39 base_url: https://auth.timfalken.com
40 client_id: git.timfalken.com
41 client_secret_file: /etc/bluegit/client_secret
42 redirect_path: /auth/callback
43 user_agent: BlueGitAccountClient/0.1
44```
45
46Een leeg `client_secret` valt terug op het bestand, en dat weer op `BLUEGIT_AUTH_CLIENT_SECRET`.
47
48`auth.mode: dev` slaat de ronde over en maakt een sessie voor `dev_user`. De configuratie weigert die modus als `base_url` op `git.timfalken.com` staat.
49
50## Export
51
52Het JSON-bestand bevat het account, de namen en voorvoegsels van toegangstokens (niet het token zelf), de publieke SSH-sleutels, en de waarden van geheimen van repositories en groepen waarvan deze gebruiker beheerder is. Dat laatste hoort bij "alle persoonsgegevens", en het is de reden dat alleen die gebruiker de route mag aanroepen.