Naar de hoofdinhoud

Gebruikers inrichten met SCIM 2.0

fremforge implementeert SCIM 2.0 (RFC 7643/7644), zodat je IdP Forgejo-gebruikers automatisch in je organisatie kan inrichten: aanmaken bij indiensttreding, bijwerken bij gewijzigde attributen, deactiveren bij uitdiensttreding. Nooit meer “Jan is net vertrokken, heeft iemand eraan gedacht zijn toegang tot fremforge in te trekken?” Deactiveert je IdP iemand, dan wordt de SCIM-vlag active omgezet en deactiveert fremforge de Forgejo-gebruiker nog dezelfde minuut.

SCIM werkt samen met OIDC; het vervangt het niet. SCIM is het protocol voor inrichting. Het pusht gebruikersrecords naar fremforge. Gebruikers melden zich nog steeds aan via je apart ingestelde aanmeldflow (OIDC). De meeste kleine teams hebben SCIM helemaal niet nodig. Gebruikers handmatig beheren via de UI van Forgejo is prima. Richt SCIM pas in als “we hebben net vijf mensen aangenomen, heeft iemand eraan gedacht ze aan fremforge toe te voegen?” een echt probleem wordt.

Deze pagina is de praktische gids om Okta, Entra, Authentik of elke andere SCIM 2.0-IdP te koppelen. Plug-and-play voor de grote IdP’s; werkt met elke SCIM 2.0-client.

Mogelijkheden

MogelijkheidOndersteund
POST /Users (inrichten)✓
GET /Users/:id (opzoeken)✓
GET /Users (lijst, met filter userName eq)✓
PATCH /Users/:id (bewerkingen uit RFC 7644 §3.5.2)✓
PUT /Users/:id (volledig vervangen)✓
DELETE /Users/:id (deactiveren, niet definitief verwijderen)✓
GET /ServiceProviderConfig✓
GET /ResourceTypes, GET /Schemas (discovery)✓
POST /Groups / GET /Groups / GET /Groups/:id✓
PATCH /Groups/:id (leden toevoegen/verwijderen)✓
PUT /Groups/:id (volledig vervangen)✓
DELETE /Groups/:id (Forgejo-team verwijderen + koppeling zacht verwijderen)✓
Groepsfilter displayName eq✓
Bulk-endpoints✗ Nog niet
Filteroperatoren anders dan eq✗ Gebruik meerdere verzoeken
Geneste groepen✗ Forgejo kent ze niet

Instellen

Stap 1: schakel SCIM in fremforge in

  1. Organisatiebeheer → SSO → SCIM 2.0-gebruikersinrichting → klik op SCIM inschakelen en token aanmaken.
  2. De pagina die na de klik verschijnt, toont het bearer-token één keer. Kopieer het; je hebt het nodig voor je IdP. Het token komt nooit in een URL terecht en fremforge toont het niet opnieuw: alleen de SHA-256-hash ervan wordt opgeslagen. Ben je het kwijt, klik dan op Token roteren om een nieuw token aan te maken.
  3. Noteer de Basis-URL die op de pagina staat. Die ziet er zo uit:
    https://frem.sh/<your-org>/scim/v2

Stap 2: koppel je IdP

Okta

  1. Applications → Create App Integration → SCIM 2.0 Test App (Header Auth).
  2. Tabblad Provisioning → Configure API Integration:
    • Base URL: https://frem.sh/<your-org>/scim/v2
    • Authentication Mode: HTTP Header
    • HTTP Header Name: Authorization
    • HTTP Header Value: Bearer <token from step 1>
  3. Test API Credentials moet een succesmelding geven.
  4. Tabblad To App → schakel Create, Update en Deactivate in.
  5. Wijs gebruikers aan de app toe. Okta stuurt ze met een POST naar fremforge.

Microsoft Entra (Azure AD)

  1. Enterprise Applications → New application → Non-gallery → noem hem “fremforge”.
  2. Provisioning → Get started → modus = Automatic:
    • Tenant URL: https://frem.sh/<your-org>/scim/v2
    • Secret Token: <token from step 1> (plak het zonder het voorvoegsel Bearer ; Entra voegt dat zelf toe)
  3. Test Connection → groen vinkje.
  4. Mappings → gebruik de standaardkoppeling voor User; het enige veld dat vaak moet worden aangepast is userName: zet het op userPrincipalName (de aanmeldnaam van de gebruiker in de vorm van een e-mailadres).
  5. Save & Start provisioning.

