Single sign-on med SAML 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.

Nedenfor beskrives den SP-metadata-XML, hver organisation får, og den konfiguration på IdP-siden, som de store IdP’er forventer. Testet på lanceringsdagen mod Authentik på fremverks egen operatør-tenant. Rapportér problemer til support@frem.sh, hvis din IdP’s import af metadata ikke opfører sig som forventet.

fremforge understøtter SAML 2.0 side om side med OIDC. OIDC anbefales til de fleste organisationer. De fleste moderne IdP’er (Entra, Okta, Auth0, Authentik, Keycloak, Google Workspace) understøtter OIDC direkte. Signeringsnøglernes livscyklus håndteres automatisk via OIDC’s discovery-endpoint, og der er færre ting, der kan gå galt. Brug kun SAML, når dit IdP-team specifikt kræver det (føderationsaftaler i regulerede brancher, ældre IdP’er, der ikke har fået OIDC, eller compliance-rammer, der er ældre end OIDC).

Begge protokoller ender i den samme Forgejo-session, og ingen af dem er “mere sikker”. OIDC kræver mindre vedligehold over tid (ingen manuel certifikatrotation, ingen fejlsøgning i XML-signaturer). OIDC er beskrevet på siden om OIDC SSO. Resten af denne side handler om SAML.

Opsætning

Trin 1: verificér et domæne

Samme forløb som for OIDC. Administration → SSO → Verificerede domæner → tilføj dit e-maildomæne. Bevis, at du kontrollerer domænet, med en DNS TXT-post eller en HTTP-fil på .well-known/fremforge-verification. Det skal være gjort, før du kan registrere en autentificeringskilde, også SAML.

Trin 2: hent fremforges SP-metadata

fremforge udgiver sin Service Provider-metadata på:

https://frem.sh/<your-org>/_admin/sso/saml/metadata.xml

Det er et almindeligt SAML 2.0-metadatadokument, som din IdP importerer for at kende:

• fremforges entity ID: https://frem.sh/<your-org>/saml/metadata
• URL’en til Assertion Consumer Service (ACS), som IdP’en sender SAML-svar til: https://frem.sh/<your-org>/saml/acs
• den valgfrie URL til Single Logout: https://frem.sh/<your-org>/saml/slo
• understøttede NameID-formater: emailAddress (foretrukket) og unspecified
• kravet om, at assertions er signeret (WantAssertionsSigned="true")

De fleste IdP’er kan indlæse metadata enten fra en URL eller ved filupload. Begge dele virker.

Trin 3: konfigurér din IdP

Okta

1. Applications → Create App Integration → SAML 2.0.
2. General Settings, name = “fremforge”.
3. Configure SAML:
   • Single sign-on URL: indsæt https://frem.sh/<your-org>/saml/acs
   • Audience URI (SP Entity ID): indsæt https://frem.sh/<your-org>/saml/metadata
   • Name ID format: EmailAddress
   • Application username: Email
4. Attribute Statements, som minimum:
   • email → user.email
   • username → user.email (eller user.login)
   • displayName → user.firstName + " " + user.lastName
   • Valgfrit: groups → udtryk: getFilteredGroups("...", "OKTA", 100) til mapning fra gruppe til team
5. Fanen Sign On → View SAML setup instructions → kopiér felterne fra IdP-siden:
   • Identity Provider Single Sign-On URL
   • Identity Provider Issuer (entity ID)
   • X.509 Certificate (PEM)

Microsoft Entra (Azure AD)

1. Enterprise Applications → New application → Non-gallery → navngiv den “fremforge”.
2. Single sign-on → SAML.
3. Basic SAML Configuration:
   • Identifier (Entity ID): https://frem.sh/<your-org>/saml/metadata
   • Reply URL (ACS): https://frem.sh/<your-org>/saml/acs
   • Logout URL (valgfri): https://frem.sh/<your-org>/saml/slo
4. Attributes & Claims: kontrollér, at email, givenname og surname bliver sendt, og omdøb dem om nødvendigt, så de svarer til det, fremforge forventer (email, username, displayName).
5. SAML Signing Certificate → Certificate (Base64) → download. Konvertér til PEM (Entra leverer rå base64, så pak den ind i -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----).
6. Notér IdP’ens Login URL og Microsoft Entra Identifier.

Generisk SAML 2.0-IdP

Enhver IdP, der understøtter SAML 2.0, virker. Det mindste, din IdP skal vide:

• SP entity ID: https://frem.sh/<your-org>/saml/metadata
• ACS URL: https://frem.sh/<your-org>/saml/acs (HTTP-POST-binding)
• NameID-format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• Signér assertions: ja
• Signér requests: ikke påkrævet (vi signerer ikke AuthnRequests i v1)

Trin 4: registrér IdP’en i fremforge

1. Gå til Administration → SSO, og start SSO-guiden på /<your-org>/_admin/sso/wizard/start. Vælg SAML 2.0, når guiden spørger efter protokol.
2. Udfyld:
   • Visningsnavn, som står på login-knappen i Forgejo (f.eks. “Acme SSO”)
   • IdP-entitets-id, din IdP’s identifikator (HTTPS-URL)
   • IdP’ens SSO-URL, hvor Forgejo sender brugerne hen for at blive godkendt (HTTPS-URL)
   • IdP’ens SLO-URL, valgfri; hvis den er udfyldt, sender Forgejo SLO-requests ved logout
   • IdP’ens X.509-certifikat, indsæt det PEM-kodede certifikat (-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----)
   • Gruppeattribut, valgfri; navnet på den SAML-attribut, der indeholder gruppemedlemskaber (til automatisk mapning til teams)
