Skip to content
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.

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

Rewrite Okta SAML docs for application owners #2155

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

alexisintech
Copy link
Member

@alexisintech alexisintech commented Apr 2, 2025

🔎 Previews:

Followup from #2112

What problem does this solve?

Here's how configuring SAML usually works:

  1. An App Owner begins to onboard a new enterprise, and is put in touch with the enterprise's IT Admin
  2. The App Owner creates the saml connection, and shares the Single sign-on URL and Audience URI (SP Entity ID) with the IT Admin via an email, along with more instructions
  3. The IT admin follows those instructions, and responds via email with a metadata url
  4. The App owner adds the metadata URL, and then coordinates on a time with the IT admin to enable and test the connection

Our docs today don't reflect that reality. They presume the the reader has simultaneous access to Clerk and the Okta IDP. As such, an application owner reading our docs needs to understand them deeply enough to re-write them into an email suitable for the IT-admin's consumption. This is time consuming and painful, because the App owner wants to avoid needing to internalize the nitty-gritty details of SAML - that's why they have Clerk!

What changed?

This rewrites the docs with the two above personas in mind.

The Application Owner is the primary reader, with access to Clerk. The instructions for the IT Admin (with access to Okta) are encapsulated in an email template.

Checklist

  • I have clicked on "Files changed" and performed a thorough self-review
  • All existing checks pass

Copy link

github-actions bot commented Apr 2, 2025

Hey, here’s your docs preview: https://clerk.com/docs/pr/2155

@alexisintech alexisintech changed the title (wip) Rewrite Okta SAML docs for application owners Apr 2, 2025
@alexisintech alexisintech marked this pull request as ready for review April 4, 2025 20:24
@alexisintech alexisintech requested a review from a team as a code owner April 4, 2025 20:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant