feat(saml): provide a FAQ for self-hosted installation

[aldy505]

DESCRIBE YOUR PR

Closes getsentry/self-hosted#4033

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
  Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ready	Preview, Comment	Jul 5, 2026 10:53am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored		Jul 5, 2026 10:53am

[sentry]

Bug: The new FAQ title is vague, inconsistent with other FAQs, and doesn't specify the root cause of the 500 error it addresses, potentially misleading users.
_{Severity: LOW}

Suggested Fix

Revise the FAQ title to be a question, consistent with other FAQs in this section. The title should also be more specific about the problem it solves, such as mentioning the system.url-prefix configuration, to avoid misleading users who are experiencing 500 errors from different causes.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: docs/organization/authentication/sso/saml2.mdx#L160

Potential issue: The new FAQ title "API throwing 500 error status when trying to login
on self-hosted Sentry" is overly vague and breaks the established question-based format
of other FAQs in the section. A 500 error during SAML login can stem from multiple
issues, such as a missing `system.url-prefix` configuration (the topic of this FAQ),
CSRF protection problems, or incorrect SAML attribute mapping. By not specifying the
cause, the title can mislead users experiencing a 500 error from a different root cause
into attempting an irrelevant fix, causing confusion and wasted time.

_{Did we get this right? 👍 / 👎 to inform future reviews.}