Authentik

  1. Applications → Providers → Create → SCIM Provider:
    • URL: https://frem.sh/<your-org>/scim/v2
    • Token: <token from step 1>
  2. Koppel de provider aan je Application en wijs een groep toe; gebruikers in die groep worden ingericht.

Generieke SCIM 2.0-IdP

Elke client die de standaardvorm Authorization: Bearer <token> tegen een SCIM 2.0-basis-URL ondersteunt, werkt. fremforge maakt zijn mogelijkheden bekend op:

GET /<your-org>/scim/v2/ServiceProviderConfig

Bekijk dat antwoord om na te gaan wat wordt ondersteund voordat je de koppeling bouwt.

Wat er gebeurt bij het inrichten

Als je IdP een gebruiker met een POST aanlevert:

  1. fremforge maakt een Forgejo-gebruiker aan (de gebruikersnaam wordt afgeleid van de SCIM-waarde userName; namen in de vorm van een e-mailadres worden aangepast aan de regels [a-z0-9-] van Forgejo, bijvoorbeeld alice@acme.example → alice-acme-example).
  2. De gebruiker wordt toegevoegd aan het standaardteam Members van de organisatie. Hij wordt NIET gepromoveerd tot eigenaar. Promotie tot beheerder blijft aan de kant van de operator.
  3. De gebruiker meldt zich aan via je bestaande OIDC-authenticatiebron (die je apart instelt op de SSO-pagina). SCIM maakt het gebruikersrecord aan; de aanmeldflow aan de kant van de IdP meldt hem aan.
  4. fremforge schrijft een rij in audit_events met de actie scim.user.create. Zichtbaar op het beheertabblad Auditlog.

Als je IdP een gebruiker deactiveert (PATCH active=false of DELETE):

  1. fremforge zet prohibit_login=true op de Forgejo-gebruiker. Sessies worden ingetrokken en toekomstige aanmeldingen geweigerd.
  2. De SSH-sleutels van de gebruiker blijven in Forgejo staan (ze kunnen niet worden gebruikt om te pushen, omdat de gebruiker is geblokkeerd).
  3. Het lidmaatschap van de organisatie blijft bestaan voor het auditspoor. Om de gebruiker definitief te verwijderen, klikt een beheerder van de organisatie in de UI van Forgejo op Remove from org.

Groepen inrichten

Als je IdP een SCIM-groep aanmaakt, doet fremforge het volgende:

  1. Het maakt een Forgejo-team aan in de organisatie van je tenant. De teamnaam wordt afgeleid van de displayName van de groep (aangepast aan de regels [a-z0-9_-] van Forgejo, maximaal 30 tekens).
  2. Het legt de koppeling vast in scim_groups, zodat latere PATCH-, PUT- en DELETE-bewerkingen weer bij hetzelfde Forgejo-team uitkomen.
  3. Het staat PATCH-bewerkingen op members toe met op=add / op=remove (RFC 7644 §3.5.2 + de korte vorm members[value eq "<id>"]).
  4. DELETE /Groups/:id verwijdert het onderliggende Forgejo-team. De databaserij wordt zacht verwijderd (deleted_at), zodat de koppeling externalId↔team blijft bestaan als dezelfde IdP-groep opnieuw wordt aangemaakt.

Elk Forgejo-team geeft zijn leden standaard schrijftoegang tot alle repository’s in de organisatie (een groep “Backend” krijgt dus schrijftoegang tot elke repository). Fijnmaziger toegang per repository stel je als operator in via de teaminstellingen in Forgejo; fremforge-SCIM pusht geen rechten per repository, omdat SCIM 2.0 geen standaard heeft voor attributen met repositoryrechten.

Beperkingen bij de lancering:

  • E-mail is de gebruikerssleutel. SCIM identificeert gebruikers via externalId, waarvan we verwachten dat het overeenkomt met het primaire e-mailadres van de gebruiker. Dat sluit aan bij onze bestaande OIDC-instelling username_claim.
  • Geen geneste groepen. Het teammodel van Forgejo is plat (een gebruiker zit in een team of niet). Geneste groepshiërarchieën uit je IdP worden platgeslagen: een gebruiker in Engineering → Backend → API wordt lid van alle drie de bijbehorende Forgejo-teams.

