Hoppa till huvudinnehållet

Single sign-on med OIDC

fremforge stöder OpenID Connect (OIDC) för single sign-on. OIDC är det protokoll för single sign-on som fremforge stöder. Alla större IdP:er (Entra, Okta, Google Workspace, Auth0, Authentik, Keycloak) har inbyggt stöd för OIDC. Livscykeln för signeringsnycklar sköts automatiskt via OIDC:s discovery- och JWKS-endpoints.

OIDC är i dag det enda protokollet för single sign-on som fremforge erbjuder. SAML finns inte ännu; både Microsoft Entra ID och ADFS stöder OIDC.

Konfiguration

Steg 1: verifiera en domän

Organisationens administration → SSO → Verifierade domäner (fäll ut det hopfällda avsnittet) → lägg till din mejldomän (t.ex. acme.com). Visa att du kontrollerar den på något av följande sätt:

  • DNS TXT-post: lägg till _fremforge-verification=<token> i domänens DNS och klicka sedan på Verify.
  • HTTP-fil: publicera token på https://acme.com/.well-known/fremforge-verification och klicka sedan på Verify.

Domänen måste vara verifierad innan du kan registrera en autentiseringskälla. Det gör du bara en gång.

Steg 2: skapa en OAuth 2.0-applikation i din IdP

fremforge behöver tre värden från din IdP: Client ID, Client Secret och utfärdar-URL:en (även kallad roten för OIDC-discovery-URL:en). Konfigurera din IdP enligt nedan.

