Rewrite Azure SAML docs for application owners #2112
Merged
Conversation
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
izaaklauer
changed the title
|
Hey, here’s your docs preview: https://clerk.com/docs/pr/2112 |
| 1. Select **Add connection**. You'll be redirected to the connection's configuration page. | ||
| 1. In the **Service Provider Configuration** section, save the **Reply URL (Assertion Consumer Service URL)** and **Identifier (Entity ID)** values somewhere secure. Keep this page open. | ||
| 1. Select **Add connection**. You'll be redirected to the connection's configuration page. Note that the connection is disabled by default. | ||
| 1. In the **Service Provider Configuration** section, note the **Reply URL (Assertion Consumer Service URL)** and **Identifier (Entity ID)**. These will need to be added to your customer's Microsoft Entra ID application. |
There was a problem hiding this comment.
to clarify: does the IT admin need to save these values to provide to the customer later?
There was a problem hiding this comment.
The app owner needs to save these values to provide to their customer IT admin.
Co-authored-by: Laura Beatris <[email protected]>
Co-authored-by: Laura Beatris <[email protected]>
Co-authored-by: Laura Beatris <[email protected]>
Co-authored-by: Alexis Aguilar <[email protected]>
LauraBeatris
force-pushed
the
izaak/orgs-597-azure
branch
from
f2a8f6d to
7c9eb66
Compare
alexisintech
approved these changes
Apr 2, 2025
This was referenced Apr 2, 2025
alexisintech
added a commit
that referenced
this pull request
May 27, 2025
Co-authored-by: Laura Beatris <[email protected]> Co-authored-by: Alexis Aguilar <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Preview: https://clerk.com/docs/pr/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 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 😆 .