docs: finish the SAML metadata-URL pass - #637
Merged
Merged
Conversation
The metadata-URL change in #635 left a few spots still framed around the old "send us four values" ask: - The intro and the multi-domain bullet still said "the values". - The note about members with existing Google/Microsoft accounts had ended up inside the no-metadata-URL subsection, so it read as applying only to that path. It applies to everyone; moved it back up. - Okta step 6 still led with "View SAML setup instructions" rather than the metadata link. - Certificate rotation said Shorebird re-reads your metadata, which is not true for a connection created from hand-entered values. Also documents that Shorebird keeps every signing certificate the metadata lists, so publishing the new certificate alongside the old one makes a rotation a non-event, and labels the fallback table's Okta column as an example, since that section is aimed at providers that publish no metadata URL.
eseidel
enabled auto-merge (squash)
August 29, 2026 05:30
easymac
approved these changes
Aug 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
#635 switched the ask from four values to a metadata URL, but left a few
spots on the page still written for the old ask.
bullet ("send the values for each one") still describe a list of values.
the domain had ended up inside the "If your IdP publishes no metadata
URL" subsection, so it read as applying only to that fallback path. It
applies to every connection — moved back up under the two-item ask.
the metadata link as the alternative. Now the other way round.
is not true for a connection created from hand-entered values.
Two things added from the landed admin behavior: importing keeps every
signing certificate the metadata lists, so a customer who publishes the
new certificate alongside the old one before the switch can rotate with
no downtime; and the fallback table's Okta column is now labeled as an
example, since that section is aimed at providers that publish no
metadata URL.
Verified against
web/apps/admin/app/routes/saml._index.tsxandsaml-metadata.server.ts: the import dialog takes a metadata URL orpasted XML, so the page's "send the XML file itself" fallback is
accurate.
Prettier and cspell pass. Vale isn't installed in this checkout, so it
did not run; no headings changed.