@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/sso/index.mdx

@@ -0,0 +1,295 @@
+---
+title: Single Sign-On
+description: "Facilitate greater security, easier account management, and\_accelerated application onboarding and adoption."
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/sso/index.mdx
+---
+
+## Choose your integration approach
+
+There are two ways to integrate Single Sign-On (SSO) with WorkOS:
+
+### (A) With the standalone SSO API
+
+The standalone API (covered in this document), is a standalone API for integrating into an existing auth stack.
+
+### (B) Using WorkOS User Management
+
+[User Management](/user-management) is a complete authentication platform which includes SSO out of the box.
+
+## How Single Sign-On works
+
+Single Sign-On is the most frequently asked for requirement by organizations looking to adopt new SaaS applications. SSO enables authentication via an organization’s [identity provider (IdP)](/glossary/idp).
+
+This service is compatible with any IdP that supports either the [SAML](/glossary/saml) or [OIDC](/glossary/oidc) protocols. It’s modeled to meet the [OAuth 2.0](/glossary/oauth-2-0) framework specification, abstracting away the underlying authentication handshakes between different IdPs.
+
+![Authentication Flow Diagram](https://images.workoscdn.com/images/90b84f08-3363-446a-8610-f7b2bd2ee2ca.png?auto=format&fit=clip&q=80)[border=false]
+
+WorkOS SSO API acts as authentication middleware and intentionally does not handle user database management for your application.
+
+## What you’ll build
+
+In this guide, we’ll take you from learning about Single Sign-On and POC-ing all the way through to authenticating your first user via the WorkOS SSO API.
+
+## Before getting started
+
+To get the most out of this guide, you’ll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+- A local app to integrate SSO with.
+
+Reference these [example apps](/sso/example-apps) as you follow this guide.
+
+## API object definitions
+
+[Connection](/reference/sso/connection)
+: The method by which a group of users (typically in a single organization) sign in to your application.
+
+[Profile](/reference/sso/profile)
+: Represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized and raw attributes.
+
+## (1) Add SSO to your app
+
+Let’s build the SSO authentication workflow into your app.
+
+### Install the WorkOS SDK
+
+WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.
+
+<LanguageSelector>
+  Install the SDK using the command below.
+
+  <CodeBlock title="Install the WorkOS SDK" file="install-sdk">
+    <CodeBlockTab language="js" file="install-sdk-npm" title="npm" />
+    <CodeBlockTab language="js" file="install-sdk-yarn" title="Yarn" />
+    <CodeBlockTab language="java" file="install-sdk-maven" title="Maven" />
+    <CodeBlockTab language="java" file="install-sdk-gradle" title="Gradle" />
+    <CodeBlockTab language="ruby" file="install-sdk-terminal" title="Terminal" />
+    <CodeBlockTab language="ruby" file="install-sdk-bundler" title="Bundler" />
+  </CodeBlock>
+</LanguageSelector>
+
+### Set secrets
+
+To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app’s configuration based on your preferences.
+
+```plain title="Environment variables"
+WORKOS_API_KEY='sk_example_123456789'
+WORKOS_CLIENT_ID='client_123456789'
+```
+
+> The code examples use your staging API keys when [signed in](https://dashboard.workos.com)
+
+### Add an endpoint to initiate SSO
+
+The endpoint to initiate SSO via the WorkOS API is responsible for handing off the rest of the authentication workflow to WorkOS. There are a couple configuration options shown below.
+
+You can use the optional `state` parameter to encode arbitrary information to help restore application state between redirects.
+
+- | Using organization ID
+
+  Use the organization parameter when authenticating a user by their specific organization. This is the preferred parameter for SAML and OIDC connections.
+
+  The example below uses the Test Organization that is available in your staging environment and uses a mock identity provider. It’s created to help you test your SSO integration without having to go through the process of setting up an account with a real identity provider.
+
+  <CodeBlock
+    title="Authentication Endpoint"
+    file="get-authorization-with-organization-id"
+  >
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-organization-id-next"
+      title="Next.js"
+    />
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-organization-id-next-app-router"
+      title="Next.js (App Router)"
+    />
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-organization-id-express"
+      title="Express"
+    />
+    <CodeBlockTab
+      language="ruby"
+      file="get-authorization-with-organization-id-rails"
+      title="Rails"
+    />
+    <CodeBlockTab
+      language="ruby"
+      file="get-authorization-with-organization-id-sinatra"
+      title="Sinatra"
+    />
+    <CodeBlockTab
+      language="python"
+      file="get-authorization-with-organization-id-django"
+      title="Django"
+    />
+    <CodeBlockTab
+      language="python"
+      file="get-authorization-with-organization-id-flask"
+      title="Flask"
+    />
+  </CodeBlock>
+
+- | Using connection ID
+
+  You can also use the connection parameter for SAML or OIDC connections when authenticating a user by their connection ID.
+
+  <CodeBlock
+    title="Authentication Endpoint"
+    file="get-authorization-with-connection-id"
+  >
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-connection-id-next"
+      title="Next.js"
+    />
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-connection-id-next-app-router"
+      title="Next.js (App Router)"
+    />
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-connection-id-express"
+      title="Express"
+    />
+    <CodeBlockTab
+      language="ruby"
+      file="get-authorization-with-connection-id-rails"
+      title="Rails"
+    />
+    <CodeBlockTab
+      language="ruby"
+      file="get-authorization-with-connection-id-sinatra"
+      title="Sinatra"
+    />
+    <CodeBlockTab
+      language="python"
+      file="get-authorization-with-connection-id-django"
+      title="Django"
+    />
+    <CodeBlockTab
+      language="python"
+      file="get-authorization-with-connection-id-flask"
+      title="Flask"
+    />
+  </CodeBlock>
+
+- | Using provider
+
+  The provider parameter is used for OAuth connections which are configured at the environment level.
+
+  > The supported `provider` values are `GoogleOAuth`, `MicrosoftOAuth`, `GitHubOAuth`, and `AppleOAuth`.
+
+  <CodeBlock
+    title="Authentication Endpoint"
+    file="get-authorization-with-provider"
+  >
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-provider-next"
+      title="Next.js"
+    />
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-provider-next-app-router"
+      title="Next.js (App Router)"
+    />
+    <CodeBlockTab
+      language="js"
+      file="get-authorization-with-provider-express"
+      title="Express"
+    />
+    <CodeBlockTab
+      language="ruby"
+      file="get-authorization-with-provider-rails"
+      title="Rails"
+    />
+    <CodeBlockTab
+      language="ruby"
+      file="get-authorization-with-provider-sinatra"
+      title="Sinatra"
+    />
+    <CodeBlockTab
+      language="python"
+      file="get-authorization-with-provider-django"
+      title="Django"
+    />
+    <CodeBlockTab
+      language="python"
+      file="get-authorization-with-provider-flask"
+      title="Flask"
+    />
+  </CodeBlock>
+
+If there is an issue generating an authorization URL, WorkOS will return the redirect URI as is. Read the [API Reference](/reference/sso/get-authorization-url) for more details.
+
+### Add a callback endpoint
+
+Next, let’s add the redirect endpoint which will handle the callback from WorkOS after a user has authenticated with their identity provider. This endpoint should exchange the authorization code returned by WorkOS with the authenticated user’s profile. The authorization code is valid for 10 minutes.
+
+<CodeBlock file="callback-endpoint" title="Callback Endpoint">
+  <CodeBlockTab language="js" file="callback-endpoint-next" title="Next.js" />
+  <CodeBlockTab
+    language="js"
+    file="callback-endpoint-next-app-router"
+    title="Next.js (App Router)"
+  />
+  <CodeBlockTab
+    language="js"
+    file="callback-endpoint-express"
+    title="Express"
+  />
+  <CodeBlockTab language="ruby" file="callback-endpoint-rails" title="Rails" />
+  <CodeBlockTab
+    language="ruby"
+    file="callback-endpoint-sinatra"
+    title="Sinatra"
+  />
+  <CodeBlockTab
+    language="python"
+    file="callback-endpoint-django"
+    title="Django"
+  />
+  <CodeBlockTab
+    language="python"
+    file="callback-endpoint-flask"
+    title="Flask"
+  />
+</CodeBlock>
+
+When adding your callback endpoint, it is important to always validate the returned profile’s organization ID. It’s unsafe to validate using email domains as organizations might allow email addresses from outside their corporate domain (e.g. for guest users).
+
+---
+
+## (2) Configure a redirect URI
+
+Go to the [Redirects](https://dashboard.workos.com/redirects) page in the dashboard to configure allowed redirect URIs. This is your callback endpoint you used in the previous section.
+
+Multi-tenant apps will typically have a single redirect URI specified. You can set multiple redirect URIs for single-tenant apps. You’ll need to be sure to specify which redirect URI to use in the WorkOS client call to fetch the authorization URL.
+
+> WorkOS staging environments allow wildcard characters in redirect URIs. More information about wildcard characters support can be found in the [Redirect URIs](/sso/redirect-uris/wildcard-characters) guide.
+> Query parameters are not allowed in any environment.
+
+![Redirects in the Dashboard](https://images.workoscdn.com/images/195dbff3-adbf-4010-b07c-ffc73ceeca68.png?auto=format&fit=clip&q=90)
+
+### Identity provider-initiated SSO
+
+Normally, the default redirect URI you configure in the WorkOS dashboard is going to be used for all identity provider-initiated SSO sessions. This is because the WorkOS client is not used to initiate the authentication flow.
+
+However, your customer can specify a separate redirect URI to be used for all their IdP-initiated sessions as a `RelayState` parameter in the SAML settings on their side.
+
+Learn more about configuring IdP-initiated SSO in the [Login Flows](/sso/login-flows/idp-initiated-sso/configure-idp-initiated-sso) guide.
+
+---
+
+## (3) Test end-to-end
+
+If you followed this guide, you used the Test Organization available in your staging environment to initiate SSO. With that, you can already test your integration end-to-end.
+
+![Test SSO WorkOs Dashboard](https://images.workoscdn.com/images/7b7407d7-dcc7-4fd4-859f-4ee4214d69c2.png?auto=format&fit=clip&q=80)
+
+Head to the _Test SSO_ page in the [WorkOS Dashboard](https://dashboard.workos.com/) to get started with testing common login flows, or read on about that in detail in the next guide.

package/.docs/organized/docs/sso/it-team-faq.mdx

@@ -0,0 +1,35 @@
+---
+title: FAQ for IT teams
+description: Answers to common questions from your customer’s IT team.
+originalPath: .tmp-workos-clone/packages/docs/content/sso/it-team-faq.mdx
+---
+
+## What is WorkOS?
+
+WorkOS is a software company that provides a suite of products to make an app enterprise-ready. These products include Single Sign-On, Directory Sync, and User Management, among others.
+
+Developers integrate WorkOS services into their apps in order to provide a secure authentication and user provisioning experience. It’s trusted by companies like Webflow, Plaid, Vercel, and many others.
+
+## What data does WorkOS store?
+
+For Single Sign-On, WorkOS stores the user profile from the identity provider. This includes the user's name, email and IP address.
+
+For Directory Sync, WorkOS will store the data that the identity provider sends. The shape and content of that data is at the discretion of the identity provider.
+
+For more information, view our [Privacy Policy](https://workos.com/legal/privacy)
+
+## How do developer apps communicate with WorkOS?
+
+Developers integrate with WorkOS using its Rest API and the related SDKs. You can find a list of all WorkOS API endpoints in the [API reference](/reference).
+
+## What IP addresses does WorkOS use?
+
+WorkOS uses Cloudflare to ensure security and reliability of all operations. If you are looking to create a list of allowed IP addresses for the WorkOS API, you can use the IP ranges listed in the [Cloudflare documentation](https://www.cloudflare.com/ips/).
+
+## Is WorkOS certified for SOC 2 Type II, SOC 3 and SIG Lite?
+
+Yes, WorkOS is compliant with all the above and regularly undergoes penetration testing.
+
+## Is WorkOS GDPR compliant?
+
+Yes, WorkOS is GDPR compliant. Reach out to [support](mailto:support@workos.com) to request deletion of data.

package/.docs/organized/docs/sso/jit-provisioning.mdx

@@ -0,0 +1,101 @@
+---
+title: Just-In-Time User Provisioning
+description: Learn how to provision users in your app using Just-In-Time user provisioning.
+originalPath: .tmp-workos-clone/packages/docs/content/sso/jit-provisioning.mdx
+---
+
+## Introduction
+
+User provisioning is the process of creating a user account and associated identity information. There are various ways for an application to provision users. This guide explores user provisioning strategies and offers a deep dive into SSO-based just-in-time (JIT) user provisioning.
+
+## Definitions
+
+**User provisioning**
+: Provisioning is the process of creating a user and setting attributes for them inside an app.
+
+**JIT user provisioning**
+: Just-in-time user provisioning creates a user in an app when the user attempts to sign in for the first time. The account and respective role don’t exist until the app creates them – just-in-time.
+
+**Identity**
+: An identity is a collection of attributes associated with a user or entity in an identity provider. For example, an identity includes at least one unique identifier, such as id, and user profile attributes, such as name and email.
+
+**Role**
+: A primitive in your app that defines specific permissions for the users. Roles are often defined as an ability or a job title, for example, “Editor” or “Accountant”.
+
+## User provisioning strategies
+
+User provisioning is the process of creating a user account with associated identity data in your app. Your app needs to determine a unique identifier for an identity, create a unique account for that user, and link the identity profile attributes to that user’s account. There are many strategies to provision users in an app, but the main three are:
+
+1. Self-registration
+2. Provisioning users via [Directory Sync](/directory-sync)
+3. JIT provisioning via SSO
+
+The type of provisioning needed will depend on your app’s architecture and level of enterprise feature support:
+
+| Strategy               | Description                                                           | Usage                                                                                                |
+| ---------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Self-registration      | Users fill out a registration form to create an account in the app    | For users that don’t have an SSO service, usually the first authentication mechanism built in an app |
+| Pre-provisioning users | Use a service like Directory Sync to create users in the app          | Required by large enterprises to automatically provision users                                       |
+| JIT provisioning       | Create a user account when a user signs in via SSO for the first time | Leverage user identity from an SSO provider to create an account in your app                         |
+
+## What is JIT provisioning?
+
+JIT provisioning creates a user account with associated identity information when a user authenticates via SSO for the first time. IT admins often use JIT provisioning to quickly set up accounts in an app. Typically, apps that implement only SSO will have JIT provisioning support as the alternative is self-registration by individual users or manual entry of all users by the IT admin.
+
+### Sample scenario
+
+Consider the fictional SaaS company _HireOS_, which offers recruiting software to other businesses. _HireOS_ is an online app allowing customers to track leads, candidates, and interviews.
+
+_HireOS_ has integrated SSO using WorkOS and supports JIT provisioning. For example, a _HireOS_ customer would like their users to have accounts automatically provisioned in _HireOS_ when they first log in. The customer’s IT admin will only need to assign the users to the _HireOS_ SAML app in their identity provider. When users log into _HireOS_ via SSO, they will have accounts created in _HireOS_, just in time.
+
+A usual account setup flow using JIT provisioning follows these steps:
+
+1. An IT admin self-registers via username and password to create a team account in _HireOS_.
+2. The IT admin configures the _HireOS_ team account to use SSO as the authentication mechanism.
+3. The IT admin enables JIT provisioning for this team account by clicking the "Enable JIT Provisioning" checkbox.
+4. The IT admin adds the users that should get access to _HireOS_ to the app in the identity provider.
+5. When a user logs into _HireOS_ with the correct email domain and authenticates via SSO, _HireOS_ creates the user account upon successful first-time login.
+
+## JIT provisioning with WorkOS SSO
+
+When a user authenticates to your app via SSO for the first time, and JIT provisioning is enabled, your app provisions a new user account. You can create the account by saving the identity information (the WorkOS SSO profile) directly on your app's user account. Or, you can create a separate identity from the WorkOS SSO profile related to this new user account. This logic allows users to have multiple identities if your app supports several login methods per user.
+
+You can use the WorkOS SSO profile `id` attribute as the unique identifier for this identity from WorkOS. WorkOS ensures the profile is unique per SSO connection via the `idp_id`. In addition, your app can use either the `connection_id` or `organization_id` to tie the identity to a team account.
+
+```json language="json" title="SSO user profile"
+{
+  "object": "profile",
+  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
+  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
+  "connection_type": "OktaSAML",
+  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
+  "email": "todd@example.com",
+  "first_name": "Todd",
+  "last_name": "Rundgren",
+  "idp_id": "00u1a0ufowBJlzPlk357",
+  "role": {
+    "slug": "admin"
+  },
+  "raw_attributes": {}
+}
+```
+
+You may want to grant new users roles in your application via JIT provisioning. For more information on mapping role data between the IdP and your app, see the [Mapping Roles](/sso/identity-provider-role-assignment) guide.
+
+### New account creation
+
+When your app receives a WorkOS SSO profile, it is standard to perform the following series of checks:
+
+1. Find an identity with the profile `id` or `idp_id`. If found, log in the corresponding user.
+2. If you cannot find an identity, try to find a user with the same `email` as the profile. If found, create an identity for the user and log them in.
+3. Otherwise, create a new identity using the WorkOS SSO profile, create a new user, and associate this identity with the user account.
+
+### Linking an existing user
+
+If an admin adds SSO authentication to their team account after they've had users register, your app can link these new SSO identities to the current user accounts, just-in-time.
+
+A linking field (e.g. `email`) should be established to find a current user with the incoming WorkOS SSO Profile. Then, the identity information can be linked with the existing user account via a persistent identifier in case of an email change later.
+
+## Implementing SSO with WorkOS
+
+This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [User Management](/user-management), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

package/.docs/organized/docs/sso/launch-checklist.mdx

@@ -0,0 +1,71 @@
+---
+title: Launch Checklist
+description: Make sure you’re ready to take your app to production.
+originalPath: .tmp-workos-clone/packages/docs/content/sso/launch-checklist.mdx
+---
+
+## Implement complementary enterprise features
+
+- Integrate the WorkOS [Admin Portal](/admin-portal) to enable your users to onboard and set up SSO themselves.
+- Integrate the WorkOS Directory Sync API for automatic user updating, provisioning, and deprovisioning.
+
+### Before you start
+
+This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [User Management](/user-management), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.
+
+## Create an IP Allowlist
+
+WorkOS makes use of Cloudflare to ensure security and reliability of all operations. If you are looking to create a list of allowed IP addresses for redirect requests, you can use the IP Ranges listed in the [Cloudflare documentation](https://www.cloudflare.com/ips/).
+
+## Go-live checklist
+
+- [ ] Implement an SSO UI/UX. See our guide for ideas – [UI/UX Best Practices for IdP & SP-Initiated SSO](https://workos.com/blog/ui-ux-best-practices-for-idp-and-sp-initiated-sso)
+- [ ] [Test the end-to-end SSO](/sso/test-sso) experience in your Staging environment.
+- [ ] Unlock your Production environment by adding your billing information
+  > Only enterprise connections in your Production environment will be charged. OAuth connections in Production will be free.
+- [ ] Set your Production Client’s ID and API Key as environment variables
+- [ ] Secure your Production Project’s API key
+- [ ] Configure production redirect URI(s) in your Product Project. Verify the default redirect URI is correct
+- [ ] Ensure that your application can receive redirects from WorkOS.
+      Depending on your network architecture, you may need to allowlist incoming redirect traffic from `api.workos.com`.
+- [ ] Add Connections for your customers in the Production Environment
+
+## Frequently asked questions
+
+### How should an application handle the first time a user authenticates using WorkOS?
+
+If a user is authenticating to your application for the first time via SSO and doesn’t have an account, you can implement just-in-time provisioning to create a user when authentication is complete.
+
+You can also leverage [Directory Sync](/directory-sync) to pre-provision users with API endpoints or webhooks. In this case, the user will already be created in your application when they authenticate for the first time.
+
+### Can we add SSO authentication for a current user in an application?
+
+If a user is authenticating to your application via SSO, but already has an account (with username/password for example), you can “upgrade” them to SSO. Usually the emails are the same for both methods of authentication, so you can match on email address. Once SSO via WorkOS is enabled, you can restrict users to sign in with only SSO.
+
+### How does WorkOS manage user attributes from an identity provider?
+
+WorkOS normalizes user attributes so you can expect known values such as `id`, `email`,`firstName`, and `lastName`.
+
+### Is the user attribute mapping configurable in WorkOS?
+
+Yes. For example, let’s say the `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` attribute contains the user email rather than the `surname` as the attribute name suggests. In these edge cases, WorkOS will identify any attributes that are misconfigured and recommend correct mapping in the “Attribute Mapper“ section of the “Connection info” page.
+
+### What does the “Allow Profiles Outside Organization” option do?
+
+By default, WorkOS restricts user profiles for SAML Connections to profiles that have email domains that are in the set of [User Email Domains](/reference/organization-domain) on the Organization.
+
+Enabling this option removes this restriction and allows user profiles with any email address to sign in through Connections under this Organization.
+
+If this option is enabled, your code can not exclusively trust the returned `email` attribute on user profiles to be a verified email address. Instead, you must use the `organization_id` or `connection_id` in order to verify that the profile belongs to whom it claims.
+
+### What does “There are 0 profiles awaiting reconciliation” refer to?
+
+This refers to the number of user profiles that have inconsistent attribute mappings, and that need to be updated in order to successfully authenticate.
+
+### How do I integrate WorkOS SSO with my native mobile application?
+
+When it comes to mobile applications, our typical advice in implementing SSO authentication goes like this:
+
+1. Generate the authentication URL and route the user to a browser or browser fragment in order to authenticate.
+2. The end user authenticates via the native UI of their IdP within that browser.
+3. Upon successful authentication, deep-link the user back into your native application.

package/.docs/organized/docs/sso/login-flows.mdx

@@ -0,0 +1,101 @@
+---
+title: Login Flows
+description: "Learn the differences between SP‑initiated and IdP‑initiated\_SSO."
+originalPath: .tmp-workos-clone/packages/docs/content/sso/login-flows.mdx
+---
+
+The instructions in the [Quick Start guide](/sso) focus on setting up Service Provider (SP)-initiated SSO. In these scenarios, when a user attempts to login, they navigate to an application (a service provider) and are then redirected to the [Identity Provider (IdP)](/glossary/idp) for authentication, via the WorkOS API.
+
+Alternatively, most users are able to start the process from the Identity Provider itself. Organizations will often provide an IdP dashboard where employees can select any of the eligible applications that they can access via the IdP, similar to the screenshot below. Clicking on a tile results in an IdP-initiated login flow, since the user initiates the login from the Identity Provider, not the application.
+
+![Screenshot of the Okta dashboard](https://images.workoscdn.com/images/1489f46f-bbcd-4e47-a217-3a45f0f795aa.png?auto=format&fit=clip&q=50)
+
+---
+
+## SP-initiated SSO
+
+With an SP-initiated login flow, the user begins the authentication process from your application. You can control where the user will be redirected after login by specifying the `redirectURI` parameter when making the [Get Authorization URL](/reference/sso/get-authorization-url) call. Additionally, this call can take an optional `state` parameter - this parameter will be returned in the callback after authentication, where your application can use it to verify the validity of the response or to pass any state from the originating session. One common practice is to route requests from different Organizations to a single Redirect URI, but instead utilize the `state` parameter to deep link users into the application after the authentication is completed.
+
+<CodeBlock file="get-authorization-url" title="Get Authorization URL Call" />
+
+---
+
+## IdP-initiated SSO
+
+If you follow the instructions in the [Quick Start guide](/sso), IdP-initiated login flows will automatically be available, and users will be able to find a tile for your application within their IdP, similar to the screenshot above. Clicking on the tile will send an IdP-initiated SSO response to your application's callback endpoint.
+
+### Configure IdP-initiated SSO
+
+Additionally, since IdP-initiated flows do not generate a customized authorization URL the way SP-initiated flows do, there is no way to dynamically pass the `redirectURI` and `state` parameters to your application's callback. By default, users will be redirected to the default Redirect URI upon a successful login. However, IdP Administrators can customize the redirect destination by configuring a default `RelayState` in the IdP, and including a `redirect_uri` parameter in it. The URI must be specified in the format of a URL parameter: `redirect_uri=uri`, and the URI must be one of the Redirect URIs specified in your WorkOS [Dashboard](https://dashboard.workos.com). Any other values in the IdP’s `RelayState` will be ignored and discarded.
+
+Your application will also be able to retrieve the [Profile object](/reference/sso/profile) for the user upon successful authentication. If your IdP is unable to provide a `redirect_uri` in its default `RelayState`, or if you would like to generate a custom redirect URI for each user after they sign in, you can use the [Profile object](/reference/sso/profile) to dynamically generate a redirect URI.
+
+```json title="Example Profile"
+{
+  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
+  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
+  "connection_type": "okta",
+  "email": "todd@example.com",
+  "first_name": "Todd",
+  "idp_id": "00u1a0ufowBJlzPlk357",
+  "last_name": "Rundgren",
+  "object": "profile",
+  "raw_attributes": {}
+}
+```
+
+The Profile object includes the `connection_id` which identifies the connection that the profile is associated with in WorkOS. We recommend using the connection information for routing requests in an IdP-Initiated flow.
+
+### Disable IdP-initiated SSO (Beta)
+
+We have recently added Beta support for fully disabling IdP-initiated SSO logins for a connection. Once disabled, any attempted IdP-initiated requests will fail with an `idp_initiated_sso_disabled` error.
+
+> Disabling IdP-initiated SSO is currently in invite-only beta, please reach out to [WorkOS support](mailto:support@workos.com) if you’d like to use it or learn more about it.
+
+For applications that need to support IdP-initiated workflows, but would like to mitigate the security risks of unsolicited SAML responses, WorkOS recommends the following:
+
+- Disable IdP-initiated SSO for your connection.
+- Adjust your callback method to capture the `idp_initiated_sso_disabled` error.
+- Start a new SP-initiated request from the callback when the error is detected.
+
+The error callback will include the connection and organization ID’s, which can be used to request a new authorization URL for the SP-initiated request. The new request will generally be transparent to the user, as they are already logged in to the Identity Provider.
+
+<CodeBlock
+  file="callback-endpoint-idp-initiated"
+  title="Callback Endpoint with IdP-Initiated error support"
+>
+  <CodeBlockTab
+    language="js"
+    file="callback-endpoint-idp-initiated-next"
+    title="Next.js"
+  />
+  <CodeBlockTab
+    language="js"
+    file="callback-endpoint-idp-initiated-express"
+    title="Express"
+  />
+  <CodeBlockTab
+    language="ruby"
+    file="callback-endpoint-idp-initiated-rails"
+    title="Rails"
+  />
+  <CodeBlockTab
+    language="ruby"
+    file="callback-endpoint-idp-initiated-sinatra"
+    title="Sinatra"
+  />
+  <CodeBlockTab
+    language="python"
+    file="callback-endpoint-idp-initiated-django"
+    title="Django"
+  />
+  <CodeBlockTab
+    language="python"
+    file="callback-endpoint-idp-initiated-flask"
+    title="Flask"
+  />
+</CodeBlock>
+
+## Implementing SSO with WorkOS
+
+This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [User Management](/user-management), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

package/.docs/organized/docs/sso/redirect-uris.mdx

@@ -0,0 +1,44 @@
+---
+title: Redirect URIs
+description: >-
+  Learn what a redirect URI is and how it relates to Service Provider and
+  Identity Provider initiated login flows.
+originalPath: .tmp-workos-clone/packages/docs/content/sso/redirect-uris.mdx
+---
+
+## Introduction
+
+With a [WorkOS Service Provider (SP) initiated login flow](/sso), there are a series of exchanges that take place between a Service Provider (your application), WorkOS, and the IdP that’s being used to authenticate the user as shown in the diagram below. The [Redirect URI](/glossary/redirect-uri) is the location to which the user gets returned to after successfully completing the authentication with their [Identity Provider (IdP)](/glossary/idp).
+
+With an Identity Provider (IdP) initiated login flow, the approach is similar but the user will begin the login flow by clicking on the tile within their IdP platform instead of from your application.
+
+![Authentication Flow Diagram](https://images.workoscdn.com/images/90b84f08-3363-446a-8610-f7b2bd2ee2ca.png?auto=format&fit=clip&q=80)
+
+In WorkOS Production Environments, the Redirect URI to your application cannot use HTTP or localhost, however, Redirect URIs that use HTTP and localhost are allowed in Sandbox Environments.
+
+There should be at least one redirect URI configured and selected as a default for a WorkOS Environment. This can be done from the [Redirects](https://dashboard.workos.com/redirects) page in the WorkOS dashboard. If you try to route the authorization flow to a Redirect URI that is not yet defined in the Dashboard it will result in an error and users will be unable to sign in, so it’s important to define them in the dashboard first.
+
+![Dashboard UI showing redirects](https://images.workoscdn.com/images/f5d55c0d-0932-41c9-a372-09a9606cc5bb.png?auto=format&fit=clip&q=90)
+
+The Redirect URI can also be included directly in the Get Authorization URL call as a redirect_uri parameter. When the Redirect URI is set in this fashion, it will override the default Redirect URI that is set in the WorkOS Dashboard.
+
+---
+
+## Wildcard characters
+
+WorkOS supports using wildcard characters in Redirect URIs for staging environments.
+
+![WorkOS Dashboard UI editing a wildcard character in a redirect URI](https://images.workoscdn.com/images/951f3dc0-d654-48dd-af00-15f68e2880e5.png?auto=format&fit=clip&q=90)
+
+The `*` symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules in order to properly function.
+
+- The protocol of the URL **must not** be `http:` in Production Environments.
+- The wildcard **must** be located in a subdomain within the hostname component. For example, `http://*.com` will not work.
+- The wildcard **must** be located in the subdomain which is furthest from the root domain. For example, `https://sub.*.example.com` will not work.
+- The URL **must not** contain more than one wildcard. For example, `https://*.*.example.com` will not work.
+- A wildcard character **may** be prefixed and/or suffixed with additional valid hostname characters. For example, `https://prefix-*-suffix.example.com` will work.
+- A URL with a valid wildcard **will not** match a URL more than one subdomain level in place of the wildcard. For example, `https://*.example.com` will not work with `https://sub1.sub2.example.com`.
+
+## Implementing SSO with WorkOS
+
+This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [User Management](/user-management), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.