Tokens roteren

SCIM-bearertokens horen periodiek te worden geroteerd. fremforge ondersteunt rotatie zonder onderbreking met een periode waarin twee tokens geldig zijn:

  1. Organisatiebeheer → SSO → SCIM → klik op Token roteren.
  2. Het nieuwe token wordt één keer getoond, op de pagina die na de klik verschijnt (nooit in een URL); kopieer het.
  3. Het vorige token blijft geldig totdat je op Vorig token laten vallen klikt. In die periode kan je IdP overstappen op het nieuwe token zonder dat lopende inrichtingsaanroepen mislukken.
  4. Werk je IdP bij met het nieuwe token.
  5. Klik op Vorig token laten vallen zodra je hebt vastgesteld dat het nieuwe token werkt (controleer een paar cycli lang de inrichtingsstatus aan de kant van de IdP).

Aanbevolen ritme: elke 90 dagen, of bij personeelswijzigingen die rotatie van inloggegevens rechtvaardigen.

SCIM uitschakelen

Organisatiebeheer → SSO → SCIM → klik op SCIM uitschakelen. fremforge:

  • wist de hashes van zowel het huidige als het vorige token (elk openstaand verzoek van de IdP krijgt 401);
  • markeert de rij met enabled=false (zichtbaar in de audit);
  • laat de rijen in scim_users intact (opnieuw inschakelen richt de gebruikers opnieuw in vanuit je IdP).

De Forgejo-gebruikers zelf worden NIET gedeactiveerd. Wil je ze allemaal buitensluiten, doe dat dan eerst vanuit je IdP en schakel daarna SCIM uit.

Problemen oplossen

“Authorization: Bearer required” (401) bij elk verzoek

Het bearer-token bereikt fremforge niet. Veelvoorkomende oorzaken:

  • Verkeerde headernaam: die moet precies Authorization zijn.
  • Ontbrekend voorvoegsel Bearer : Okta voegt het automatisch toe, sommige clients niet. Controleer met tcpdump of de uitgebreide logs van je IdP wat die werkelijk verstuurt.
  • Token ingetrokken: heb je geroteerd en het vorige token laten vallen, dan werkt het oude token niet meer. Plak het huidige opnieuw.

“userName is required” (400) bij POST

Je IdP koppelt userName niet aan een zinvolle waarde. In Entra betekent dit vaak dat de UPN van de gebruiker niet is ingesteld; koppel userName aan mail of een vergelijkbaar attribuut dat niet leeg is.

Gebruikers ingericht, maar ze kunnen zich niet aanmelden

SCIM maakt alleen het gebruikersrecord aan. De aanmeldflow gebruikt je apart ingestelde OIDC-authenticatiebron. Controleer:

  1. Of de gebruiker een OIDC-authenticatiebron heeft, ingesteld onder Organisatiebeheer → SSO → Auth-bronnen.
  2. Of de identiteit van de gebruiker aan de kant van de IdP (e-mailadres, principal name) overeenkomt met de userName die je via SCIM hebt ingericht.
  3. Of het aanmeldscherm op frem.sh/user/login?redirect_to=/<your-org> de SSO-knop toont.

Filter werkt niet voor email eq of andere operatoren

We ondersteunen alleen userName eq "<value>". Al het andere geeft een lege lijst terug. De meeste IdP’s hebben alleen userName eq nodig om dubbele gebruikers te voorkomen; kijk in hun inrichtingslogs welke filtervormen ze versturen en laat het ons weten als je extra operatoren nodig hebt (via support@frem.sh).

Auditspoor

Elke handeling via SCIM wordt vastgelegd in het auditlog van de organisatie met actor=system (de actor is immers “je IdP” en geen aangemelde gebruiker) en een van de volgende acties:

  • scim.enabled / scim.disabled: handelingen in de beheer-UI
  • scim.token.rotated / scim.token.previous-dropped: handelingen in de beheer-UI
  • scim.user.create: POST door de IdP
  • scim.user.update / scim.user.replace: PATCH/PUT door de IdP
  • scim.user.deactivate / scim.user.reactivate: wijziging van de vlag active door de IdP
  • scim.group.create / scim.group.update / scim.group.replace / scim.group.delete: levenscyclus van groepen door de IdP
  • dezelfde handelingen komen ook in het auditdeel van de gegevensexport terecht

Kruisverwijzingen