Single sign-on med OIDC

fremforge støtter OpenID Connect (OIDC) for single sign-on. OIDC er protokollen for single sign-on som fremforge støtter. Alle store identitetsleverandører (IdP-er) – Entra, Okta, Google Workspace, Auth0, Authentik og Keycloak – støtter OIDC direkte. Livssyklusen til signeringsnøklene håndteres automatisk via OIDC-endepunktene for discovery og JWKS.

OIDC er den eneste protokollen for single sign-on som fremforge tilbyr i dag. SAML er ikke tilgjengelig ennå; både Microsoft Entra ID og ADFS støtter OIDC.

Oppsett

Steg 1: bekreft et domene

Organisasjonsadministrasjon → SSO → Bekreftede domener (utvid den sammenfoldede delen) → legg til e-postdomenet ditt (f.eks. acme.com). Bevis at du kontrollerer det på en av disse måtene:

• DNS TXT-post: legg til _fremforge-verification=<token> i DNS for domenet, og klikk deretter på Bekreft.
• HTTP-fil: legg ut tokenet på https://acme.com/.well-known/fremforge-verification, og klikk deretter på Bekreft.

Domenet må være bekreftet før du kan registrere en autentiseringskilde. Dette gjør du bare én gang.

Steg 2: opprett en OAuth 2.0-applikasjon i identitetsleverandøren

