Hoppa till huvudinnehållet

Användarprovisionering med SCIM 2.0

fremforge implementerar SCIM 2.0 (RFC 7643/7644) så att din IdP automatiskt kan provisionera Forgejo-användare i din organisation: skapa vid anställning, uppdatera när attribut ändras, inaktivera när anställningen upphör. Inget mer “John har slutat, kom någon ihåg att återkalla hans åtkomst till fremforge?” När din IdP inaktiverar någon ändras SCIM-flaggan active, och fremforge inaktiverar Forgejo-användaren samma minut.

SCIM kompletterar OIDC; det ersätter det inte. SCIM är protokollet för provisionering. Det pushar användarposter till fremforge. Användarna loggar fortfarande in via ditt separat konfigurerade inloggningsflöde (OIDC). De flesta små team behöver inte SCIM alls. Manuell användarhantering i Forgejos gränssnitt fungerar bra. Sätt bara upp SCIM när “vi har just anställt fem personer, kom någon ihåg att lägga till dem i fremforge?” blir ett verkligt problem.

Den här sidan är fältguiden för att ansluta Okta, Entra, Authentik eller valfri IdP med SCIM 2.0. Det fungerar direkt med de stora IdP:erna och med vilken SCIM 2.0-klient som helst.

Funktioner

FunktionStöds
POST /Users (provisionera)✓
GET /Users/:id (slå upp)✓
GET /Users (lista, med filtret userName eq)✓
PATCH /Users/:id (operationer enligt RFC 7644 §3.5.2)✓
PUT /Users/:id (fullständig ersättning)✓
DELETE /Users/:id (inaktivera, inte permanent radering)✓
GET /ServiceProviderConfig✓
GET /ResourceTypes, GET /Schemas (upptäckt)✓
POST /Groups / GET /Groups / GET /Groups/:id✓
PATCH /Groups/:id (lägg till/ta bort medlemmar)✓
PUT /Groups/:id (fullständig ersättning)✓
DELETE /Groups/:id (raderar Forgejo-teamet + mjukraderar mappningen)✓
Gruppfilter displayName eq✓
Bulk-endpoints✗ Inte än
Filteroperatorer utöver eq✗ Använd flera anrop
Nästlade grupper✗ Forgejo modellerar dem inte

Konfiguration

Steg 1, slå på SCIM i fremforge

  1. Organisationens administration → SSO → SCIM 2.0-användarprovisionering → klicka på Slå på SCIM och skapa token.
  2. Sidan som svarar på klicket visar bearer-token en gång. Kopiera den; du behöver den för din IdP. Token läggs aldrig i en URL, och fremforge visar den inte igen: bara dess SHA-256-hash lagras. Om du tappar bort den klickar du på Rotera token för att skapa en ny.
  3. Notera Bas-URL som visas på sidan. Den ser ut så här:
    https://frem.sh/<your-org>/scim/v2

Steg 2, anslut din IdP

Okta

  1. Applications → Create App Integration → SCIM 2.0 Test App (Header Auth).
  2. Fliken 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 ska returnera ett lyckat resultat.
  4. Fliken To App → slå på Create, Update, Deactivate.
  5. Tilldela användare till appen. Okta skickar dem med POST till fremforge.

Microsoft Entra (Azure AD)

  1. Enterprise Applications → New application → Non-gallery → ge den namnet “fremforge”.
  2. Provisioning → Get started → läge = Automatic:
    • Tenant URL: https://frem.sh/<your-org>/scim/v2
    • Secret Token: <token from step 1> (klistra in utan prefixet Bearer ; Entra lägger till det)
  3. Test Connection → grön bock.
  4. Mappings → använd standardmappningen för User. Det enda fält som ofta behöver justeras är userName: sätt det till userPrincipalName (användarens inloggning i mejlformat).
  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. Koppla providern till din Application och tilldela en grupp; användarna i den gruppen provisioneras.

Generisk IdP med SCIM 2.0

Alla klienter som stöder standardformen Authorization: Bearer <token> mot en bas-URL för SCIM 2.0 fungerar. fremforge annonserar sina funktioner på:

GET /<your-org>/scim/v2/ServiceProviderConfig
  • granska det svaret för att se vad som stöds innan du integrerar.

Vad som händer vid provisionering

När din IdP skickar en användare med POST:

  1. fremforge skapar en Forgejo-användare (användarnamnet härleds från SCIM-attributet userName; namn i mejlformat anpassas till Forgejos regler [a-z0-9-], t.ex. alice@acme.example → alice-acme-example).
  2. Användaren läggs till i organisationens standardteam Members. Användaren befordras INTE till ägare. Befordran till administratör sköts av operatören.
  3. Användaren loggar in via din befintliga OIDC-autentiseringskälla (som konfigureras separat på SSO-sidan). SCIM skapar användarposten; inloggningsflödet hos IdP:n loggar in användaren.
  4. fremforge loggar en rad i audit_events med åtgärden scim.user.create. Den syns på fliken Granskningslogg i administrationen.

När din IdP inaktiverar en användare (PATCH active=false eller DELETE):

  1. fremforge sätter prohibit_login=true på Forgejo-användaren. Sessioner återkallas och framtida inloggningar nekas.
  2. Användarens SSH-nycklar ligger kvar i Forgejo (de kan inte användas för push eftersom användaren är låst).
  3. Medlemskapet i organisationen behålls för granskningsspåret. För att ta bort det helt klickar en organisationsadministratör på Remove from org i Forgejos gränssnitt.

Provisionering av grupper

