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, 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.
App-registratie
1. Registreer een app in Entra (één tenant). Zet het platform op Web. 2. Redirect-URI: {base_url}{redirect_path}, bijvoorbeeld https://git.voorbeeld.nl/auth/callback. 3. Maak een clientgeheim aan. Zelfde geheimenketen als bij oauth: veld, client_secret_file, of BLUEGIT_AUTH_CLIENT_SECRET. 4. Geen aparte Graph-rechten nodig voor aanmelden. Avatar via Graph zit er niet in.
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.
Identiteit → BlueGit-gebruiker
| BlueGit | Bron bij Entra |
|---|---|
auth_id (numeriek) | Stabiele hash van tid + oid (valt terug op sub als oid ontbreekt) |
username | Lokaal deel van preferred_username of email, gesaneerd naar kleine letters; anders u + korte hash van oid |
avatar_url | Leeg (initialen in de UI) |
auth_admin / IdP-is_admin | Altijd false; Entra-rollen maken niemand BlueGit-beheerder |
Installatiebeheerder blijft: alleen de eerste aangemelde gebruiker op deze installatie.
Wat er anders is onder Entra
- Geen
/api/me, geen avatar-URL, geenemail_verifiedvan de auth-server. Extendverlengt alleen de BlueGit-sessie (24 uur); er is geen remote session-extend.Logoutwist alleen de lokale sessie; het Entra-token wordt niet ingetrokken.- Pipeline-falenmail via
POST /api/emailop auth.timfalken.com werkt niet (geenMailerop 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 | |
| 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`) |
| 6 | |
| 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. |
| 8 | |
| 9 | ### Wat een site moet doen |
| 10 | |
| 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. |
| 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. |
| 13 | 3. De browser gaat naar `GET /oauth/authorize` met `client_id`, `redirect_uri`, `response_type=code` en een verplichte `state`. |
| 14 | 4. De callback controleert `state` en wisselt de code server-side: |
| 15 | |
| 16 | ```http |
| 17 | POST /oauth/token |
| 18 | Content-Type: application/x-www-form-urlencoded |
| 19 | Accept: application/json |
| 20 | User-Agent: BlueGitAccountClient/0.1 |
| 21 | |
| 22 | grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&client_secret=… |
| 23 | ``` |
| 24 | |
| 25 | 5. Het antwoord bevat `access_token`, `expires_in` (86400) en `user` met `id`, `username` en `avatar_url`. Geen e-mailadres. |
| 26 | 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. |
| 27 | 7. `POST /api/session/extend` schuift de 24 uur op. `POST /api/logout` trekt het token in. |
| 28 | 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`). |
| 29 | |
| 30 | BlueGit stuurt op elk server-naar-server-verzoek `User-Agent: BlueGitAccountClient/0.1` en `Accept: application/json`. |
| 31 | |
| 32 | ### Configuratie (oauth) |
| 33 | |
| 34 | ```yaml |
| 35 | auth: |
| 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 | |
| 44 | Een leeg `client_secret` valt terug op het bestand, en dat weer op `BLUEGIT_AUTH_CLIENT_SECRET`. |
| 45 | |
| 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. |
| 101 | |
| 102 | ## Export |
| 103 | |
| 104 | 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. |