Rewrite Okta SAML docs for application owners #2155
Conversation
|
Hey, here’s your docs preview: https://clerk.com/docs/pr/2155 |
|
|
||
| <Steps> | ||
| ## Enable Okta as a SAML connection in Clerk | ||
| ## Create an Okta SAML connection in Clerk |
There was a problem hiding this comment.
Wondering if it might be helpful to precede each heading with who each step is for - e.g., "App Admin: Create an Okta SAML connection in Clerk" and "Okta Customer: Configure SAML app" to make it even clearer
There was a problem hiding this comment.
ooo I like this idea too!
|
|
||
| > [!WARNING] | ||
| > If there are existing users with email domains that match the SAML connection, and there is an error in the SAML configuration in Clerk or Okta, those users will be **unable to sign in** when the connection is enabled. If this is a concern, we recommend coordinating with your counterpart to test the connection at an off-peak time. | ||
| > To make the connection available for users to authenticate with: |
There was a problem hiding this comment.
Is this sentence supposed to be included in the warning block? It feels like it might belong with the steps below for better readability
There was a problem hiding this comment.
oopsie hehe probably
| - Create a SSO connection via Clerk Dashboard | ||
| - Give your customer instructions on how to connect Okta Workforce to your Clerk app | ||
| - Enable and test the SAML connection |
There was a problem hiding this comment.
Not a suggestion/change but wondering what this is - couldn't see it on the preview?
There was a problem hiding this comment.
it's an artifact - the tutorialhero no longer supports this and needs to be updated! it's an old PR
🔎 Previews:
Followup from #2112
What problem does this solve?
Here's how configuring SAML usually works:
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