BlueGit

timfa bluegit

Files

bluegit / docs / AUTH.md

AUTH.md

AUTH.md 9.5 KiB Download Raw

Aanmelden: auth.timfalken.com of Microsoft Entra ID

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.

auth.timfalken.com (mode: oauth)

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. Dat wordt geen BlueGit-beheerder. Alleen de eerste aangemelde gebruiker van deze installatie is dat, en die vlag geeft geen toegang tot andermans repositories, groepen of geheimen. 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.

Configuratie (oauth)

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.

Microsoft Entra ID (mode: entra)

Entra is wél OpenID Connect. BlueGit gebruikt de authorization-code-flow met scope=openid profile email User.Read en PKCE S256. De login zet HttpOnly-cookies (bluegit_oauth_state, bluegit_oauth_nonce, bluegit_oauth_pkce; 600 seconden, Secure bij HTTPS, SameSite=Lax) en wist ze na de callback. In het ID-token controleert BlueGit: nonce, handtekening (JWKS, alleen RS256; none en HS256 worden geweigerd), iss, aud, verplichte exp (met 60 seconden klokverschuiving; ook nbf en iat als ze er zijn), en verplichte tid die case-insensitive gelijk moet zijn aan auth.tenant_id. authorization_endpoint, token_endpoint en jwks_uri moeten op dezelfde host staan als de issuer; bij een HTTPS-issuer moeten die eindpunten ook HTTPS zijn. Een zelfgezette auth.issuer moet HTTPS zijn, behalve op localhost (voor tests). Alleen één tenant: zet tenant_id op de Directory (tenant) ID van die directory.

Een korte checklist staat ook in de README.

App-registratie

1. Open het Microsoft Entra-beheercentrum → Identiteit → Toepassingen → App-registraties → Nieuwe registratie. 2. Kies één tenant (Accounts in this organizational directory only / single tenant). Multi-tenant is niet ondersteund. 3. Platform: Web. De redirect-URI moet exact {base_url}{auth.redirect_path} zijn. auth.redirect_path is standaard /auth/callback, bijvoorbeeld https://git.timfalken.com/auth/callback. Pad, schema en host moeten letterlijk overeenkomen. 4. Maak onder Certificates & secrets een client secret aan. Noteer de waarde (één keer zichtbaar) en de verloopdatum. 5. BlueGit vraagt de scopes openid, profile en email. Geen aparte Graph-rechten nodig voor aanmelden. Avatar via Graph zit er niet in. 6. Op het overzicht van de registratie staan de Directory (tenant) ID (auth.tenant_id) en de Application (client) ID (auth.client_id).

Configuratie (entra)

auth:
  mode: entra
  tenant_id: 00000000-0000-0000-0000-000000000000
  client_id: 11111111-1111-1111-1111-111111111111
  client_secret: ""
  client_secret_file: /etc/bluegit/client_secret
  redirect_path: /auth/callback
  # issuer alleen zetten voor een andere cloud of een testissuer.
  # Leeg = https://login.microsoftonline.com/{tenant_id}/v2.0
  # issuer: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0

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.

Het clientgeheim hoort in auth.client_secret, in auth.client_secret_file (bijvoorbeeld /etc/bluegit/client_secret, mode 0600) of in de omgevingsvariabele BLUEGIT_AUTH_CLIENT_SECRET (bijvoorbeeld /etc/bluegit/secret.env). Na een wijziging: systemctl restart bluegit.

De bestaande knop Aanmelden (navigatie, /login) start de Entra-flow zodra auth.mode: entra staat. Er is geen aparte knop.

Voeg onder API-machtigingen van de app-registratie Microsoft Graph → User.Read (gedelegeerd) toe en geef zo nodig admin-toestemming. Bij het aanmelden haalt BlueGit GET https://graph.microsoft.com/v1.0/me/photo/$value op (alleen die host, met een maximale grootte en typecontrole). Een 404 (geen foto) is geen fout: de UI gebruikt initialen. Een later opnieuw inloggen ververst de Graph-foto, maar overschrijft geen handmatig geüploade avatar.

Identiteit → BlueGit-gebruiker

BlueGitBron bij Entra
auth_id (numeriek)Stabiele hash van tid + oid (valt terug op sub als oid ontbreekt)
usernameLokaal deel van preferred_username of email, gesaneerd naar kleine letters; anders u + korte hash van oid
avatar_urlProfielfoto van Microsoft Graph, bewaard als lokale avatar; zonder foto (404) initialen in de UI. Een handmatig geüploade avatar wordt niet overschreven.
auth_admin / IdP-is_adminAltijd false; Entra-rollen maken niemand BlueGit-beheerder

Installatiebeheerder blijft: alleen de eerste aangemelde gebruiker op deze installatie.

Accountkoppeling loopt via tid + oid (de stabiele auth_id). Dezelfde Entra-gebruiker komt terug op het bestaande BlueGit-account, ook als de weergavenaam bij Entra verandert (als de nieuwe gebruikersnaam al bezet is, blijft de oude naam staan). Een nieuwe login waarvan de afgeleide gebruikersnaam al door een ander account bezet is, wordt geweigerd (err.userTaken). Er is geen overname via e-mail.