3. Gør guiden færdig. fremforge kontrollerer, at URL’erne er HTTPS, og at certifikatet har PEM-format, og opretter derefter autentificeringskilden i Forgejo.

Via REST API

SAML-autentificeringskilden kan også registreres programmatisk, hvilket er praktisk, når du scripter oprettelsen af organisationer eller styrer opsætningen fra et CI-workflow. Det er den samme provisionSamlAuthSource, som admin-guiden kører.

• Verificér først et domæne POST /_app/api/v1/orgs/:slug/sso/domains body: { "domain": "acme.com" } og derefter POST /_app/api/v1/orgs/:slug/sso/domains/:id/verify
• Registrér SAML-kilden POST /_app/api/v1/orgs/:slug/sso med en body, der indeholder type: "saml", idp_entity_id, idp_sso_url, idp_certificate (PEM)
• List kilderne GET /_app/api/v1/orgs/:slug/sso

Kræver et Personal Access Token (PAT) med scopet sso:write:

curl -X POST \
  -H "Authorization: Bearer ${FREMFORGE_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-saml",
    "type": "saml",
    "idp_entity_id": "https://idp.acme.com/saml/metadata",
    "idp_sso_url": "https://idp.acme.com/saml/sso",
    "idp_certificate": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
  }' \
  https://frem.sh/_app/api/v1/orgs/acme/sso

Den fulde OpenAPI-specifikation finder du i referencen til det offentlige REST API.

Trin 5: test login-forløbet

1. Åbn frem.sh/user/login?redirect_to=/<your-org> i et privat browservindue.
2. Klik på SAML SSO-knappen (teksten er det visningsnavn, du valgte).
3. Du bliver sendt videre til din IdP, logger ind og sendes tilbage til fremforge med en ny Forgejo-session.

Hvis noget fejler, så se Fejlfinding nedenfor.

Fejlfinding

“SAML response signature validation failed”

Den hyppigste årsag er forkert certifikat. Det certifikat, du indsætter, skal være det samme, som din IdP signerer SAML-svarene med. Hvis din IdP roterer certifikater, skal du indsætte det nye i fremforge. Autentificeringskilden kan opdateres ved at indsætte certifikatet igen (slet den gamle autentificeringskilde og registrér en ny med det opdaterede certifikat; senere versioner af brugerfladen vil understøtte rotation af certifikatet direkte).

Hvis du er sikker på, at certifikatet er det rigtige, så eksportér det igen, og kontrollér, at PEM-teksten ikke har fået ekstra mellemrum eller BOM-tegn med under kopieringen.

“Email attribute not found”

Din IdP sender ikke en email-attribut. Du kan enten:

• justere claim-mapningen på IdP-siden, så den sender email (eller mail for Entra)
• eller kontakte support, så vi mapper om på vores side; Forgejos SAML-autentificeringskilde understøtter konfigurerbare navne på assertion-nøgler

Automatisk mapning af grupper til teams virker ikke

Det er ikke en del af v1: feltet Gruppeattribut indeholder navnet på SAML-attributten (f.eks. memberOf), men vi opretter endnu ikke automatisk Forgejo-teams ud fra gruppeværdierne. Indtil videre kommer gruppeattributterne med i SAML-svaret og kan ses i revisionsloggen; teammedlemskab administreres manuelt eller via SCIM.

Det står på roadmappen: skriv til support@frem.sh, hvis du gerne vil have det prioriteret.

SAML sammen med SCIM

SAML håndterer login-forløbet: brugeren klikker på SSO-knappen, IdP’en godkender vedkommende, og fremforge giver en session.

SCIM håndterer provisionering: når en bruger tilføjes til gruppen på IdP-siden, opretter SCIM-connectoren brugerens fremforge-konto.

De to supplerer hinanden. De fleste enterprise-kunder bruger begge: SCIM opretter brugerne automatisk, og SAML logger dem ind. Den side er beskrevet under SCIM 2.0.

Det gør vi IKKE (endnu)

• Signering af AuthnRequests: vi signerer ikke AuthnRequests, og nogle IdP’er kræver det. Opret en sag, hvis din IdP afviser usignerede requests.
• Krypterede assertions: vi dekrypterer ikke krypterede SAML-assertions. Almindelige SAML-svar (signeret, men ikke krypteret) er det understøttede format.
• IdP-initieret SSO: vi understøtter kun SP-initieret login. Brugerne skal starte på frem.sh/user/login?redirect_to=/<your-org>, ikke på IdP’ens app-felt.
• Automatisk mapning af SAML-grupper til teams, se ovenfor.
• Flere IdP’er pr. organisation: hver organisation har højst én autentificeringskilde. Hvis du har brug for både en OIDC- og en SAML-kilde til samme organisation (forskellige målgrupper), så kontakt support@frem.sh; SSO med flere kilder er planlagt til en senere version.

Krydshenvisninger

• Administration → SSO, administrationsfladen
• SCIM 2.0, brug det sammen med SAML, så hele identiteten styres fra IdP’en
• Migreringsguides, gennemgange IdP for IdP, der også dækker genetablering af SSO
• Trust, hvordan SSO indgår i den samlede tilgang til identitet og adgang