Okta

  1. Applications → Create App Integration → OIDC, Web Application.
  2. Sign-in redirect URIs: https://frem.sh/user/oauth2/<auth-source-name>/callback
  3. Sign-out redirect URIs: https://frem.sh/<your-org>/logout (valfritt men rekommenderas)
  4. Assignments: tilldela applikationen till de grupper eller användare som ska ha åtkomst till fremforge.
  5. Kopiera Client ID, Client Secret och Okta-domänen (t.ex. https://acme.okta.com).
    • Utfärdar-URL = https://acme.okta.com (eller https://acme.okta.com/oauth2/default för egna auktoriseringsservrar)

Microsoft Entra (Azure AD)

  1. App registrations → New registration, namn “fremforge”, kontotyper som stöds = en enda tenant.
  2. Redirect URI: Web → https://frem.sh/user/oauth2/<auth-source-name>/callback
  3. Certificates & secrets → New client secret; kopiera Value direkt (visas bara en gång).
  4. Overview: kopiera Application (client) ID och Directory (tenant) ID.
    • Utfärdar-URL = https://login.microsoftonline.com/<tenant-id>/v2.0
  5. Token configuration → Add groups claim, välj Security groups. Det fyller i groups-claimet som används för att mappa till team i fremforge.
  6. API permissions: kontrollera att openid, profile och email är beviljade (det är de som standard).

ADFS

ADFS på Windows Server 2016 och senare är en OpenID Connect-leverantör.

  1. AD FS Management → Application Groups → Add Application Group, namn “fremforge”, mall Server application (under Standalone applications) eller Server application accessing a web API.
  2. Kopiera Client Identifier. Redirect URI: https://frem.sh/user/oauth2/<auth-source-name>/callback.
  3. Configure Application Credentials → Generate a shared secret; kopiera den (visas bara en gång).
  4. Bevilja scopen openid, profile och email, och lägg till regler för issuance transform som lägger email och name (och ett grupp-claim, om du mappar team) i ID-token.
    • Utfärdar-URL = https://<your-adfs-host>/adfs (discovery på https://<your-adfs-host>/adfs/.well-known/openid-configuration)

MFA-verifiering via OIDC har ännu inte testats mot ADFS. Slå på den för en testanvändare först och kontrollera att inloggningen lyckas.

Google Workspace

  1. Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID.
  2. Applikationstyp: Web application.
  3. Authorised redirect URIs: https://frem.sh/user/oauth2/<auth-source-name>/callback
  4. Kopiera Client ID och Client Secret.
    • Utfärdar-URL = https://accounts.google.com
  5. Under Google Workspace Admin → Security → API controls → Domain-wide delegation begränsar du OAuth-samtycket till din domän, så att bara medlemmar i din Workspace kan autentisera sig.

Authentik

  1. Applications → Providers → Create → OAuth2/OpenID Connect Provider.
  2. Redirect URIs: https://frem.sh/user/oauth2/<auth-source-name>/callback
  3. Signing Key: välj ditt signeringscertifikat i Authentik.
  4. Kopiera Client ID, Client Secret och OpenID Configuration URL (ta bort /.well-known/openid-configuration; utfärdar-URL:en är roten, t.ex. https://sso.acme.internal/application/o/<slug>/).
  5. Skapa en Application och koppla den till leverantören; sätt start-URL:en till frem.sh/user/login?redirect_to=/<your-org>.

Keycloak

  1. Your Realm → Clients → Create client.
  2. Client type: OpenID Connect. Client ID: fremforge.
  3. Valid redirect URIs: https://frem.sh/user/oauth2/<auth-source-name>/callback
  4. Fliken Credentials: kopiera Client Secret.
    • Utfärdar-URL = https://keycloak.acme.internal/realms/<your-realm>

Auth0 / Okta Customer Identity Cloud

  1. Applications → Create Application → Regular Web Application.
  2. Allowed Callback URLs: https://frem.sh/user/oauth2/<auth-source-name>/callback
  3. Allowed Logout URLs: https://frem.sh/<your-org>/logout
  4. Settings: kopiera Domain, Client ID och Client Secret.
    • Utfärdar-URL = https://<your-auth0-domain>/

Steg 3: registrera leverantören i fremforge

  1. Organisationens administration → SSO, skrolla till Lägg till en ny SSO-källa och klicka på Start wizard (öppnar /_admin/sso/wizard/start).
  2. Välj OpenID Connect som källtyp och fortsätt.
  3. Fyll i:
    • Visningsnamn: visas på knappen på inloggningssidan, t.ex. “Sign in with Okta”.
    • Client ID och Client Secret från steg 2.
    • Utfärdar-URL: fremforge hämtar <issuer>/.well-known/openid-configuration för att hitta endpoints automatiskt.
  4. Attribute mapping (standardvärdena fungerar för de flesta IdP:er):
    • claimet email → mejladress i fremforge (standard: email)
    • claimet username → användarnamn i Forgejo (standard: preferred_username → faller tillbaka på email)
    • claimet display_name → fullständigt namn (standard: name)
  5. Gå igenom guidens skärmar för granskning och bekräftelse. fremforge gör en discovery-hämtning och kontrollerar anslutningen innan något sparas.

När källan har sparats visas knappen Sign in with <name> på organisationens inloggningssida på frem.sh/user/login?redirect_to=/<your-org>.

Via REST API

OIDC-autentiseringskällan kan registreras programmatiskt, vilket är praktiskt när du skriptar provisionering av organisationer eller styr konfigurationen från CI. Samma provisionOidcAuthSource körs som i administrationsguiden.

  • Verifiera först en domän POST /_app/api/v1/orgs/:slug/sso/domains med body { "domain": "acme.com" }, och sedan POST /_app/api/v1/orgs/:slug/sso/domains/:id/verify
  • Registrera OIDC-källan POST /_app/api/v1/orgs/:slug/sso, där body innehåller type: "oidc", issuer_url, client_id och client_secret
  • Uppdatera mappningen grupp→team PUT /_app/api/v1/orgs/:slug/sso med body { "id": "...", "group_team_map": { ... } }
  • Lista källor GET /_app/api/v1/orgs/:slug/sso

Kräver en personlig åtkomsttoken (PAT) med scopet sso:write:

curl -X POST \
  -H "Authorization: Bearer ${FREMFORGE_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-okta",
    "type": "oidc",
    "issuer_url": "https://acme.okta.com",
    "client_id": "0oa1abc...",
    "client_secret": "s3cr3t..."
  }' \
  https://frem.sh/_app/api/v1/orgs/acme/sso

Se referensen för det publika REST-API:et för den fullständiga OpenAPI-specifikationen.

Vad som händer vid inloggning

  1. Användaren klickar på Sign in with <name> på frem.sh/user/login?redirect_to=/<your-org>.
  2. fremforge skickar vidare till IdP:ns auktoriserings-endpoint med scope=openid email profile.
  3. Användaren autentiserar sig hos IdP:n (MFA upprätthålls av IdP:n, inte av fremforge).
  4. IdP:n skickar tillbaka till frem.sh/user/oauth2/<auth-source-name>/callback med en auktoriseringskod.
  5. fremforge byter koden mot tokens, validerar ID-tokens signatur mot IdP:ns JWKS, läser ut claimen för mejladress och användarnamn och skapar eller uppdaterar Forgejo-användaren.
  6. Om Require SSO är påslaget (Organisationens administration → SSO → Policyer) blockeras direkt inloggning med lösenord. Bara vägen via IdP:n fungerar.

Require SSO

Organisationens administration → SSO → Policyer → Require SSO for all members. När detta är påslaget gäller följande:

  • Befintliga medlemmar måste autentisera sig på nytt via IdP:n vid nästa inloggning.
  • PAT:er och SSH-nycklar fungerar fortfarande som autentiseringsmetoder, men med Require SSO påslaget omvalideras IdP-sessionen var 15:e minut vid Git-operationer. En användare som inaktiveras i IdP:n förlorar därför åtkomsten för push och pull inom 15 minuter, även om SSH-nyckeln fortfarande är registrerad. Ingen separat återkallelse av nycklar behövs.
  • Nya inbjudna medlemmar får konton som bara kan använda SSO.

Kombinera med SCIM för hela livscykeln

OIDC sköter autentiseringen. För att automatisera provisionering och avprovisionering av användare (skapa konton vid anställning, inaktivera vid avslut, synkronisera gruppmedlemskap) kombinerar du OIDC med SCIM 2.0-provisionering.

De flesta IdP:er för företag (Okta, Entra) stöder både OIDC och SCIM samtidigt. Den vanliga konfigurationen:

  1. Konfigurera OIDC så att medlemmarna kan logga in via IdP:n.
  2. Slå på SCIM så att IdP:n skickar ändringar av användare och grupper automatiskt.
  3. Slå på Require SSO. Med SCIM aktivt blockeras användarens åtkomst till fremforge direkt när användaren avprovisioneras i IdP:n.

Rotation av nycklar och secrets

fremforge cachar IdP:ns JWKS (signeringsnycklar) och uppdaterar dem enligt ett schema och när en signaturvalidering misslyckas. Nyckelrotation på IdP-sidan (t.ex. Oktas automatiska nyckelrotation) hanteras transparent. Du behöver inte göra något manuellt.

Om du roterar Client Secret i IdP:n:

Autentiseringskällans kort under Organisationens administration → SSO har inget fält för client secret, och en autentiseringskälla kan inte redigeras efter att den har skapats. Vill du byta secret kontaktar du support@frem.sh innan du återkallar den gamla i IdP:n: vi uppdaterar den åt dig, och inloggningen fortsätter att fungera.

Stänga av OIDC

Vill du stoppa inloggning med OIDC tar du bort autentiseringskällan: Organisationens administration → SSO → <autentiseringskälla> → Ta bort. Inloggning via den slutar direkt. Har inga medlemmar loggat in via den ännu raderas den; har medlemmar gjort det behåller fremforge en avstängd kopia med nytt namn, så att deras konton finns kvar. Deras konton, sessioner och åtkomsttoken återkallas inte: för att stänga den åtkomsten tar du bort medlemmarna från organisationen eller avprovisionerar dem via SCIM. Användare som bara hade OIDC som väg in faller tillbaka på e-post och lösenord (om ett lokalt lösenord är satt) eller kan inte logga in, så se först till att en break-glass-ägare fortfarande kan logga in med ett lokalt lösenord. Misslyckas borttagningen säger konsolen det, inget ändras och inloggning via källan fungerar fortfarande.

Det finns ingen brytare för att stänga av en autentiseringskälla en tid och slå på den igen senare; kontakta support@frem.sh för det. För att undvika föräldralösa konton tar du bort autentiseringskällan innan du avvecklar applikationen i din IdP, inte efteråt.

Felsökning

Redirect-URI:n stämmer inte

IdP:n avvisar callbacken om redirect-URI:n som är registrerad i IdP:n inte exakt stämmer med https://frem.sh/user/oauth2/<auth-source-name>/callback. <auth-source-name> är det namn du angav när du lade till autentiseringskällan i fremforge (t.ex. okta-primary, entra-prod); Forgejos OAuth2-router använder det för att skicka callbacken rätt. Kopiera den exakta callback-URL:en från fältet Redirect URI som SSO-guiden visar medan du lägger till autentiseringskällan (Organisationens administration → SSO → + Lägg till SSO-källa) i stället för att skriva den för hand; URL:en är skiftlägeskänslig och avslutande snedstreck spelar roll.

invalid_client vid tokenutbytet

Client ID eller Client Secret är fel. Kopiera dem igen från IdP:ns konsol. Vissa IdP:er visar secreten bara en gång när den skapas. Skapa en ny secret om originalet inte sparades.

Claims saknas (användarnamn eller mejladress är tomt)

Kontrollera IdP:ns policy för vilka attribut och claims som lämnas ut. fremforge kräver minst claimet email i ID-token. Om din IdP kräver uttryckliga behörigheter för att lämna ut claims (t.ex. kräver Entra API-behörigheterna profile och email), se till att de är beviljade och godkända.

Användare är provisionerade men kan inte logga in

Om Require SSO är påslaget och användarens mejldomän inte stämmer med en verifierad domän blockerar fremforge inloggningen. Verifiera domänen under Organisationens administration → SSO → Verifierade domäner. Domänen i användarens email-claim måste stämma.

Step-up med sessionsbindning per organisation

Utöver den vanliga SSO-inloggningen kan fremforge kräva en ny autentisering, intygad av IdP:n, varje gång en användare går över till en annan organisations administrationsgränssnitt. Det är den styrka för reglerade branscher som “sessionsbindning per organisation” på prissidan utlovar, och den är användbar när varje administrativ åtgärd över organisationsgränser behöver bära en IdP-intygad autentisering avgränsad till just den organisationen.

Det finns två styrkenivåer. Bindningen är påslagen som standard; vilken nivå som gäller beror på om du konfigurerar step-up-klienten nedan:

  • Mjuk bindning (standard om du inte konfigurerar step-up): omdirigeringen vid första åtkomsten till en annan organisation går via Forgejos universella /user/login. Om din Forgejo-session är aktuell märks rundturen inte och frågar inte efter något, så den visar att webbläsaren har en giltig session, inte att användaren har autentiserat sig på nytt. Använd hård bindning när du behöver en ny autentisering per organisation. Break-glass med lokala inloggningsuppgifter fungerar som förut.
  • Hård bindning (konfigureras nedan): omdirigeringen går via fremforges step-up-endpoint, som startar en OIDC-autentisering med prompt=login mot din IdP. IdP:n MÅSTE fråga efter inloggningsuppgifter och MFA igen; vi kontrollerar att auth_time i den returnerade ID-token ligger inom 5 minuter från nu. Break-glass med lokala inloggningsuppgifter via /user/login fungerar fortfarande för organisationens ägare; hård bindning ändrar bara vägen för åtkomst till andra organisationer, inte den universella inloggningen.

Konfigurera hård bindning

Hård bindning kräver en ANDRA OIDC-klient i din IdP vid sidan av den som Forgejo använder (samma utfärdare, separat client_id + client_secret, separat redirect-URI).

  1. I din IdP registrerar du en ny OIDC-applikation:

    FältVärde
    ApplikationstypWeb (konfidentiell)
    Grant typesAuthorization Code, med PKCE
    Redirect-URIhttps://frem.sh/<your-org>/_admin/-/stepup/callback
    Autentiseringsmetod mot token-endpointclient_secret_basic eller client_secret_post
    Obligatoriska scopesopenid, email
    Claimet auth_timeObligatoriskt i ID-token
    prompt=loginRespekteras (standardbeteende hos de flesta IdP:er)

  2. I fremforge går du till Organisationens administration → SSO, fäller ut Add OIDC auth source och fyller i de valfria fälten under Per-org session-binding step-up längst ned i formuläret:

    • Step-up Client ID: från din IdP:s nya applikation
    • Step-up Client Secret: från din IdP:s nya applikation; krypteras i vila med AES-256-GCM (HKDF-härledd undernyckel) innan den sparas
    • Step-up Redirect URI: https://frem.sh/<your-org>/_admin/-/stepup/callback

  3. Verifiera: öppna https://frem.sh/<your-org>/_admin/billing i ett nytt webbläsarfönster. Du ska skickas via din IdP, få frågan om inloggning igen och hamna tillbaka på faktureringssidan. Granskningsloggen visar en händelse org-session.step-up.ok med auth_time.

Om step-up-fälten lämnas tomma faller autentiseringskällan tillbaka på mjuk bindning, vilket passar organisationer som vill ha SSO vid inloggning men inte behöver IdP-intyg per organisation.

Felsökning av hård bindning

  • “IdP did not emit auth_time”: IdP:n returnerade en ID-token utan claimet auth_time. fremforge kräver det, eftersom det är så vi kontrollerar att den nya autentiseringen är färsk. Kontrollera IdP:ns claim-policy; de flesta har en inställning för att “inkludera auth_time”.
  • “auth_time too old”: IdP:n respekterade prompt=login på protokollnivå men frågade inte användaren igen i praktiken. Skärp IdP:ns policy för “session lifetime” eller “max age” för den här klienten.
  • “step-up cookie binding mismatch”: användaren bytte identitet mitt i flödet (t.ex. öppnade en andra flik och autentiserade sig som en annan användare). Börja om från /<your-org>/_admin/billing.
  • “step-up redirect URI rejected”: URI:n klarade inte vårt skydd för publik HTTPS (privata adresser, loopback- och metadataadresser blockeras). Använd den kanoniska formen frem.sh/_app.

Korsreferenser