Veelvoorkomende fouten

  • Redirect-URI komt niet exact overeen (pad, schema, host, slash) → redirect mismatch, vaak AADSTS50011. Zet in Entra precies {base_url}{auth.redirect_path}.
  • Verlopen of verkeerd client secret → de token-exchange faalt. Maak een nieuw geheim, werk auth.client_secret_file of BLUEGIT_AUTH_CLIENT_SECRET bij, en herstart.
  • Verkeerde tenant: auth.tenant_id wijst naar een andere directory, of tid in het ID-token komt niet overeen → aanmelden wordt geweigerd.
  • Issuer of discovery-eindpunten niet op HTTPS (buiten localhost) of jwks_uri op een andere host dan de issuer → BlueGit start niet of weigert discovery.

Wat er anders is onder Entra

  • Geen /api/me, geen avatar-URL, geen email_verified van de auth-server.
  • Extend verlengt alleen de BlueGit-sessie (24 uur); er is geen remote session-extend.
  • Logout wist alleen de lokale sessie; het Entra-token wordt niet ingetrokken.
  • Pipeline-falenmail via POST /api/email op auth.timfalken.com werkt niet (geen Mailer op de Entra-provider).

Wat BlueGit bewaart

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.

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.

Dev-modus

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.

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# 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`)
6
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.
8
9### Wat een site moet doen
10
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.
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.
133. De browser gaat naar `GET /oauth/authorize` met `client_id`, `redirect_uri`, `response_type=code` en een verplichte `state`.
144. De callback controleert `state` en wisselt de code server-side:
15
16```http
17POST /oauth/token
18Content-Type: application/x-www-form-urlencoded
19Accept: application/json
20User-Agent: BlueGitAccountClient/0.1
21
22grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&client_secret=…
23```
24
255. Het antwoord bevat `access_token`, `expires_in` (86400) en `user` met `id`, `username` en `avatar_url`. Geen e-mailadres.
266. `GET /api/me` met `Authorization: Bearer` vult `is_admin`, `email_verified` en `passkey_only` aan. `is_admin` is beheerder van de auth-server. Dat wordt geen BlueGit-beheerder. Alleen de eerste aangemelde gebruiker van deze installatie is dat, en die vlag geeft geen toegang tot andermans repositories, groepen of geheimen.
277. `POST /api/session/extend` schuift de 24 uur op. `POST /api/logout` trekt het token in.
288. 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`).
29
30BlueGit stuurt op elk server-naar-server-verzoek `User-Agent: BlueGitAccountClient/0.1` en `Accept: application/json`.
31
32### Configuratie (oauth)
33
34```yaml
35auth:
36 mode: oauth
37 base_url: https://auth.timfalken.com
38 client_id: git.timfalken.com
39 client_secret_file: /etc/bluegit/client_secret
40 redirect_path: /auth/callback
41 user_agent: BlueGitAccountClient/0.1
42```
43
44Een leeg `client_secret` valt terug op het bestand, en dat weer op `BLUEGIT_AUTH_CLIENT_SECRET`.
45
46## Microsoft Entra ID (`mode: entra`)
47
48Entra is wél OpenID Connect. BlueGit gebruikt de authorization-code-flow met `scope=openid profile email User.Read` en PKCE S256. De login zet HttpOnly-cookies (`bluegit_oauth_state`, `bluegit_oauth_nonce`, `bluegit_oauth_pkce`; 600 seconden, `Secure` bij HTTPS, `SameSite=Lax`) en wist ze na de callback. In het ID-token controleert BlueGit: `nonce`, handtekening (JWKS, alleen RS256; `none` en HS256 worden geweigerd), `iss`, `aud`, verplichte `exp` (met 60 seconden klokverschuiving; ook `nbf` en `iat` als ze er zijn), en verplichte `tid` die case-insensitive gelijk moet zijn aan `auth.tenant_id`. `authorization_endpoint`, `token_endpoint` en `jwks_uri` moeten op dezelfde host staan als de issuer; bij een HTTPS-issuer moeten die eindpunten ook HTTPS zijn. Een zelfgezette `auth.issuer` moet HTTPS zijn, behalve op localhost (voor tests). Alleen één tenant: zet `tenant_id` op de Directory (tenant) ID van die directory.
49
50Een korte checklist staat ook in de [README](../README.md#microsoft-entra-id).
51
52### App-registratie
53
541. Open het [Microsoft Entra-beheercentrum](https://entra.microsoft.com) → Identiteit → Toepassingen → App-registraties → Nieuwe registratie.
552. Kies één tenant (*Accounts in this organizational directory only* / single tenant). Multi-tenant is niet ondersteund.
563. Platform: **Web**. De redirect-URI moet exact `{base_url}{auth.redirect_path}` zijn. `auth.redirect_path` is standaard `/auth/callback`, bijvoorbeeld `https://git.timfalken.com/auth/callback`. Pad, schema en host moeten letterlijk overeenkomen.
574. Maak onder *Certificates & secrets* een client secret aan. Noteer de waarde (één keer zichtbaar) en de verloopdatum.
585. BlueGit vraagt de scopes `openid`, `profile` en `email`. Geen aparte Graph-rechten nodig voor aanmelden. Avatar via Graph zit er niet in.
596. Op het overzicht van de registratie staan de **Directory (tenant) ID** (`auth.tenant_id`) en de **Application (client) ID** (`auth.client_id`).
60
61### Configuratie (entra)
62
63```yaml
64auth:
65 mode: entra
66 tenant_id: 00000000-0000-0000-0000-000000000000
67 client_id: 11111111-1111-1111-1111-111111111111
68 client_secret: ""
69 client_secret_file: /etc/bluegit/client_secret
70 redirect_path: /auth/callback
71 # issuer alleen zetten voor een andere cloud of een testissuer.
72 # Leeg = https://login.microsoftonline.com/{tenant_id}/v2.0
73 # issuer: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0
74```
75
76Ontbreekt `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.
77
78Het clientgeheim hoort in `auth.client_secret`, in `auth.client_secret_file` (bijvoorbeeld `/etc/bluegit/client_secret`, mode `0600`) of in de omgevingsvariabele `BLUEGIT_AUTH_CLIENT_SECRET` (bijvoorbeeld `/etc/bluegit/secret.env`). Na een wijziging: `systemctl restart bluegit`.
79
80De bestaande knop **Aanmelden** (navigatie, `/login`) start de Entra-flow zodra `auth.mode: entra` staat. Er is geen aparte knop.
81
82Voeg onder *API-machtigingen* van de app-registratie **Microsoft Graph → User.Read** (gedelegeerd) toe en geef zo nodig admin-toestemming. Bij het aanmelden haalt BlueGit `GET https://graph.microsoft.com/v1.0/me/photo/$value` op (alleen die host, met een maximale grootte en typecontrole). Een 404 (geen foto) is geen fout: de UI gebruikt initialen. Een later opnieuw inloggen ververst de Graph-foto, maar overschrijft geen handmatig geüploade avatar.
83
84### Identiteit → BlueGit-gebruiker
85
86| BlueGit | Bron bij Entra |
87| --- | --- |
88| `auth_id` (numeriek) | Stabiele hash van `tid` + `oid` (valt terug op `sub` als `oid` ontbreekt) |
89| `username` | Lokaal deel van `preferred_username` of `email`, gesaneerd naar kleine letters; anders `u` + korte hash van `oid` |
90| `avatar_url` | Profielfoto van Microsoft Graph, bewaard als lokale avatar; zonder foto (404) initialen in de UI. Een handmatig geüploade avatar wordt niet overschreven. |
91| `auth_admin` / IdP-`is_admin` | Altijd false; Entra-rollen maken niemand BlueGit-beheerder |
92
93Installatiebeheerder blijft: alleen de eerste aangemelde gebruiker op deze installatie.
94
95Accountkoppeling loopt via `tid` + `oid` (de stabiele `auth_id`). Dezelfde Entra-gebruiker komt terug op het bestaande BlueGit-account, ook als de weergavenaam bij Entra verandert (als de nieuwe gebruikersnaam al bezet is, blijft de oude naam staan). Een *nieuwe* login waarvan de afgeleide gebruikersnaam al door een ander account bezet is, wordt geweigerd (`err.userTaken`). Er is geen overname via e-mail.
96
97### Veelvoorkomende fouten
98
99- Redirect-URI komt niet exact overeen (pad, schema, host, slash) → redirect mismatch, vaak AADSTS50011. Zet in Entra precies `{base_url}{auth.redirect_path}`.
100- Verlopen of verkeerd client secret → de token-exchange faalt. Maak een nieuw geheim, werk `auth.client_secret_file` of `BLUEGIT_AUTH_CLIENT_SECRET` bij, en herstart.
101- Verkeerde tenant: `auth.tenant_id` wijst naar een andere directory, of `tid` in het ID-token komt niet overeen → aanmelden wordt geweigerd.
102- Issuer of discovery-eindpunten niet op HTTPS (buiten localhost) of `jwks_uri` op een andere host dan de issuer → BlueGit start niet of weigert discovery.
103
104### Wat er anders is onder Entra
105
106- Geen `/api/me`, geen avatar-URL, geen `email_verified` van de auth-server.
107- `Extend` verlengt alleen de BlueGit-sessie (24 uur); er is geen remote session-extend.
108- `Logout` wist alleen de lokale sessie; het Entra-token wordt niet ingetrokken.
109- Pipeline-falenmail via `POST /api/email` op auth.timfalken.com werkt niet (geen `Mailer` op de Entra-provider).
110
111## Wat BlueGit bewaart
112
113Van 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.
114
115SSH-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.
116
117## Dev-modus
118
119`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.
120
121## Export
122
123Het 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.