docs: move the SAML ACS URL to /sp/acs and document IdP-initiated sign-in [ENG-1736]

[twk3]

Updates the SAML SSO docs for Better Auth 1.7.1, which this release ships (ENG-1736). Both changes break SSO sign-in for an install that doesn't act, so the CHANGELOG lists them as Breaking Changes.

What changed in the API

• The ACS URL moved from /api/auth/sso/saml2/callback/<provider id> to /api/auth/sso/saml2/sp/acs/<provider id>. The old path answers 404; there is no redirect.
• IdP-initiated sign-ins are refused, for example from an Okta tile or the Entra My Apps portal. Better Auth accepted them up to 1.6 and refuses them from 1.7. The API turns them back on with SSO_SAML_ALLOW_IDP_INITIATED=true, which it already reads, but which wasn't documented.
• 1.7.1 checks the assertion's Recipient and Destination against the ACS URL, so an IdP with those set separately has to update them too.
• The Audience is still SSO_SAML_ISSUER. Better Auth uses the configured issuer as the SP entity ID, and the expected audience is that entity ID, so the Audience doesn't change.
• The SP metadata is new: it's served at /api/auth/sso/saml2/sp/metadata?providerId=<provider id>. The env-configured provider is found there too.

Changes

• docs/sso-saml.md:
  • the new ACS URL, with Recipient and Destination set to it;
  • the SP metadata URL;
  • SSO_SAML_ALLOW_IDP_INITIATED in the optional settings;
  • troubleshooting entries for a Recipient or Destination mismatch, and for sign-in from the IdP's dashboard.
• on-prem/.env.example: the new ACS URL in the setup summary, and a commented SSO_SAML_ALLOW_IDP_INITIATED line.
• docs/configuration.md: the ACS URL in the provider id row, and a row for the new variable.
• on-prem/CHANGELOG.md [Unreleased]:
  • Breaking Changes: the ACS move, with the steps to take in the IdP, and the refused IdP-initiated sign-ins;
  • New Environment Variables: SSO_SAML_ALLOW_IDP_INITIATED.

No compose change: api reads .env through env_file, so the new variable reaches it as is. SSO_SAML_SP_CERT_FILE was already removed in #31.

Testing

Docs only. The behavior was read from the API (packages/api/src/lib/sso.ts, config.ts) and from @better-auth/sso 1.7.1 (createSP, getExpectedSAMLRecipients, findSAMLProvider, spMetadata). It wasn't exercised against a real IdP.

Related

• Helm chart: feat: add currents.sso.saml.allowIdpInitiated, the new SAML ACS URL and a 1.0 upgrade guide [ENG-1736] helm-charts#61 (same change, plus the 1.0 upgrade guide)

Checklist

• PR title is Changelog-friendly: (fix|feat|chore): title [CSR-xxx]
• User-friendly and meaningful description of the changes
• Documentation was updated

🤖 Generated with Claude Code

https://claude.ai/code/session_01UhM4wHR2xPP8bbrkXGaqUD

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[baz-reviewer]

Baz Summary

Update the SAML SSO documentation and release notes for Better Auth 1.7.1, including the new ACS and SP metadata endpoints, stricter Recipient/Destination validation, and IdP-initiated sign-in behavior. Document SSO_SAML_ALLOW_IDP_INITIATED and provide upgrade steps so customers can update their IdP configuration without losing SSO access.

Topics

Topic	Details
SAML SSO Guidance	Document the new SAML ACS and SP metadata endpoints, require matching Recipient and Destination URLs, clarify that the Audience remains SSO_SAML_ISSUER, and add troubleshooting and configuration guidance for IdP-initiated sign-ins via SSO_SAML_ALLOW_IDP_INITIATED. Modified files (3) docs/configuration.md docs/sso-saml.md on-prem/.env.example Latest Contributors(1) User Commit Date dj@currents.dev docs: name the provide... October 14, 2026
SAML Upgrade Notes	Warn on-prem customers about the breaking SAML endpoint and IdP-initiated sign-in changes, and provide upgrade steps plus the new environment variable in the release notes. Modified files (1) on-prem/CHANGELOG.md Latest Contributors(1) User Commit Date dj@currents.dev docs: name the Okta ch... October 14, 2026

  _{Activate to get a short verdict whether this PR is good to go or not}

  _{Activate Skill Maintainer to keep your skills up to date}

  _{This PR would have been improved with Baz Planner - Try it now}