När din IdP skapar en SCIM-grupp gör fremforge följande:

  1. Skapar ett Forgejo-team i din tenants organisation. Teamets namn härleds från gruppens displayName (anpassat till Forgejos regler [a-z0-9_-], högst 30 tecken).
  2. Registrerar mappningen i scim_groups, så att framtida PATCH-, PUT- och DELETE-operationer leder tillbaka till samma Forgejo-team.
  3. Tillåter PATCH-operationer på members med op=add / op=remove (RFC 7644 §3.5.2 + kortformen members[value eq "<id>"]).
  4. DELETE /Groups/:id raderar det underliggande Forgejo-teamet. Databasraden mjukraderas (deleted_at) så att mappningen externalId↔team överlever om samma IdP-grupp skapas igen.

Varje Forgejo-team ger som standard sina medlemmar skrivåtkomst till alla repon i organisationen (så en grupp “Backend” får skrivåtkomst till varje repo). Mer finkornig åtkomst per repo konfigureras av operatören i Forgejos teaminställningar. fremforges SCIM pushar inte behörigheter avgränsade till repon, eftersom SCIM 2.0 saknar standard för attribut för repo-behörigheter.

Begränsningar vid lansering:

  • Mejladressen är användarnyckeln. SCIM identifierar användare via externalId, som vi förväntar oss ska matcha användarens primära mejladress. Det stämmer överens med vår befintliga OIDC-inställning username_claim.
  • Inga nästlade grupper. Forgejos teammodell är platt (en användare är antingen med i ett team eller inte). Nästlade grupphierarkier från din IdP plattas ut: en användare i Engineering → Backend → API blir medlem i alla tre motsvarande Forgejo-team.

Rotation av token

Bearer-tokens för SCIM bör roteras med jämna mellanrum. fremforge stöder rotation utan avbrott med ett fönster för två tokens:

  1. Organisationens administration → SSO → SCIM → klicka på Rotera token.
  2. Den nya token visas en gång, på sidan som svarar på klicket (aldrig i en URL); kopiera den.
  3. Den tidigare token är giltig tills du klickar på Släpp tidigare token. Fönstret låter din IdP byta till den nya token utan att några pågående provisioneringsanrop går förlorade.
  4. Uppdatera din IdP med den nya token.
  5. När du har bekräftat att den nya token fungerar (kontrollera provisioneringens hälsa hos IdP:n under några cykler) klickar du på Släpp tidigare token.

Rekommenderat intervall: var 90:e dag, eller vid personalförändringar som motiverar rotation av inloggningsuppgifter.

Stänga av SCIM

Organisationens administration → SSO → SCIM → klicka på Stäng av SCIM. fremforge:

  • Rensar hasharna för både den aktuella och den tidigare token (alla väntande anrop från IdP:n får 401)
  • Markerar raden enabled=false (synligt i granskningen)
  • Lämnar raderna i scim_users orörda (när du slår på igen provisioneras de på nytt från din IdP)

Själva Forgejo-användarna inaktiveras INTE. Om du vill låsa ute alla gör du det först i din IdP och stänger sedan av SCIM.

Felsökning

“Authorization: Bearer required” (401) på varje anrop

Bearer-token når inte fremforge. Vanliga orsaker:

  • Fel namn på headern: det måste vara exakt Authorization.
  • Prefixet Bearer saknas: Okta lägger till det automatiskt, men vissa klienter gör det inte. Kontrollera vad din IdP faktiskt skickar med tcpdump eller IdP:ns utförliga loggar.
  • Token återkallad: om du har roterat och släppt den tidigare token är den gamla död. Klistra in den aktuella igen.

“userName is required” (400) vid POST

Din IdP mappar inte userName till ett meningsfullt värde. I Entra betyder det ofta att användarens UPN inte är satt; mappa userName till mail eller ett liknande attribut som inte är tomt.

Användare provisionerade men kan inte logga in

SCIM skapar bara användarposten. Inloggningsflödet använder din separat konfigurerade OIDC-autentiseringskälla. Kontrollera:

  1. Att användaren har en OIDC-autentiseringskälla konfigurerad under organisationens administration → SSO → Autentiseringskällor.
  2. Att användarens identitet hos IdP:n (mejladress, principal name) matchar det userName du provisionerade via SCIM.
  3. Att IdP:ns inloggningssida på frem.sh/user/login?redirect_to=/<your-org> visar SSO-knappen.

Filtret fungerar inte för email eq eller andra operatorer

Vi stöder bara userName eq "<value>". Allt annat returnerar en tom lista. De flesta IdP:er behöver bara userName eq för deduplicering. Kontrollera i deras provisioneringsloggar vilka filterformer de skickar och hör av dig om du behöver fler operatorer (skriv till support@frem.sh).

Granskningsspår

Varje åtgärd som drivs av SCIM registreras i organisationens granskningslogg med actor=system (eftersom aktören är “din IdP”, inte en inloggad användare) och en av följande:

  • scim.enabled / scim.disabled: åtgärder i operatörsgränssnittet
  • scim.token.rotated / scim.token.previous-dropped: åtgärder i operatörsgränssnittet
  • scim.user.create: POST från IdP:n
  • scim.user.update / scim.user.replace: PATCH/PUT från IdP:n
  • scim.user.deactivate / scim.user.reactivate: ändring av flaggan active från IdP:n
  • scim.group.create / scim.group.update / scim.group.replace / scim.group.delete: gruppens livscykel från IdP:n
  • samma åtgärder hamnar i granskningsdelen av dataexportpaketet

Korsreferenser