Skip to content

Add self-serve SSO docs#3349

Open
im2nguyen wants to merge 11 commits intomainfrom
tu/self-serve-sso-docs
Open

Add self-serve SSO docs#3349
im2nguyen wants to merge 11 commits intomainfrom
tu/self-serve-sso-docs

Conversation

@im2nguyen
Copy link
Copy Markdown
Contributor

@im2nguyen im2nguyen commented May 7, 2026

🔎 Previews:

⚠️ this component haven't been released yet, we're working on an internal experimental version for testing

What does this solve? What changed?

  • We're working on a new feature to support self-serve SSO. Initially, we're releasing only <ConfigureSSO/> so folks can embed this component to enable this feature.

Deadline

  • Aiming to get feature complete and shipped by Friday (05/08). Ideally by then 🙏

Other resources

@im2nguyen im2nguyen requested a review from a team as a code owner May 7, 2026 03:32
@vercel
Copy link
Copy Markdown

vercel Bot commented May 7, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-docs Ready Ready Preview May 8, 2026 5:22pm

Request Review

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 7, 2026

⚠️ TypeDoc files detected in this PR

This PR modifies files in the 'clerk-typedoc/' folder. These files are auto-generated from the clerk/javascript repository and should not be edited directly.

To make changes to TypeDoc documentation:

  1. 🔄 Make your changes in the appropriate files in the clerk/javascript repository.
  2. 🚀 The TypeDoc documentation will be pulled through to this repository via a CI action.

Thanks for contributing! 🙏

@@ -0,0 +1,7 @@
---
title: '`OAuthConsentInfo`'
description: An interface that represents OAuth consent information.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this added due to a bad git rebase?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah this looks like it's from this PR

Comment thread docs/reference/components/authentication/configure-sso.mdx Outdated
Comment thread docs/reference/components/authentication/configure-sso.mdx Outdated
Comment thread docs/reference/components/authentication/configure-sso.mdx Outdated
sdk: astro, nextjs, react, tanstack-react-start, vue, js-frontend
---

The `<ConfigureSSO />` component renders a guided wizard that lets a signed-in user — typically the IT admin at one of your enterprise customers — configure an enterprise SSO connection end-to-end without leaving your application or touching the Clerk Dashboard.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add an screenshot of the component once we release it

<If sdk="astro">
```astro {{ filename: 'src/pages/sso-setup.astro' }}
---
import { __experimental_ConfigureSSO as ConfigureSSO } from '@clerk/astro/components'
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll remove the __experimental prefix from here before releasing it GA - this is just used in the SDK now so we can incrementally implement internally

@SarahSoutoul SarahSoutoul self-assigned this May 7, 2026
Comment on lines -72 to +74

1. In the Okta dashboard, find the **Attribute Statements (optional)** section.
1. For the **Name** field, enter `mail`.
1. For the **Value** field, choose `user.email` from the dropdown.
1. Select the **Add Another** button to add another attribute.
1. For the **Name** field, enter `firstName`.
1. For the **Value** field, choose `user.firstName` from the dropdown.
1. Select the **Add Another** button to add another attribute.
1. For the **Name** field, enter `lastName`.
1. For the **Value** field, choose `user.lastName` from the dropdown.
1. Scroll to the bottom of the page and select the **Next** button to continue.
1. You will be redirected to the **Feedback** page. Fill out the feedback however you would like and select the **Finish** button to complete the setup.
| Attribute | Required | Claim name |
| - | - | - |
| Email address | ✅ | `user.email` |
| First name | ❌ | `user.firstName` |
| Last name | ❌ | `user.lastName` |

Okta uses these values by default, so you probably won't need to configure them manually. However, incorrect attribute mappings cause many SAML configuration errors. If the integration doesn't work as expected, define the attributes explicitly:

1. In the Okta dashboard, find the **Attribute Statements** section.
1. Select **Add expression** for each attribute, and enter the following name and expression pairs:
- `mail` and `user.profile.email`
Copy link
Copy Markdown
Member

@LauraBeatris LauraBeatris May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this due to the Okta UI changes? They recently updated the UI for attribute statements and our copy here was using the "legacy" UI

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep, this is the new ui changes. using expressions instead of legacy ui

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

e75b5d5

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should also update self-serve sso to use these instructions too 👀

Comment thread docs/guides/configure/auth-strategies/enterprise-connections/self-serve-sso.mdx Outdated
@LauraBeatris LauraBeatris marked this pull request as draft May 7, 2026 16:59
Co-authored-by: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com>
@im2nguyen im2nguyen marked this pull request as ready for review May 8, 2026 17:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants