BlueGit

timfa bluegit

docs: Entra-aanmelden in AUTH.md en voorbeeldconfigs

Co-authored-by: Cursor <cursoragent@cursor.com>

timfa Tim Falken · pushed by timfa

Authored 2026-11-12 · 5 days ago

Hash
a2cd1e1b51200f7d216dd991ce224805539c82e2
Parent
bbaba0d3
Pipeline
Passed
2 files changed +66 −10
docs/AUTH.md +62 −10
@@ -1,8 +1,12 @@
1 # Koppeling met auth.timfalken.com
1 # Aanmelden: auth.timfalken.com of Microsoft Entra ID
2
3 BlueGit kent drie `auth.mode`-waarden: `oauth` (standaard, auth.timfalken.com), `entra` (Microsoft Entra ID, OIDC, één tenant) en `dev` (lokale sessie zonder IdP). Zonder nieuwe velden blijft alles zoals voorheen.
4
5 ## auth.timfalken.com (`mode: oauth`)
2 6
3 7 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](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 8
5 ## Wat een site moet doen
9 ### Wat een site moet doen
6 10
7 11 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.
8 12 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.
@@ -25,13 +29,7 @@ grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&client_sec
25 29
26 30 BlueGit stuurt op elk server-naar-server-verzoek `User-Agent: BlueGitAccountClient/0.1` en `Accept: application/json`.
27 31
28 ## Wat BlueGit bewaart
29
30 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. Een merge vanaf de website gebruikt daarom `{naam}@users.git.timfalken.com` als afzender. Het bearer-token blijft in de sessietabel tot afmelden of verlopen.
31
32 SSH-sleutels op de auth-server zijn er voor aanmelden dáár (`POST /api/ssh-login/challenge` en `/verify`, namespace `timfalken-account`). Er komt geen API waarmee een verbonden site die sleutels ophaalt. BlueGit houdt eigen sleutels bij voor git-over-SSH. Ze worden geplakt op de accountpagina.
33
34 ## Configuratie
32 ### Configuratie (oauth)
35 33
36 34 ```yaml
37 35 auth:
@@ -45,7 +43,61 @@ auth:
45 43
46 44 Een leeg `client_secret` valt terug op het bestand, en dat weer op `BLUEGIT_AUTH_CLIENT_SECRET`.
47 45
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.
46 ## Microsoft Entra ID (`mode: entra`)
47
48 Entra is wél OpenID Connect. BlueGit gebruikt de authorization-code-flow met `scope=openid profile`, controleert `state` in de cookie, en controleert in het ID-token `nonce`, handtekening (JWKS, RS256), `iss`, `aud` en `exp`. Alleen één tenant: zet `tenant_id` op de directory-id van die tenant.
49
50 ### App-registratie
51
52 1. Registreer een app in Entra (één tenant). Zet het platform op Web.
53 2. Redirect-URI: `{base_url}{redirect_path}`, bijvoorbeeld `https://git.voorbeeld.nl/auth/callback`.
54 3. Maak een clientgeheim aan. Zelfde geheimenketen als bij oauth: veld, `client_secret_file`, of `BLUEGIT_AUTH_CLIENT_SECRET`.
55 4. Geen aparte Graph-rechten nodig voor aanmelden. Avatar via Graph zit er niet in.
56
57 ### Configuratie (entra)
58
59 ```yaml
60 auth:
61 mode: entra
62 tenant_id: 00000000-0000-0000-0000-000000000000
63 client_id: 11111111-1111-1111-1111-111111111111
64 client_secret: ""
65 client_secret_file: /etc/bluegit/client_secret
66 redirect_path: /auth/callback
67 # issuer alleen zetten voor een andere cloud of een testissuer.
68 # Leeg = https://login.microsoftonline.com/{tenant_id}/v2.0
69 # issuer: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0
70 ```
71
72 Ontbreekt `tenant_id`, `client_id` of het clientgeheim, dan weigert BlueGit te starten met een duidelijke fout. `auth.base_url` hoort bij oauth en wordt bij entra niet standaard op auth.timfalken.com gezet.
73
74 ### Identiteit → BlueGit-gebruiker
75
76 | BlueGit | Bron bij Entra |
77 | --- | --- |
78 | `auth_id` (numeriek) | Stabiele hash van `tid` + `oid` (valt terug op `sub` als `oid` ontbreekt) |
79 | `username` | Lokaal deel van `preferred_username` of `email`, gesaneerd naar kleine letters; anders `u` + korte hash van `oid` |
80 | `avatar_url` | Leeg (initialen in de UI) |
81 | `auth_admin` / IdP-`is_admin` | Altijd false; Entra-rollen maken niemand BlueGit-beheerder |
82
83 Installatiebeheerder blijft: alleen de eerste aangemelde gebruiker op deze installatie.
84
85 ### Wat er anders is onder Entra
86
87 - Geen `/api/me`, geen avatar-URL, geen `email_verified` van de auth-server.
88 - `Extend` verlengt alleen de BlueGit-sessie (24 uur); er is geen remote session-extend.
89 - `Logout` wist alleen de lokale sessie; het Entra-token wordt niet ingetrokken.
90 - Pipeline-falenmail via `POST /api/email` op auth.timfalken.com werkt niet (geen `Mailer` op de Entra-provider).
91
92 ## Wat BlueGit bewaart
93
94 Van het account: het numerieke auth-id, de gebruikersnaam in kleine letters, de avatar-URL (kan leeg zijn), en of die persoon op de auth-server beheerder is (`auth_admin`; bij Entra altijd false). Geen e-mail. Een merge vanaf de website gebruikt daarom `{naam}@users.git.timfalken.com` als afzender. Het bearer-token blijft in de sessietabel tot afmelden of verlopen.
95
96 SSH-sleutels op de auth-server zijn er voor aanmelden dáár (`POST /api/ssh-login/challenge` en `/verify`, namespace `timfalken-account`). Er komt geen API waarmee een verbonden site die sleutels ophaalt. BlueGit houdt eigen sleutels bij voor git-over-SSH. Ze worden geplakt op de accountpagina.
97
98 ## Dev-modus
99
100 `auth.mode: dev` slaat de ronde over en maakt een sessie voor `dev_user`. De configuratie weigert die modus als `base_url` (van de BlueGit-site) op `git.timfalken.com` staat.
49 101
50 102 ## Export
51 103
@@ -1,8 +1,12 @@
1# Koppeling met auth.timfalken.com
1# Aanmelden: auth.timfalken.com of Microsoft Entra ID
2
3BlueGit kent drie `auth.mode`-waarden: `oauth` (standaard, auth.timfalken.com), `entra` (Microsoft Entra ID, OIDC, één tenant) en `dev` (lokale sessie zonder IdP). Zonder nieuwe velden blijft alles zoals voorheen.
4
5## auth.timfalken.com (`mode: oauth`)
2
6
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.
7De 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
8
5## Wat een site moet doen
9### Wat een site moet doen
6
10
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.
111. 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.
122. 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.
@@ -25,13 +29,7 @@ grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&client_sec
25
29
26BlueGit stuurt op elk server-naar-server-verzoek `User-Agent: BlueGitAccountClient/0.1` en `Accept: application/json`.
30BlueGit stuurt op elk server-naar-server-verzoek `User-Agent: BlueGitAccountClient/0.1` en `Accept: application/json`.
27
31
28## Wat BlueGit bewaart
32### Configuratie (oauth)
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. Een merge vanaf de website gebruikt daarom `{naam}@users.git.timfalken.com` als afzender. 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 komt geen API waarmee een verbonden site die sleutels ophaalt. BlueGit houdt eigen sleutels bij voor git-over-SSH. Ze worden geplakt op de accountpagina.
33
34## Configuratie
35
33
36```yaml
34```yaml
37auth:
35auth:
@@ -45,7 +43,61 @@ auth:
45
43
46Een leeg `client_secret` valt terug op het bestand, en dat weer op `BLUEGIT_AUTH_CLIENT_SECRET`.
44Een leeg `client_secret` valt terug op het bestand, en dat weer op `BLUEGIT_AUTH_CLIENT_SECRET`.
47
45
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.
46## Microsoft Entra ID (`mode: entra`)
47
48Entra is wél OpenID Connect. BlueGit gebruikt de authorization-code-flow met `scope=openid profile`, controleert `state` in de cookie, en controleert in het ID-token `nonce`, handtekening (JWKS, RS256), `iss`, `aud` en `exp`. Alleen één tenant: zet `tenant_id` op de directory-id van die tenant.
49
50### App-registratie
51
521. Registreer een app in Entra (één tenant). Zet het platform op Web.
532. Redirect-URI: `{base_url}{redirect_path}`, bijvoorbeeld `https://git.voorbeeld.nl/auth/callback`.
543. Maak een clientgeheim aan. Zelfde geheimenketen als bij oauth: veld, `client_secret_file`, of `BLUEGIT_AUTH_CLIENT_SECRET`.
554. Geen aparte Graph-rechten nodig voor aanmelden. Avatar via Graph zit er niet in.
56
57### Configuratie (entra)
58
59```yaml
60auth:
61 mode: entra
62 tenant_id: 00000000-0000-0000-0000-000000000000
63 client_id: 11111111-1111-1111-1111-111111111111
64 client_secret: ""
65 client_secret_file: /etc/bluegit/client_secret
66 redirect_path: /auth/callback
67 # issuer alleen zetten voor een andere cloud of een testissuer.
68 # Leeg = https://login.microsoftonline.com/{tenant_id}/v2.0
69 # issuer: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0
70```
71
72Ontbreekt `tenant_id`, `client_id` of het clientgeheim, dan weigert BlueGit te starten met een duidelijke fout. `auth.base_url` hoort bij oauth en wordt bij entra niet standaard op auth.timfalken.com gezet.
73
74### Identiteit → BlueGit-gebruiker
75
76| BlueGit | Bron bij Entra |
77| --- | --- |
78| `auth_id` (numeriek) | Stabiele hash van `tid` + `oid` (valt terug op `sub` als `oid` ontbreekt) |
79| `username` | Lokaal deel van `preferred_username` of `email`, gesaneerd naar kleine letters; anders `u` + korte hash van `oid` |
80| `avatar_url` | Leeg (initialen in de UI) |
81| `auth_admin` / IdP-`is_admin` | Altijd false; Entra-rollen maken niemand BlueGit-beheerder |
82
83Installatiebeheerder blijft: alleen de eerste aangemelde gebruiker op deze installatie.
84
85### Wat er anders is onder Entra
86
87- Geen `/api/me`, geen avatar-URL, geen `email_verified` van de auth-server.
88- `Extend` verlengt alleen de BlueGit-sessie (24 uur); er is geen remote session-extend.
89- `Logout` wist alleen de lokale sessie; het Entra-token wordt niet ingetrokken.
90- Pipeline-falenmail via `POST /api/email` op auth.timfalken.com werkt niet (geen `Mailer` op de Entra-provider).
91
92## Wat BlueGit bewaart
93
94Van het account: het numerieke auth-id, de gebruikersnaam in kleine letters, de avatar-URL (kan leeg zijn), en of die persoon op de auth-server beheerder is (`auth_admin`; bij Entra altijd false). Geen e-mail. Een merge vanaf de website gebruikt daarom `{naam}@users.git.timfalken.com` als afzender. Het bearer-token blijft in de sessietabel tot afmelden of verlopen.
95
96SSH-sleutels op de auth-server zijn er voor aanmelden dáár (`POST /api/ssh-login/challenge` en `/verify`, namespace `timfalken-account`). Er komt geen API waarmee een verbonden site die sleutels ophaalt. BlueGit houdt eigen sleutels bij voor git-over-SSH. Ze worden geplakt op de accountpagina.
97
98## Dev-modus
99
100`auth.mode: dev` slaat de ronde over en maakt een sessie voor `dev_user`. De configuratie weigert die modus als `base_url` (van de BlueGit-site) op `git.timfalken.com` staat.
49
101
50## Export
102## Export
51
103
packaging/bluegit.yml +4 −0
@@ -23,6 +23,10 @@ auth:
23 23 client_secret_file: /etc/bluegit/client_secret
24 24 redirect_path: /auth/callback
25 25 user_agent: BlueGitAccountClient/0.1
26 # Alternatief: Microsoft Entra ID (OIDC, één tenant). Zie docs/AUTH.md.
27 # mode: entra
28 # tenant_id: 00000000-0000-0000-0000-000000000000
29 # client_id: 11111111-1111-1111-1111-111111111111
26 30
27 31 git:
28 32 binary: git
@@ -23,6 +23,10 @@ auth:
23 client_secret_file: /etc/bluegit/client_secret
23 client_secret_file: /etc/bluegit/client_secret
24 redirect_path: /auth/callback
24 redirect_path: /auth/callback
25 user_agent: BlueGitAccountClient/0.1
25 user_agent: BlueGitAccountClient/0.1
26 # Alternatief: Microsoft Entra ID (OIDC, één tenant). Zie docs/AUTH.md.
27 # mode: entra
28 # tenant_id: 00000000-0000-0000-0000-000000000000
29 # client_id: 11111111-1111-1111-1111-111111111111
26
30
27git:
31git:
28 binary: git
32 binary: git