Gå til hovedinnhold

Brukerprovisjonering med SCIM 2.0

fremforge implementerer SCIM 2.0 (RFC 7643/7644), slik at IdP-en din automatisk kan provisjonere Forgejo-brukere inn i organisasjonen: opprette ved ansettelse, oppdatere når attributter endres, deaktivere når noen slutter. Ikke mer «John har nettopp sluttet, husket noen å tilbakekalle fremforge-tilgangen hans?» Deaktivering i IdP-en endrer SCIM-flagget active, og fremforge deaktiverer Forgejo-brukeren i løpet av samme minutt.

SCIM fungerer sammen med OIDC; det erstatter det ikke. SCIM er protokollen for provisjonering. Den sender brukerposter inn i fremforge. Brukerne logger fortsatt inn via innloggingsflyten du har konfigurert separat (OIDC). De fleste små team trenger ikke SCIM i det hele tatt. Manuell brukeradministrasjon i Forgejos brukergrensesnitt er helt greit. Sett opp SCIM først når «vi har nettopp ansatt fem personer, husket noen å legge dem inn i fremforge?» blir et reelt problem.

Denne siden er en praktisk veiledning for å koble til Okta / Entra / Authentik / en hvilken som helst SCIM 2.0-IdP. Det virker rett ut av boksen med de store IdP-ene og fungerer med alle SCIM 2.0-klienter.

Funksjoner

FunksjonStøttes
POST /Users (provisjonering)✓
GET /Users/:id (oppslag)✓
GET /Users (liste, med filteret userName eq)✓
PATCH /Users/:id (operasjoner etter RFC 7644 §3.5.2)✓
PUT /Users/:id (full erstatning)✓
DELETE /Users/:id (deaktivering, ikke permanent sletting)✓
GET /ServiceProviderConfig✓
GET /ResourceTypes, GET /Schemas (oppdagelse)✓
POST /Groups / GET /Groups / GET /Groups/:id✓
PATCH /Groups/:id (legge til / fjerne medlemmer)✓
PUT /Groups/:id (full erstatning)✓
DELETE /Groups/:id (sletter Forgejo-teamet og myk-sletter koblingen)✓
Gruppefilteret displayName eq✓
Bulk-endepunkter✗ Ikke ennå
Filteroperatorer utover eq✗ Bruk flere forespørsler
Nestede grupper✗ Forgejo modellerer dem ikke

Oppsett

Trinn 1: slå på SCIM i fremforge

  1. Organisasjonsadministrasjon → SSO → Brukerprovisjonering med SCIM 2.0 → klikk Aktiver SCIM og lag token.
  2. Siden som svarer på klikket, viser bearer-tokenet én gang. Kopier det; du trenger det i IdP-en din. Tokenet legges aldri i en URL, og fremforge viser det ikke igjen: bare SHA-256-hashen lagres. Hvis du mister det, klikker du Rotate token for å utstede et nytt.
  3. Noter Base URL som vises på siden. Den ser slik ut:
    https://frem.sh/<your-org>/scim/v2

Trinn 2: koble til IdP-en din

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 at det lyktes.
  4. Fanen To App → slå på Create, Update, Deactivate.
  5. Tildel brukere til appen. Okta sender dem med POST til fremforge.

Microsoft Entra (Azure AD)

  1. Enterprise Applications → New application → Non-gallery → gi den navnet «fremforge».
  2. Provisioning → Get started → modus = Automatic:
    • Tenant URL: https://frem.sh/<your-org>/scim/v2
    • Secret Token: <token from step 1> (lim inn uten prefikset Bearer ; Entra legger det til)
  3. Test Connection → grønn hake.
  4. Mappings → bruk standardkoblingen for User; det eneste feltet som ofte må justeres, er userName. Sett det til userPrincipalName (brukerens innlogging i e-postformat).
  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. Knytt provideren til applikasjonen din og tildel en gruppe; brukerne i den gruppen blir provisjonert.

Generisk SCIM 2.0-IdP

Alle klienter som støtter standardformen Authorization: Bearer <token> mot en SCIM 2.0-base-URL, fungerer. fremforge oppgir hva som støttes, her:

GET /<your-org>/scim/v2/ServiceProviderConfig
  • se på det svaret for å kontrollere hva som støttes, før du integrerer.

Hva som skjer under provisjonering

Når IdP-en din sender en bruker med POST:

  1. fremforge oppretter en Forgejo-bruker (brukernavnet utledes fra SCIM-feltet userName; navn i e-postformat tilpasses Forgejos regler [a-z0-9-], for eksempel alice@acme.example → alice-acme-example).
  2. Brukeren legges til i organisasjonens standardteam Members. Brukeren forfremmes IKKE til Owner. Forfremmelse til administrator skjer på operatørsiden.
  3. Brukeren logger inn via den eksisterende OIDC-autentiseringskilden (satt opp separat på SSO-siden). SCIM oppretter brukerposten; innloggingsflyten hos IdP-en logger brukeren inn.
  4. fremforge skriver en rad i audit_events med handlingen scim.user.create. Den vises i adminfanen Audit log.

Når IdP-en deaktiverer en bruker (PATCH active=false eller DELETE):

  1. fremforge setter prohibit_login=true på Forgejo-brukeren. Sesjonene tilbakekalles, og nye innlogginger avvises.
  2. Brukerens SSH-nøkler blir liggende i Forgejo (de kan ikke brukes til å pushe, fordi brukeren er låst).
  3. Medlemskapet i organisasjonen beholdes for revisjonssporet. For å fjerne det helt klikker en organisasjonsadministrator Remove from org i Forgejos brukergrensesnitt.

Gruppeprovisjonering