fremforge trenger tre verdier fra identitetsleverandøren: Client ID, Client Secret og Issuer URL (også kalt roten av OIDC-discovery-URL-en). Sett opp identitetsleverandøren slik.

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 (valgfritt, men anbefalt)
4. Assignments: tildel applikasjonen til gruppene eller brukerne som skal ha tilgang til fremforge.
5. Kopier: Client ID, Client Secret og Okta domain (f.eks. https://acme.okta.com).
   • Issuer URL = https://acme.okta.com (eller https://acme.okta.com/oauth2/default for egendefinerte autorisasjonsservere)

Microsoft Entra (Azure AD)

1. App registrations → New registration, navn «fremforge», støttede kontotyper = én tenant.
2. Redirect URI: Web → https://frem.sh/user/oauth2/<auth-source-name>/callback
3. Certificates & secrets → New client secret, kopier Value med en gang (vises bare én gang).
4. Overview: kopier Application (client) ID og Directory (tenant) ID.
   • Issuer URL = https://login.microsoftonline.com/<tenant-id>/v2.0
5. Token configuration → Add groups claim, velg Security groups. Dette fyller groups-claimen som fremforge bruker til å tilordne team.
6. API permissions: bekreft at openid, profile og email er gitt (det er de som standard).

ADFS

ADFS på Windows Server 2016 og nyere er en OpenID Connect-leverandør.

1. AD FS Management → Application Groups → Add Application Group, navn «fremforge», malen Server application (under Standalone applications) eller Server application accessing a web API.
2. Kopier Client Identifier. Redirect URI: https://frem.sh/user/oauth2/<auth-source-name>/callback.
3. Configure Application Credentials → Generate a shared secret, kopier den (vises bare én gang).
4. Gi scopene openid, profile og email, og legg til transformasjonsregler for utstedelse som legger email og name (og en gruppe-claim hvis du tilordner team) i ID-tokenet.
   • Issuer URL = https://<your-adfs-host>/adfs (discovery på https://<your-adfs-host>/adfs/.well-known/openid-configuration)

MFA-verifisering via OIDC er ennå ikke testet mot ADFS. Slå den på for én testbruker først, og sjekk at innloggingen lykkes.

Google Workspace

1. Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID.
2. Applikasjonstype: Web application.
3. Authorised redirect URIs: https://frem.sh/user/oauth2/<auth-source-name>/callback
4. Kopier Client ID og Client Secret.
   • Issuer URL = https://accounts.google.com
5. Under Google Workspace Admin → Security → API controls → Domain-wide delegation begrenser du OAuth-samtykket til domenet ditt, slik at bare medlemmer av arbeidsområdet kan autentisere seg.

Authentik

1. Applications → Providers → Create → OAuth2/OpenID Connect Provider.
2. Redirect URIs: https://frem.sh/user/oauth2/<auth-source-name>/callback
3. Signing Key: velg signeringssertifikatet i Authentik.
4. Kopier Client ID, Client Secret og OpenID Configuration URL (fjern /.well-known/openid-configuration; issuer-URL-en er roten, f.eks. https://sso.acme.internal/application/o/<slug>/).
5. Opprett en Application og knytt den til leverandøren; sett start-URL-en til frem.sh/user/login?redirect_to=/<your-org>.

Keycloak

1. Your Realm → Clients → Create client.
2. Client type: OpenID Connect. Klient-ID: fremforge.
3. Valid redirect URIs: https://frem.sh/user/oauth2/<auth-source-name>/callback
4. Fanen Credentials: kopier Client Secret.
   • Issuer 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: kopier Domain, Client ID og Client Secret.
   • Issuer URL = https://<your-auth0-domain>/

Steg 3: registrer leverandøren i fremforge

1. Organisasjonsadministrasjon → SSO, bla ned til Legg til en ny SSO-kilde og klikk på Start wizard (åpner /_admin/sso/wizard/start).
2. Velg OpenID Connect som kildetype og fortsett.
3. Fyll inn:
   • Display name, vises på knappen på innloggingssiden, f.eks. «Sign in with Okta».
   • Client ID og Client Secret fra steg 2.
   • Utsteder-URL; fremforge henter <issuer>/.well-known/openid-configuration for å finne endepunktene automatisk.
4. Tilordning av attributter (standardverdiene virker for de fleste identitetsleverandører):
   • email-claim → e-postadresse i fremforge (standard: email)
   • username-claim → brukernavn i Forgejo (standard: preferred_username → faller tilbake til email)
   • display_name-claim → fullt navn (standard: name)
5. Gå gjennom veiviserens skjermbilder for gjennomgang og bekreftelse. fremforge gjør et discovery-oppslag og kontrollerer tilkoblingen før noe lagres.

Når det er lagret, vises en knapp for Sign in with <name> på organisasjonens innloggingsside på frem.sh/user/login?redirect_to=/<your-org>.

Via REST-API

OIDC-autentiseringskilden kan registreres programmatisk – nyttig når du skripter klargjøring av organisasjoner eller styrer oppsettet fra CI. Den samme provisionOidcAuthSource kjører som i administrasjonsveiviseren.

• Bekreft et domene først POST /_app/api/v1/orgs/:slug/sso/domains body: { "domain": "acme.com" }, deretter POST /_app/api/v1/orgs/:slug/sso/domains/:id/verify
• Registrer OIDC-kilden POST /_app/api/v1/orgs/:slug/sso; bodyen inneholder type: "oidc", issuer_url, client_id, client_secret
• Oppdater tilordningen gruppe→team PUT /_app/api/v1/orgs/:slug/sso body: { "id": "...", "group_team_map": { ... } }
• List kilder GET /_app/api/v1/orgs/:slug/sso

Krever et personlig tilgangstoken (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 referansen for det offentlige REST-API-et for hele OpenAPI-spesifikasjonen.

Hva som skjer ved innlogging

1. Brukeren klikker på Sign in with <name> på frem.sh/user/login?redirect_to=/<your-org>.
2. fremforge sender brukeren videre til autorisasjonsendepunktet hos identitetsleverandøren med scope=openid email profile.
3. Brukeren autentiserer seg hos identitetsleverandøren (MFA håndheves av identitetsleverandøren, ikke av fremforge).
4. Identitetsleverandøren sender brukeren tilbake til frem.sh/user/oauth2/<auth-source-name>/callback med en autorisasjonskode.
5. fremforge bytter koden mot tokener, validerer signaturen på ID-tokenet mot identitetsleverandørens JWKS, henter ut e-post- og brukernavn-claimene og oppretter eller oppdaterer Forgejo-brukeren.
6. Hvis Require SSO er slått på (Organisasjonsadministrasjon → SSO → Policies), blokkeres direkte innlogging med passord. Bare veien via identitetsleverandøren virker.

Krev SSO

Organisasjonsadministrasjon → SSO → Policies → Require SSO for all members. Når dette er slått på:

• Eksisterende medlemmer må autentisere seg på nytt via identitetsleverandøren ved neste innlogging.
• PAT-er og SSH-nøkler fortsetter å virke som autentiseringsmekanismer, men med Require SSO slått på blir sesjonen hos identitetsleverandøren validert på nytt hvert 15. minutt ved Git-operasjoner. En bruker som deaktiveres hos identitetsleverandøren, mister derfor tilgang til push/pull innen 15 minutter, selv om SSH-nøkkelen fortsatt er registrert. Det trengs ingen separat tilbakekalling av nøkler.
• Nye invitasjoner av medlemmer blir kontoer med bare SSO.

Kombiner med SCIM for full livssyklusstyring

OIDC håndterer autentisering. For å automatisere klargjøring og avvikling av brukere (opprette kontoer ved ansettelse, deaktivere ved fratredelse, synkronisere gruppemedlemskap) kombinerer du OIDC med klargjøring via SCIM 2.0.

De fleste identitetsleverandører for virksomheter (Okta, Entra) støtter både OIDC og SCIM samtidig. Det typiske oppsettet:

1. Sett opp OIDC slik at medlemmer kan logge inn via identitetsleverandøren.
2. Slå på SCIM slik at identitetsleverandøren sender endringer i brukere og grupper automatisk.
3. Slå på Require SSO. Med SCIM aktivt blokkerer avvikling av brukeren hos identitetsleverandøren tilgangen til fremforge umiddelbart.

Rotasjon av tokener

fremforge bufrer identitetsleverandørens JWKS (signeringsnøkler) og oppdaterer dem etter en tidsplan og når validering av en signatur feiler. Nøkkelrotasjon hos identitetsleverandøren (f.eks. automatisk nøkkelrotasjon i Okta) håndteres uten at du merker det. Ingen manuell handling er nødvendig.

Hvis du roterer Client Secret hos identitetsleverandøren:

Kortet til autentiseringskilden i Organisasjonsadministrasjon → SSO har ikke noe felt for klient-secreten, og en autentiseringskilde kan ikke redigeres etter at den er opprettet. For å bytte secreten kontakter du support@frem.sh før du tilbakekaller den gamle hos identitetsleverandøren: vi oppdaterer den for deg, og innloggingen fortsetter å virke.

Slå av OIDC

Vil du stoppe innlogging med OIDC, fjerner du autentiseringskilden: Organisasjonsadministrasjon → SSO → <autentiseringskilde> → Fjern. Innlogging via den stopper med en gang. Har ingen medlemmer logget inn via den ennå, slettes den; har medlemmer gjort det, beholder fremforge en avslått kopi med nytt navn, slik at kontoene deres blir værende. Kontoene, øktene og tilgangstokenene deres trekkes ikke tilbake: for å stenge den tilgangen fjerner du medlemmene fra organisasjonen eller avprovisjonerer dem via SCIM. Brukere som bare hadde OIDC som vei inn, faller tilbake på e-post og passord (hvis et lokalt passord er satt) eller kan ikke logge inn, så sørg først for at en break-glass-eier fortsatt kan logge inn med et lokalt passord. Mislykkes fjerningen, sier konsollen fra, ingenting endres, og innlogging via kilden fungerer fortsatt.

Det finnes ingen bryter for å slå av en autentiseringskilde en stund og på igjen senere; kontakt support@frem.sh for det. For å unngå foreldreløse kontoer fjerner du autentiseringskilden før du avvikler applikasjonen i IdP-en, ikke etterpå.

Feilsøking

Redirect-URI stemmer ikke

Identitetsleverandøren avviser callbacken hvis redirect-URI-en som er registrert hos den, ikke stemmer nøyaktig med https://frem.sh/user/oauth2/<auth-source-name>/callback. <auth-source-name> er Navn du satte da du la til autentiseringskilden i fremforge (f.eks. okta-primary, entra-prod); den brukes av Forgejos OAuth2-ruter til å sende callbacken videre. Kopier den nøyaktige callback-URL-en fra feltet Redirect-URI som SSO-veiviseren viser mens du legger til autentiseringskilden (Organisasjonsadministrasjon → SSO → + Legg til SSO-kilde), i stedet for å skrive den inn for hånd; URL-en skiller mellom store og små bokstaver, og avsluttende skråstreker betyr noe.

invalid_client ved tokenutveksling

Client ID eller Client Secret er feil. Kopier på nytt fra konsollen hos identitetsleverandøren. Noen identitetsleverandører viser hemmeligheten bare én gang, når den opprettes. Generer en ny hemmelighet hvis den opprinnelige ikke ble tatt vare på.

Claims mangler (brukernavn eller e-post er tomt)

Sjekk policyen for utlevering av attributter/claims hos identitetsleverandøren. fremforge krever minst email-claimen i ID-tokenet. Hvis identitetsleverandøren krever eksplisitte tillatelser for å utlevere claims (f.eks. krever Entra API-tillatelsene profile og email), må du sørge for at de er gitt og samtykket til.

Brukere er klargjort, men kan ikke logge inn

Hvis Require SSO er slått på og brukerens e-postdomene ikke stemmer med et bekreftet domene, blokkerer fremforge innloggingen. Bekreft domenet under Organisasjonsadministrasjon → SSO → Bekreftede domener. Domenet i brukerens email-claim må stemme.

Ny autentisering ved sesjonsbinding per organisasjon

Utover den vanlige SSO-innloggingen kan fremforge kreve en ny autentisering, bekreftet av identitetsleverandøren, hver gang en bruker går inn i administrasjonsflaten til en ny organisasjon. Dette er styrken for regulerte sektorer bak «sesjonsbinding per organisasjon», som er lovet på prissiden, og nyttig når hver administrativ handling på tvers av organisasjoner må bære en autentisering bekreftet av identitetsleverandøren og avgrenset til akkurat den organisasjonen.

To styrkenivåer. Bindingen er på som standard; hvilket nivå som gjelder, avhenger av om du kobler opp klienten for ny autentisering nedenfor:

• Myk binding (standard hvis du ikke kobler opp ny autentisering): omdirigeringen ved første tilgang på tvers av organisasjoner går gjennom Forgejos universelle /user/login. Hvis Forgejo-sesjonen din er gyldig, er rundturen usynlig og ber ikke om noe, så den beviser at nettleseren har en gyldig sesjon, ikke at brukeren har autentisert seg på nytt. Bruk hard binding når du trenger en ny autentisering per organisasjon. Nødtilgang med lokal legitimasjon (break-glass) forblir intakt.
• Hard binding (koble opp nedenfor): omdirigeringen går gjennom fremforges endepunkt for ny autentisering, som starter en OIDC-autentisering med prompt=login mot identitetsleverandøren. Identitetsleverandøren MÅ be om legitimasjon og MFA på nytt; vi kontrollerer at auth_time i det returnerte ID-tokenet ligger innenfor 5 minutter fra nå. Break-glass med lokal legitimasjon via /user/login virker fortsatt for eiere av organisasjonen; hard binding endrer bare veien for tilgang på tvers av organisasjoner, ikke den universelle innloggingen.

Koble opp hard binding

Hard binding krever en ANDRE OIDC-klient hos identitetsleverandøren ved siden av den Forgejo bruker (samme issuer, egen client_id + client_secret, egen redirect-URI).

1. Hos identitetsleverandøren registrerer du en ny OIDC-applikasjon:

   Felt	Verdi
   Applikasjonstype	Web (konfidensiell)
   Grant-typer	Authorization Code, med PKCE
   Redirect URI	https://frem.sh/<your-org>/_admin/-/stepup/callback
   Autentiseringsmetode for token-endepunktet	client_secret_basic eller client_secret_post
   Påkrevde scopes	openid, email
   auth_time-claim	Påkrevd i ID-tokenet
   prompt=login	Respekteres (standard oppførsel hos de fleste identitetsleverandører)

2. I fremforge går du til Organisasjonsadministrasjon → SSO, utvider Add OIDC auth source og fyller ut de valgfrie feltene for Per-org session-binding step-up nederst i skjemaet:

   • Step-up Client ID: fra den nye applikasjonen hos identitetsleverandøren
   • Step-up Client Secret: fra den nye applikasjonen hos identitetsleverandøren, kryptert ved lagring med AES-256-GCM (HKDF-avledet undernøkkel) før den lagres
   • Step-up Redirect URI: https://frem.sh/<your-org>/_admin/-/stepup/callback

3. Kontroller: åpne https://frem.sh/<your-org>/_admin/billing i et nytt nettleservindu. Du skal bli sendt via identitetsleverandøren, bli bedt om å logge inn på nytt og havne tilbake på faktureringssiden. Revisjonsloggen viser en org-session.step-up.ok-hendelse med auth_time.

Hvis feltene for ny autentisering står tomme, faller autentiseringskilden tilbake til myk binding – nyttig for organisasjoner som vil ha SSO ved innlogging, men ikke trenger bekreftelse fra identitetsleverandøren per organisasjon.

Feilsøking av hard binding

• «IdP did not emit auth_time»: identitetsleverandøren returnerte et ID-token uten auth_time-claimen. fremforge krever den fordi det er slik vi kontrollerer at den nye autentiseringen er fersk. Sjekk claim-policyen hos identitetsleverandøren; de fleste har en bryter for «include auth_time».
• «auth_time too old»: identitetsleverandøren respekterte prompt=login på protokollnivå, men ba ikke brukeren logge inn på nytt. Stram inn policyen for «session lifetime» eller «max age» for denne klienten hos identitetsleverandøren.
• «step-up cookie binding mismatch»: brukeren byttet identitet midt i flyten (f.eks. åpnet en ny fane i nettleseren og autentiserte seg som en annen bruker). Start på nytt fra /<your-org>/_admin/billing.
• «step-up redirect URI rejected»: URI-en ble stoppet av kontrollen for offentlig HTTPS (private adresser, loopback- og metadataadresser blokkeres). Bruk den kanoniske formen frem.sh/_app.

Se også

• SAML: hvorfor SAML ikke er tilgjengelig ennå
• Klargjøring av brukere med SCIM 2.0: automatiser brukerlivssyklusen via SCIM-klienten hos identitetsleverandøren
• Sikkerhet og forsyningskjede: fremforges sikkerhetsmodell rundt SSO-sesjoner
• Organisasjonsadministrasjon: oversikt over alle administrasjonsfanene