Gå til hovedindhold

Brugerprovisionering med SCIM 2.0

Oversat fra den engelske original. Hvis de to versioner er forskellige, gælder den engelske. Oversættelsen er endnu ikke korrekturlæst af en dansk modersmålsbruger.

fremforge implementerer SCIM 2.0 (RFC 7643/7644), så din identitetsudbyder (IdP) automatisk kan oprette Forgejo-brugere i din organisation: oprettelse ved ansættelse, opdatering når en attribut ændres, og deaktivering ved fratrædelse. Slut med “John er lige stoppet, var der nogen, der huskede at fjerne hans adgang til fremforge?” Når din IdP deaktiverer brugeren, skifter SCIM-flaget active, og fremforge deaktiverer Forgejo-brugeren i samme minut.

SCIM bruges sammen med OIDC eller SAML og erstatter ingen af dem. SCIM er protokollen til provisionering: den sender brugerposter ind i fremforge. Brugerne logger stadig ind via det login-forløb, du har konfigureret separat (OIDC, anbefalet eller SAML). De fleste små teams har slet ikke brug for SCIM. Det er helt fint at administrere brugerne manuelt i Forgejos brugerflade. Sæt først SCIM op, når “vi har lige ansat fem nye, var der nogen, der huskede at oprette dem i fremforge?” bliver et reelt problem.

Denne side er vejledningen til at forbinde Okta, Entra, Authentik eller en hvilken som helst anden SCIM 2.0-IdP. Det virker uden videre med de store IdP’er og med enhver SCIM 2.0-klient.

Funktioner

FunktionUnderstøttet
POST /Users (opret)✓
GET /Users/:id (opslag)✓
GET /Users (liste, med filteret userName eq)✓
PATCH /Users/:id (operationer efter RFC 7644 §3.5.2)✓
PUT /Users/:id (fuld erstatning)✓
DELETE /Users/:id (deaktivering, ikke permanent sletning)✓
GET /ServiceProviderConfig✓
GET /ResourceTypes, GET /Schemas (discovery)✓
POST /Groups / GET /Groups / GET /Groups/:id✓
PATCH /Groups/:id (tilføj/fjern medlemmer)✓
PUT /Groups/:id (fuld erstatning)✓
DELETE /Groups/:id (sletter Forgejo-teamet og soft-sletter mapningen)✓
Gruppefilteret displayName eq✓
Bulk-endpoints✗ Endnu ikke
Filteroperatorer ud over eq✗ Brug flere requests
Indlejrede grupper✗ Forgejo har ikke begrebet

Opsætning

Trin 1: slå SCIM til i fremforge

  1. Administration → SSO → SCIM 2.0-brugeroprettelse → klik på Slå SCIM til og opret token.
  2. Siden viser bearer-tokenet én gang. Kopiér det; du skal bruge det i din IdP. fremforge viser IKKE tokenet igen efter denne omdirigering (kun dets SHA-256-hash gemmes). Hvis du mister det, så klik på Rotér token for at oprette et nyt.
  3. Notér den Basis-URL, der står på siden. Den ser sådan ud:
    https://frem.sh/<your-org>/scim/v2

Trin 2: forbind din IdP

Okta

  1. Applications → Create App Integration → SCIM 2.0 Test App (Header Auth).
  2. Fanen 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 skal melde succes.
  4. Fanen To App → slå Create, Update og Deactivate til.
  5. Tildel brugere til appen. Okta sender dem med POST til fremforge.

Microsoft Entra (Azure AD)

  1. Enterprise Applications → New application → Non-gallery → kald den “fremforge”.
  2. Provisioning → Get started → mode = Automatic:
    • Tenant URL: https://frem.sh/<your-org>/scim/v2
    • Secret Token: <token from step 1> (indsæt uden præfikset Bearer ; Entra tilføjer det selv)
  3. Test Connection → grønt flueben.
  4. Mappings → brug standardmapningen for User; det eneste felt, der ofte skal justeres, er userName, som du sætter til userPrincipalName (brugerens login i e-mailformat).
  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. Knyt provideren til din Application, og tildel en gruppe; brugerne i den gruppe bliver oprettet.

