Rewrite Azure SAML docs for application owners #2112
Conversation
izaaklauer
changed the title
| @@ -17,39 +17,60 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w | |||
| } | |||
| ]} | |||
| > | |||
| - Use Microsoft Azure Entra ID to enable SSO via SAML for your Clerk app | |||
| - Create a SAML SSO connection for your customer | |||
There was a problem hiding this comment.
To prepare for the self-serve world - app owner reading this doc to customer SSO into Clerk dashboard, what do you think of removing "your customer" here
| - Create a SAML SSO connection for your customer | |
| - Create a SSO connection via Clerk Dashboard |
| @@ -17,39 +17,60 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w | |||
| } | |||
| ]} | |||
| > | |||
| - Use Microsoft Azure Entra ID to enable SSO via SAML for your Clerk app | |||
| - Create a SAML SSO connection for your customer | |||
| - Give your customer instructions on how to connect Microsoft Azure Entra ID to your app | |||
There was a problem hiding this comment.
Open for discussion: Why not using the "organization" term instead of "customer" here to align with our product modelling
|
Hey, here’s your docs preview: https://clerk.com/docs/pr/2112 |
|
|
||
| ## Create a new enterprise app in Microsoft | ||
| ## Configure the third-party Identity Provider |
There was a problem hiding this comment.
| ## Configure the third-party Identity Provider | |
| ## Configure SAML application |
What if we remove third-party here, curious what was your reasoning to include it! I'd say we should mention "SAML application" instead if configuring the identity provider
Identity Provider is the "whole database of identities", and SAML application is the actual federation bucket within their system to connect to the Clerk app
| - Assign selected users or groups to that Azure application. | ||
| - Add the Entity ID and Reply URL from Clerk to the Azure application's SAML configuration. | ||
| - Verify that the attribute mappings are correct | ||
| - Obtain and share the application's metadata URL |
There was a problem hiding this comment.
| - Obtain and share the application's metadata URL | |
| - Obtain and share the Identity Provider's application's metadata URL |
Let's be specific that this is the IdP's application metadata URL to avoid confusing with the SP metadata URL (Clerk)
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 Microsoft 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 Azure) are encapsulated in an email template.
Did any of the actual instructions change?
In running through the tutorial, I also made a few tweaks and fixes.
The biggest change is in the attribute mapping section. Right now, we're instructing the user to set the email attribute to contain the userprincipalname, which I think is flatly incorrect:
clerk-docs/docs/authentication/enterprise-connections/saml/azure.mdx
Lines 93 to 94 in ae2b5a3
And we don't acknowledge that the default attribute mappings are likely the correct ones and don't need to be modified.
What needs to happen before merging?
You may have noticed: the email template looks terrible in the browser. I introduced a new component for the template in a separate PR to this repo's parent, which introduces a copy button. Try clicking that copy button and pasting into a new email - that should look great!
I'm not sure why the markdown renders so badly on the browser. It probably needs to be fixed in the component definition on the parent repo. but fix it we must before merging this.
Stretch goals
You'll notice that the email template contains placeholders. It would be very sweet if we could automatically fetch those values and fill them! I'm willing to build the APIs necessary to make that happen if you're willing to wire them into this page 😆 .