docs: Entra-aanmelden in AUTH.md en voorbeeldconfigs
Co-authored-by: Cursor <cursoragent@cursor.com>
@@ -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.com1
# Aanmelden: auth.timfalken.com of Microsoft Entra ID2
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
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.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 doen9
### Wat een site moet doen6
10
7
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.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
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.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_sec25
29
26
BlueGit stuurt op elk server-naar-server-verzoek `User-Agent: BlueGitAccountClient/0.1` en `Accept: application/json`.30
BlueGit stuurt op elk server-naar-server-verzoek `User-Agent: BlueGitAccountClient/0.1` en `Accept: application/json`.27
31
28
## Wat BlueGit bewaart32
### Configuratie (oauth)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
## Configuratie35
33
36
```yaml34
```yaml37
auth:35
auth:@@ -45,7 +43,61 @@ auth:45
43
46
Een leeg `client_secret` valt terug op het bestand, en dat weer op `BLUEGIT_AUTH_CLIENT_SECRET`.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-registratie51
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
```yaml60
auth:61
mode: entra62
tenant_id: 00000000-0000-0000-0000-00000000000063
client_id: 11111111-1111-1111-1111-11111111111164
client_secret: ""65
client_secret_file: /etc/bluegit/client_secret66
redirect_path: /auth/callback67
# issuer alleen zetten voor een andere cloud of een testissuer.68
# Leeg = https://login.microsoftonline.com/{tenant_id}/v2.069
# issuer: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.070
```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-gebruiker75
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 Entra86
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 bewaart93
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-modus99
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
## Export102
## Export51
103
@@ -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_secret23
client_secret_file: /etc/bluegit/client_secret24
redirect_path: /auth/callback24
redirect_path: /auth/callback25
user_agent: BlueGitAccountClient/0.125
user_agent: BlueGitAccountClient/0.126
# Alternatief: Microsoft Entra ID (OIDC, één tenant). Zie docs/AUTH.md.27
# mode: entra28
# tenant_id: 00000000-0000-0000-0000-00000000000029
# client_id: 11111111-1111-1111-1111-11111111111126
30
27
git:31
git:28
binary: git32
binary: git