Generisk SCIM 2.0-IdP

Enhver klient, der understøtter det almindelige Authorization: Bearer <token>-format mod en SCIM 2.0-basis-URL, virker. fremforge oplyser sine funktioner på:

GET /<your-org>/scim/v2/ServiceProviderConfig
  • se svaret igennem for at bekræfte, hvad der understøttes, før du integrerer.

Hvad sker der ved provisionering

Når din IdP sender en bruger med POST:

  1. fremforge opretter en Forgejo-bruger (brugernavnet afledes af SCIM-feltet userName; navne i e-mailformat renses efter Forgejos regel [a-z0-9-], f.eks. alice@acme.com → alice-acme-com).
  2. Brugeren tilføjes til organisationens standardteam Members. Brugeren bliver IKKE forfremmet til Owner. Forfremmelse til administrator sker fortsat hos operatøren.
  3. Brugeren logger ind via jeres eksisterende OIDC- eller SAML-autentificeringskilde (sat op separat på SSO-siden). SCIM opretter brugerposten; login-forløbet på IdP-siden logger brugeren ind.
  4. fremforge skriver en audit_events-række med handlingen scim.user.create. Den kan ses på admin-fanen Revisionslog.

Når din IdP deaktiverer en bruger (PATCH active=false eller DELETE):

  1. fremforge sætter prohibit_login=true på Forgejo-brugeren. Sessioner tilbagekaldes, og fremtidige logins afvises.
  2. Brugerens SSH-nøgler bliver liggende i Forgejo (de kan ikke bruges til push, fordi brugeren er låst).
  3. Medlemskabet af organisationen bevares af hensyn til revisionssporet. For at fjerne brugeren helt klikker en organisationsadministrator på Remove from org i Forgejos brugerflade.

Gruppeprovisionering

Når din IdP opretter en SCIM-gruppe, gør fremforge følgende:

  1. Opretter et Forgejo-team i jeres tenant-organisation. Teamnavnet afledes af gruppens displayName (renset efter Forgejos regel [a-z0-9_-], højst 30 tegn).
  2. Registrerer mapningen i scim_groups, så fremtidige PATCH-, PUT- og DELETE-operationer peger tilbage på det samme Forgejo-team.
  3. Tillader PATCH-operationer på members med op=add / op=remove (RFC 7644 §3.5.2 + kortformen members[value eq "<id>"]).
  4. DELETE /Groups/:id sletter det underliggende Forgejo-team. Databaserækken soft-slettes (deleted_at), så mapningen mellem externalId og team overlever, hvis den samme IdP-gruppe oprettes igen.

Hvert Forgejo-team giver som standard sine medlemmer skriveadgang til alle repos i organisationen (så en “Backend”-gruppe ender med skriveadgang til alle repos). Mere finkornet adgang pr. repo konfigureres hos operatøren i Forgejos teamindstillinger; fremforges SCIM sender ikke rettigheder pr. repo, fordi SCIM 2.0 ikke har en standard for attributter om repo-rettigheder.

Begrænsninger ved lanceringen:

  • E-mail er brugernøglen. SCIM identificerer brugere ved externalId, som vi forventer svarer til brugerens primære e-mail. Det passer med vores eksisterende OIDC-indstilling username_claim.
  • Ingen Just-in-Time-provisionering ved ren SAML. Hvis I kun bruger SAML, så sæt SCIM op som en ekstra connector til livscyklussen: SAML håndterer login, SCIM håndterer brugernes livscyklus.
  • Ingen indlejrede grupper. Forgejos teammodel er flad (en bruger er enten med i et team eller ej). Indlejrede gruppehierarkier fra din IdP bliver fladet ud: en bruger i Engineering → Backend → API bliver medlem af alle tre tilsvarende Forgejo-teams.