Når IdP-en din oppretter en SCIM-gruppe, gjør fremforge følgende:

  1. Oppretter et Forgejo-team i kundeorganisasjonen din. Teamnavnet utledes fra gruppens displayName (tilpasset Forgejos regler [a-z0-9_-], høyst 30 tegn).
  2. Registrerer koblingen i scim_groups, slik at senere PATCH-, PUT- og DELETE-operasjoner peker tilbake til det samme Forgejo-teamet.
  3. Tillater PATCH-operasjoner 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-teamet. Databaseraden myk-slettes (deleted_at), slik at koblingen externalId↔team overlever om den samme IdP-gruppen opprettes på nytt.

Hvert Forgejo-team gir som standard medlemmene skrivetilgang til alle repositoryer i organisasjonen (så en «Backend»-gruppe ender opp med skrivetilgang til hvert repository). Finere tilgang per repository konfigureres på operatørsiden i Forgejos teaminnstillinger. SCIM i fremforge sender ikke tillatelser per repository, fordi SCIM 2.0 ikke har noen standard for attributter med repositorytillatelser.

Begrensninger ved lansering:

  • E-post er brukernøkkelen. SCIM identifiserer brukere med externalId, som vi forventer samsvarer med brukerens primære e-postadresse. Det stemmer med den eksisterende OIDC-innstillingen username_claim.
  • Ingen nestede grupper. Teammodellen i Forgejo er flat (en bruker er enten i et team eller ikke). Nestede grupper fra IdP-en flates ut: en bruker i Engineering → Backend → API blir medlem av alle de tre tilsvarende Forgejo-teamene.

Rotasjon av token

Bearer-tokener for SCIM bør roteres jevnlig. fremforge støtter rotasjon uten nedetid med et vindu der to tokener er gyldige:

  1. Organisasjonsadministrasjon → SSO → SCIM → klikk Roter token.
  2. Det nye tokenet vises én gang, på siden som svarer på klikket (aldri i en URL). Kopier det.
  3. Det forrige tokenet er gyldig til du klikker Drop previous token. Dette vinduet lar IdP-en bytte til det nye tokenet uten å miste provisjoneringskall som pågår.
  4. Oppdater IdP-en med det nye tokenet.
  5. Når du har bekreftet at det nye tokenet virker (sjekk provisjoneringsstatusen hos IdP-en over noen sykluser), klikker du Drop previous token.

Anbefalt kadens: hver 90. dag, eller ved personalendringer som tilsier at legitimasjon bør roteres.

Slå av SCIM

Organisasjonsadministrasjon → SSO → SCIM → klikk Deaktiver SCIM. fremforge:

  • Sletter både gjeldende og forrige token-hash (ventende forespørsler fra IdP-en får 401)
  • Merker raden enabled=false (synlig i revisjonen)
  • Lar radene i scim_users stå (slås SCIM på igjen, provisjoneres det på nytt fra IdP-en)

Selve Forgejo-brukerne deaktiveres IKKE. Hvis du vil stenge alle ute, gjør du det først i IdP-en og slår deretter av SCIM.

Feilsøking

«Authorization: Bearer required» (401) på hver forespørsel

Bearer-tokenet når ikke fram til fremforge. Vanlige årsaker:

  • Feil headernavn: det må være nøyaktig Authorization.
  • Manglende prefiks Bearer : Okta legger det til automatisk, noen klienter gjør det ikke. Sjekk hva IdP-en faktisk sender, med tcpdump eller IdP-ens detaljerte logger.
  • Tokenet er tilbakekalt: hvis du har rotert og fjernet det forrige, er det gamle tokenet dødt. Lim inn det gjeldende på nytt.

«userName is required» (400) ved POST

IdP-en din kobler ikke userName til en meningsfull verdi. I Entra betyr det ofte at brukerens UPN ikke er satt; koble userName til mail eller et lignende attributt som ikke er tomt.

Brukerne er provisjonert, men kan ikke logge inn

SCIM oppretter bare brukerposten. Innloggingsflyten bruker OIDC-autentiseringskilden du har konfigurert separat. Kontroller at:

  1. Det finnes en OIDC-autentiseringskilde under organisasjonsadministrasjon → SSO → Autentiseringskilder.
  2. Brukerens identitet hos IdP-en (e-post, principal name) samsvarer med userName som ble provisjonert med SCIM.
  3. Innloggingssiden på frem.sh/user/login?redirect_to=/<your-org> viser SSO-knappen.

Filteret virker ikke for email eq eller andre operatorer

Vi støtter bare userName eq "<value>". Alt annet gir en tom liste. De fleste IdP-er trenger bare userName eq for å unngå duplikater; sjekk i provisjoneringsloggene deres hvilke filterformer de sender, og gi oss beskjed hvis du trenger flere operatorer (skriv til support@frem.sh).

Revisjonsspor

Hver handling som SCIM utløser, registreres i organisasjonens revisjonslogg med actor=system (fordi aktøren er «IdP-en din», ikke en innlogget bruker) og én av disse:

  • scim.enabled / scim.disabled: handlinger i operatørens brukergrensesnitt
  • scim.token.rotated / scim.token.previous-dropped: handlinger i operatørens brukergrensesnitt
  • scim.user.create: POST fra IdP-en
  • scim.user.update / scim.user.replace: PATCH/PUT fra IdP-en
  • scim.user.deactivate / scim.user.reactivate: endring av active-flagget fra IdP-en
  • scim.group.create / scim.group.update / scim.group.replace / scim.group.delete: gruppens livssyklus fra IdP-en
  • de samme handlingene havner i revisjonsdelen av dataeksportpakken

Se også