SAML 2.0 single sign-on

The route below describes the per-tenant SP-metadata XML and the IdP-side configuration each major IdP expects. Tested launch-day against Authentik on the operator-side fremverk tenant; report issues at support@frem.sh if your IdP’s metadata-import flow misbehaves.

fremforge supports SAML 2.0 alongside OIDC. OIDC is recommended for most organisations. Most modern IdPs (Entra, Okta, Auth0, Authentik, Keycloak, Google Workspace) speak OIDC natively. The signing-key lifecycle is automatic via the OIDC discovery endpoint, and the diagnostic surface is smaller. Use SAML only when your IdP team specifically requires it (regulated-industry federation contracts, legacy IdPs that haven’t shipped OIDC, or compliance frameworks that pre-date OIDC).

Both protocols land at the same Forgejo session; neither is “more secure.” OIDC has less operational maintenance over time (no manual cert rotation, no XML-signature debugging). For OIDC, see the OIDC SSO page. The rest of this page covers SAML.

Setup

Step 1, verify a domain

Same flow as OIDC. Org admin → SSO → Verified domains → add your email domain. Prove control via DNS TXT record or .well-known/fremforge-verification HTTP file. Required before registering any auth source, including SAML.

Step 2, download fremforge’s SP metadata

fremforge publishes its Service Provider metadata at:

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

This is a standard SAML 2.0 metadata document that your IdP imports to learn:

• fremforge’s entity ID: https://frem.sh/<your-org>/saml/metadata
• the Assertion Consumer Service (ACS) URL where the IdP posts SAML responses: https://frem.sh/<your-org>/saml/acs
• the optional Single Logout URL: https://frem.sh/<your-org>/saml/slo
• supported NameID formats: emailAddress (preferred) and unspecified
• the requirement that assertions are signed (WantAssertionsSigned="true")

Most IdPs accept this metadata via URL fetch or file upload. Either works.

Step 3, configure your IdP

Okta

1. Applications → Create App Integration → SAML 2.0.
2. General Settings, name = “fremforge”.
3. Configure SAML:
   • Single sign-on URL: paste https://frem.sh/<your-org>/saml/acs
   • Audience URI (SP Entity ID): paste https://frem.sh/<your-org>/saml/metadata
   • Name ID format: EmailAddress
   • Application username: Email
4. Attribute Statements, at minimum:
   • email → user.email
   • username → user.email (or user.login)
   • displayName → user.firstName + " " + user.lastName
   • Optional: groups → expression: getFilteredGroups("...", "OKTA", 100) for group → team mapping
5. Sign On tab → View SAML setup instructions → copy the IdP-side fields:
   • 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 → name “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 (optional): https://frem.sh/<your-org>/saml/slo
4. Attributes & Claims, confirm email, givenname, surname are emitted; rename if needed to match what fremforge expects (email, username, displayName).
5. SAML Signing Certificate → Certificate (Base64) → download. Convert to PEM (Entra emits raw base64, wrap in -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----).
6. Note the IdP’s Login URL and Microsoft Entra Identifier.

Generic SAML 2.0 IdP

Any IdP that speaks SAML 2.0 works. The minimum your IdP needs to know:

• 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 assertions: yes
• Sign requests: not required (we don’t sign AuthnRequests in v1)

Step 4, register the IdP in fremforge

1. Org admin → SSO → Auth sources → click Add SAML 2.0 auth source.
2. Fill in:
   • Display name, appears on the Forgejo login button (e.g. “Acme SSO”)
   • IdP entity ID, your IdP’s identifier (HTTPS URL)
   • IdP SSO URL, where Forgejo redirects users for authentication (HTTPS URL)
   • IdP single-logout URL, optional; if provided, Forgejo sends SLO requests on logout
   • IdP X.509 certificate, paste the PEM-encoded cert (-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----)
   • Group attribute, optional; the SAML attribute name carrying group membership (for team auto-mapping)
3. Click Register. fremforge validates the URLs are HTTPS and the cert is in PEM shape, then creates the auth source on Forgejo.

Step 5, test the login flow

1. Open frem.sh/user/login?redirect_to=/<your-org> in a private browser window.
2. Click the SAML SSO button (label = the Display name you set).
3. You’re redirected to your IdP, log in, and bounced back to fremforge with a fresh Forgejo session.

If anything fails, check Diagnosis below.

Diagnosis

“SAML response signature validation failed”

Most common cause: wrong certificate. The cert you paste must match the cert your IdP signs SAML responses with. If your IdP rotates certs, paste the new one in fremforge. The auth source UI accepts a re-paste (delete old auth source, register new with updated cert; future iterations of this UI will support inline cert rotation).

If you’re certain the cert is correct, re-export and check the PEM didn’t pick up extra whitespace or BOM characters when copy-pasting.

“Email attribute not found”

Your IdP isn’t sending an email attribute. Either:

• Adjust the IdP-side claim mapping to send email (or mail for Entra)
• Or contact support to remap on our side, Forgejo’s SAML auth source supports configurable assertion key names

Group/team auto-mapping doesn’t work

Out of scope for v1: the Group attribute field carries the SAML attribute name (e.g. memberOf), but we don’t yet auto-create Forgejo teams from group values. For now, group attributes land in the SAML response and are visible in the audit log; team membership is managed manually or via SCIM.

Roadmap item: file with support@frem.sh if you want this prioritized.

Pairing SAML with SCIM

SAML handles the login flow: a user clicks the SSO button, the IdP authenticates them, and fremforge gives them a session.

SCIM handles provisioning: when a user is added to your IdP-side group, the SCIM connector creates their fremforge account.

The two are complementary. Most enterprise customers use both: SCIM provisions users automatically, SAML signs them in. See SCIM 2.0 for that side.

What we DON’T do (yet)

• AuthnRequest signing, we don’t sign AuthnRequests; some IdPs require this. File a ticket if your IdP rejects unsigned requests.
• Encrypted assertions, we don’t decrypt encrypted SAML assertions. Plain SAML responses (signed but not encrypted) are the supported shape.
• IdP-initiated SSO, we support SP-initiated only. Users must start at frem.sh/user/login?redirect_to=/<your-org>, not at the IdP-side tile.
• Automatic team mapping from SAML groups, see above.
• Multi-IdP per org, each org has at most one auth source; if you need both an OIDC and a SAML auth source for the same org (different audiences), that’s a Phase 2 ask.

Cross-references

• Org admin → SSO, the admin UI surface
• SCIM 2.0, pair with SAML for full IdP-managed identity
• Migration guides, IdP-by-IdP setup walkthroughs that include SSO reconnection
• Trust, how SSO fits into the broader identity-and-access posture