Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aldy505 wants to merge 1 commit into
base: master
Choose a base branch
from
+4 −0
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/organization/authentication/sso/saml2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,3 +156,7 @@ Instead, the member remains inside of Sentry without any means to log in, as the
#### Attempting to set up SAML2 SSO with an IdP results in a failure with the message “The provider did not return a valid user identity.” What is happening here?

The crux of the problem here is that different IdP platforms (Okta, Azure AD, etc) use different terms and conventions for the fields necessary for the integration to work. As a result, it’s possible to map up incorrect values into Sentry, causing SSO to fail with this error message.

#### API throwing 500 error status when trying to login on self-hosted Sentry

@sentry sentry Bot Jul 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


If you're using the self-hosted Sentry, you may encounter this error right after login. Usually this is caused by `system.url-prefix` not being set explicitly on your `sentry/config.yml` file. You need to set it to the URL matching to the web interface of your self-hosted Sentry instance. Then, you may need to execute the `install.sh` script again to apply the changes.
Loading