Rotation af token

SCIM-bearer-tokens bør roteres jævnligt. fremforge understøtter rotation uden nedetid, hvor to tokens er gyldige i en overgangsperiode:

  1. Administration → SSO → SCIM → klik på Rotér token.
  2. Det nye token vises én gang; kopiér det.
  3. Det forrige token er gyldigt, indtil du klikker på Drop forrige token. Overgangsperioden lader din IdP skifte til det nye token uden at tabe provisioneringskald, der er undervejs.
  4. Opdatér din IdP med det nye token.
  5. Når du har bekræftet, at det nye token virker (følg provisioneringsstatus på IdP-siden i et par cyklusser), klikker du på Drop forrige token.

Anbefalet interval: hver 90. dag, eller når personaleændringer giver anledning til at rotere legitimationsoplysninger.

Slå SCIM fra

Administration → SSO → SCIM → klik på Slå SCIM fra. fremforge:

  • Sletter både det nuværende og det forrige tokens hash (et ventende IdP-request får 401)
  • Markerer rækken enabled=false (synligt i revisionsloggen)
  • Lader scim_users-rækkerne være (når SCIM slås til igen, provisionerer din IdP på ny)

Selve Forgejo-brugerne bliver IKKE deaktiveret. Hvis du vil lukke dem alle ude, så gør det først fra din IdP, og slå derefter SCIM fra.

Fejlfinding

“Authorization: Bearer required” (401) på hvert request

Bearer-tokenet når ikke frem til fremforge. Typiske årsager:

  • Forkert header-navn: det skal være præcis Authorization.
  • Manglende præfiks Bearer : Okta tilføjer det automatisk, men det gør ikke alle klienter. Tjek med tcpdump eller IdP’ens detaljerede logs, hvad din IdP faktisk sender.
  • Tilbagekaldt token: hvis du har roteret og droppet det forrige token, virker det gamle ikke længere. Indsæt det nuværende igen.

“userName is required” (400) ved POST

Din IdP mapper ikke userName til en brugbar værdi. I Entra betyder det ofte, at brugerens UPN ikke er sat; map userName til mail eller en lignende attribut, der ikke er tom.

Brugerne er oprettet, men kan ikke logge ind

SCIM opretter kun brugerposten. Login-forløbet bruger jeres separat konfigurerede OIDC- eller SAML-autentificeringskilde. Kontrollér, at:

  1. Der er sat en OIDC- eller SAML-autentificeringskilde op under Administration → SSO → Autentificeringskilder.
  2. Brugerens identitet på IdP-siden (e-mail, principal name) svarer til det userName, du har provisioneret via SCIM.
  3. IdP-loginskærmen på frem.sh/user/login?redirect_to=/<your-org> viser SSO-knappen.

Filteret virker ikke for email eq eller andre operatorer

Vi understøtter kun userName eq "<value>". Alt andet giver en tom liste. De fleste IdP’er har kun brug for userName eq til at undgå dubletter; tjek i deres provisioneringslogs, hvilke filterformer de sender, og sig til, hvis du har brug for flere operatorer (skriv til support@frem.sh).

Revisionsspor

Alle handlinger, som SCIM udløser, registreres i organisationens revisionslog med actor=system (fordi aktøren er “din IdP”, ikke en indlogget bruger) og en af følgende:

  • scim.enabled / scim.disabled, handlinger i operatørens brugerflade
  • scim.token.rotated / scim.token.previous-dropped, handlinger i operatørens brugerflade
  • scim.user.create, POST fra IdP’en
  • scim.user.update / scim.user.replace, PATCH/PUT fra IdP’en
  • scim.user.deactivate / scim.user.reactivate, ændring af active-flaget fra IdP’en
  • scim.group.create / scim.group.update / scim.group.replace / scim.group.delete, gruppens livscyklus fra IdP’en
  • de samme handlinger kommer med i revisionsdelen af dataeksporten

Krydshenvisninger