@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/sso/_sequence-diagrams/saml-protocol-security-considerations.md

@@ -0,0 +1,59 @@
+---
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/sso/_sequence-diagrams/saml-protocol-security-considerations.md
+---
+# Diagrams for 'SAML Security Considerations'
+
+Currently MermaidJS rendering is not supported in docs.workos.com, so to see the rendering you’ll need to view this file on the GitHub website (VS Code Markdown preview does not support rendering).
+Alternatively you could paste the contents into [Mermaid's live editor](https://mermaid.live/) to see rendering.
+
+In the WorkOS docs it is required to draw sequence diagrams in FigJam, you can use the Mermaid generated sequence diagram as a guide to copy from.
+
+## SP to IdP flows (SP initiated)
+
+```mermaid
+%%{
+  init: {
+    "sequence": {
+       "noteAlign": "left"
+    }
+  }
+}%%
+
+sequenceDiagram
+    autonumber
+    participant u as User Agent
+    participant a as Your Application
+    participant sp as WorkOS
+
+    u -->> a: Begin login flow
+    a ->> u: redirect to WorkOS
+    u ->> sp:
+    sp -->> sp: create SAML AuthN Request
+    note right of sp: Optional: <br><br> 1. Sign the whole SAML Request message (envelope)
+    sp ->> u: redirect to IdP with {SAML Request}
+```
+
+## IdP to SP flows (SP initiated)
+
+```mermaid
+%%{
+  init: {
+    "sequence": {
+       "noteAlign": "left"
+    }
+  }
+}%%
+
+sequenceDiagram
+    autonumber
+    participant u as User Agent
+    participant idp as IdP
+    participant sp as WorkOS
+
+    u ->> idp: present {SAML AuthN Request}
+    idp --> u: authenticate the user
+    idp -->> idp: create SAML AuthN Response
+    idp ->> u: redirect with {SAML Response} to WorkOS
+    u -->> sp:
+```

package/.docs/organized/docs/sso/attributes.mdx

@@ -0,0 +1,110 @@
+---
+title: Profile Attributes
+description: Configure how attributes map from identity providers to SSO Profiles.
+originalPath: .tmp-workos-clone/packages/docs/content/sso/attributes.mdx
+---
+
+## Introduction
+
+WorkOS automatically normalizes a standard set of attributes from identity providers (IdPs) into the [Single Sign-On (SSO) Profile](/reference/sso/profile) object. More unique cases can be mapped by your customer admins. In this guide, we’ll explain how to map data from identity providers to the SSO Profiles.
+
+## Definitions
+
+**Standard attributes**
+: The most common user information, normalized across providers.
+
+**Predefined attributes**
+: Detailed user attributes for specific use cases, normalized across providers. You can opt-in to each attribute you'd like organization admins to map during SSO connection configuration.
+
+**Custom attributes**
+: For unique cases, you can create custom attributes your customers can map when setting up an SSO connection.
+
+## Standard attributes
+
+Every SSO Profile comes with the following standard attributes. These are the core set of attributes that are common across all identity providers. These are structured fields with a guaranteed schema in the top-level SSO Profile payload.
+
+| Attribute    | Description                                                                                                            |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `idp_id`     | The user’s unique identifier, assigned by the identity provider. Different identity providers use different ID formats |
+| `email`      | The user’s email                                                                                                       |
+| `first_name` | The user’s first name                                                                                                  |
+| `last_name`  | The user’s last name                                                                                                   |
+
+---
+
+## Custom attributes
+
+For more detailed user information, you can opt-in to additional predefined attributes and define your own custom attributes. These attributes will appear in the `custom_attributes` field on [SSO Profile](/reference/sso/profile) objects and can be configured in the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+> Custom attributes are currently only supported for SAML SSO connections. If you are interested in custom attributes for OIDC and OAuth connections, please reach out to [support](mailto:support@workos.com).
+
+### Predefined attributes
+
+When enabled, organization admins will we asked to map these attributes during SSO configuration in [Admin Portal](/admin-portal). These fields are always optional if enabled. These fields are named and schematized by WorkOS – they cannot be renamed.
+
+| Attribute               | Type and description                                                                                                            | Status   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `addresses`             | The user’s list of address objects (`street_address`, `locality`, `region`, `postal_code`, `country`, `primary`, `raw_address`) | Optional |
+| `cost_center_name`      | The user’s cost center name                                                                                                     | Optional |
+| `department_name`       | The user’s department name                                                                                                      | Optional |
+| `division_name`         | The user’s division name                                                                                                        | Optional |
+| `emails`                | The user’s list of email objects (`type`, `value`, `primary`)                                                                   | Optional |
+| `employee_type`         | The user’s employment type                                                                                                      | Optional |
+| `employment_start_date` | The user’s start date                                                                                                           | Optional |
+| `job_title`             | The user’s job title                                                                                                            | Optional |
+| `manager_email`         | The email address for the user’s manager                                                                                        | Optional |
+| `username`              | The user’s username                                                                                                             | Optional |
+
+#### Enable or disable a predefined attribute
+
+Predefined attributes can be enabled or disabled in the [WorkOS Dashboard](https://dashboard.workos.com/) on the Identity Provider Attributes page.
+
+![WorkOS Dashboard UI showing editing predefined attributes](https://images.workoscdn.com/images/73b775ed-c3ef-4c81-bb56-7b040d3d073a.png?auto=format&fit=clip&q=50)
+
+> For SSO Profiles, making changes to IdP attributes will take effect upon next sign-in.
+
+### Custom attributes
+
+Custom attributes can be utilized to enrich SSO Profiles with additional data from the identity provider. You can create attributes that appear as fields in the [Admin Portal](https://workos.com/admin-portal). Your customers can map these fields to the correct values in their system when setting up SSO with their identity provider.
+
+#### Create a custom attribute
+
+Custom attributes can be created in the [WorkOS Dashboard](https://dashboard.workos.com/) on the Identity Provider Attributes page.
+
+![WorkOS Dashboard UI showing custom attribute creation](https://images.workoscdn.com/images/c1d00c4c-4dea-415e-a8f8-c870317410df.png?auto=format&fit=clip&q=50)
+
+> For SSO Profiles, making changes to IdP attributes will take effect upon next sign-in.
+
+#### Delete a custom attribute
+
+When a custom attribute is deleted, [SSO Profiles](/reference/sso/profile) will retain these existing attribute values until the next sign-in.
+
+#### Editing attribute mappings
+
+If attribute data for a particular SSO connection has changed and is no longer mapped properly, you or the organization admin can edit the attribute mappings via the [WorkOS Dashboard](https://dashboard.workos.com/) connection page or [Admin Portal](https://workos.com/admin-portal), respectively.
+
+![WorkOS Dashboard UI showing editing attribute mappings for a connection](https://images.workoscdn.com/images/09395b6c-d037-440f-a17e-ef0507868532.png?auto=format&fit=clip&q=50)
+
+### Custom attribute mapping in Admin Portal
+
+You can control the visibility of custom attribute mapping for Directory Sync and Single Sign-On flows in the Admin Portal at the environment and organization level.
+
+The environment-level setting is controlled on the Identity Provider Attributes page in the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+![WorkOS Dashboard UI showing editing custom attribute mapping in Admin Portal setting](https://images.workoscdn.com/images/23ee5439-6cbb-4c18-ac39-0870d63bfc0b.png?auto=format&fit=clip&q=50)
+
+Organization-level settings are controlled on an individual organization's Attributes tab in the [WorkOS Dashboard](https://dashboard.workos.com/). Organizations mirror the environment-level settings by default.
+
+## Frequently asked questions
+
+### Which identity providers support mapping additional predefined and custom attributes?
+
+Additional predefined and custom attributes are supported for all SAML SSO connections.
+
+### Can our customers add their own custom attributes outside of what is defined in the WorkOS Dashboard?
+
+We do not currently support this functionality. Custom attributes must be defined in the WorkOS Dashboard first. Please reach out to [support](mailto:support@workos.com) if you have a specific use case that you would like to discuss.
+
+### What happens if an attribute cannot be mapped from the IdP?
+
+Attributes that cannot be mapped for a particular [SSO Profile](/reference/sso/profile) will result in a `null` value for the attribute.

package/.docs/organized/docs/sso/domains.mdx

@@ -0,0 +1,111 @@
+---
+title: Domains
+description: Understand how Organization domains are used with SSO.
+originalPath: .tmp-workos-clone/packages/docs/content/sso/domains.mdx
+---
+
+## Organizations
+
+When an [Organization](/reference/organization) is created in the WorkOS Dashboard or the [Create Organization API](/reference/organization/create), one or more domains can be associated with the organization.
+
+Domains added to an organization need to be verified. In the API, they can be initially added `'pending'` verification, and later verified using the [Domain Verification API](/domain-verification). Or, if previously verified through other means, can be added as `'verified'`.
+
+> Domains in the WorkOS Dashboard are always considered verified.
+
+## Email validation
+
+During authentication, WorkOS uses these domains to verify the user signing in through the organization's [Connection](/reference/sso/connection) belongs to one of these domains. If the domain of the user's email address does not match one of the organization's domains (or the organization has no verified domains) they will sent to your [Redirect URI](/sso/redirect-uris) with a [`profile_not_allowed_outside_organization`](/reference/sso/get-authorization-url/error-codes) error.
+
+Rejecting users with non-matching email domains prevents the impersonation of users in other organizations. This would otherwise be possible since many Identity Providers allow IT admins to create user accounts with _any_ email address, regardless if the IT admin actually controls the email address or its domain.
+
+For example, an IT admin of an organization with the domain `foo.com` can create a user account for `user@bar.com` in their Identity Provider and then sign in as that user. If the application were to receive the profile and naively look up the user record using _only_ the email address, then the IT admin will have gained access to the `user@bar.com` account.
+
+Since WorkOS cannot guarantee every application handles this scenario correctly, **the default behavior is to reject profiles when its email address does not match the associated organization's domains.**
+
+## Allowing any domain
+
+Some applications may have organizations whose users sign in using a list of domains that cannot be statically defined, or a set of domains so large as to be cumbersome to configure.
+
+A common use-case is non-domain guests. Imagine an organization hires a design consultancy and requires the designers to sign in using the organization's IdP. While the organization can create accounts in their IdP for these guests, they cannot add the designer's domain to the WorkOS organization since they cannot verify ownership of it. The default organization domain verification policy will prevent these designer's from signing in.
+
+If your application has a similar use-case, [contact support](mailto:support@workos.com) and we can work with you to relax the default organization domain verification policy. SSO will no longer require any domains to be added to the organization. This change can be made for any of your environments and will affect all organizations in the environment.
+
+## Implement profile validation
+
+Your application will be responsible for validating the email addresses of users using SSO, and checking the appropriate fields from the SSO profile.
+
+Important data from the SSO profile includes the `id` and the `organization_id`. Generally applications will store the Profile `id` alongside its users, such as a column on a `users` table. Similarly, the `organization_id` will be stored on the matching entity, such as a `teams` or `workspace` table; whichever represents a collection of users that are related to each other.
+
+```json language="json" title="SSO profile"
+{
+  "object": "profile",
+  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
+  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
+
+  // Your application should restrict any email-based JIT user
+  // provisioning to within the organization that matches this ID.
+  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
+
+  // Only match based on email or email domain unless if are
+  // filtering potential matches by the organization ID above.
+  "email": "todd@example.com"
+
+  // ...
+}
+```
+
+Here's a updated version of the WorkOS callback endpoint from the [Quick Start guide](/sso/1-add-sso-to-your-app/add-a-callback-endpoint) with examples of these checks added:
+
+```javascript langauge="JavaScript" title="WorkOS callback"
+const { WorkOS } = require('@workos-inc/node');
+const workos = new WorkOS(process.env.WORKOS_API_KEY);
+
+app.get('/callback', async (req, res) => {
+  const { profile } = await workos.sso.getProfileAndToken({
+    code: req.query.code,
+    clientId: process.env.WORKOS_CLIENT_ID,
+  });
+
+  // Your application should have a resource that is analogous to the WorkOS
+  // organization, like a "team" or "workspace".
+  const team = TeamsService.findByWorkOsOrganizationId(profile.organizationId);
+
+  if (!team) {
+    return res.status(401).send({
+      message: 'Unauthorized',
+    });
+  }
+
+  // Your application should use the Profile ID to determine whether there is an
+  // existing user linked to the SSO profile, within the scope of the "team" or
+  // "workspace" associated with the WorkOS organization.
+  //
+  // If none is found, you can then fall back to the `email` address. If one is
+  // found you should link the profile ID to the user for subsequent sign-ins.
+  //
+  // Finally, if no user exists with the email either, you can implement
+  // JIT-provisioning and create a new user record, persisting both the `email`
+  // and the ID from the profile.
+  const { user } = team.users.findOrCreateByWorkOsProfile(profile);
+
+  // Make sure to verify the user's email address. You may choose to skip
+  // email verification in order to improve UX, but should only do so if
+  // the new user's email address matches an expected domain for the "team".
+  if (!user.emailVerified) {
+    res.redirect('/verify-email');
+  } else {
+    // Start a session for the user.
+    // ...
+
+    res.redirect('/');
+  }
+});
+```
+
+> The above example makes use of JIT-provisioning, which you can read more about in more our dedicated [JIT-provisioning guide](/sso/jit-provisioning).
+
+With the above checks in place, your application can safely sign in and verify users through SSO from any domain.
+
+## Custom ACS domains
+
+While your users will authenticate with SSO using your application, they might briefly see the WorkOS [ACS URL](/glossary/acs-url). This can be configured in the production environment to a custom domain of your choosing. For more information see the [Custom Domains](/custom-domains) documentation.

package/.docs/organized/docs/sso/example-apps.mdx

@@ -0,0 +1,46 @@
+---
+title: Example Apps
+description: "View sample Single\_Sign-On apps for\_each\_SDK."
+originalPath: .tmp-workos-clone/packages/docs/content/sso/example-apps.mdx
+---
+
+You can view minimal example apps that demonstrate how to use the WorkOS SDKs to authenticate users via SSO:
+
+<ExampleApps.Root>
+  <ExampleApps.Card
+    href="https://github.com/workos/node-example-applications/tree/main/node-sso-example"
+    title="Node.js SSO app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/typescript-example-applications/tree/main/typescript-sso-example"
+    title="TypeScript SSO app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/ruby-example-applications/tree/main/ruby-sso-example"
+    title="Ruby SSO app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/python-flask-example-applications/tree/main/python-flask-sso-example"
+    title="Python Flask SSO app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/python-django-example-applications/tree/main/python-django-sso-example"
+    title="Python Django SSO app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/go-example-applications/tree/main/go-sso-example"
+    title="Go SSO app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/java-example-applications/tree/main/java-sso-example"
+    title="Java SSO app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/php-example-applications/tree/main/php-sso-example"
+    title="PHP SSO app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/dotnet-example-applications/tree/main/dotnet-sso-example"
+    title=".NET SSO app"
+  />
+</ExampleApps.Root>

package/.docs/organized/docs/sso/identity-provider-role-assignment.mdx

@@ -0,0 +1,113 @@
+---
+title: Identity Provider Role Assignment
+description: >-
+  Learn how to map role data from identity providers to roles in your app with
+  SSO.
+showNextPage: true
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/sso/identity-provider-role-assignment.mdx
+---
+
+## Introduction
+
+A role represents a logical grouping of permissions, defining access control levels for users within your application. Roles are identified by a unique, immutable slug and are assigned to [SSO user profiles](/reference/sso/profile) through their identity provider group memberships. These group role mappings can be configured on the WorkOS dashboard.
+
+## Configure roles
+
+You can manage roles in the _Roles & Permissions_ section of the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+![Roles section WorkOS Dashboard](https://images.workoscdn.com/images/d96e9c84-651d-4f5d-af3e-98e3d36b7a9f.png?auto=format&fit=clip&q=50)
+
+### Default role
+
+Role configuration occurs at the environment level. Each environment is seeded with a default `member` role, which is automatically assigned to every new profile. The default role cannot be deleted, but any role can be set as the default.
+
+If you need to set default roles or other role configurations at the organization level, refer to the [organization roles](/user-management/roles-and-permissions/organization-roles) documentation.
+
+### Priority order
+
+Role priority order determines which role is assigned when a user sign-ins with multiple groups that contain conflicting role mappings. In that scenario, the role with the highest priority will be assigned. For example, there might be a case where an employee _Jane_ is an _Engineering Manager_ and belongs to an “Engineering”, “Manager”, and “Admin” group. With group-based role assignment, the user will be assigned the role that has the highest priority defined.
+
+### Delete roles
+
+When a role is deleted, all SSO user profiles with that role will be granted the default role.
+
+> To migrate from one default role to another, set the new default role and delete the old one. SSO user profiles will then receive the new default role at the next sign-in.
+
+## SSO group role assignment
+
+Users are assigned to groups via the identity provider. Groups usually correspond to roles in your app. Therefore, IT admins will often map a group one-to-one to a role.
+
+During authentication, a user's identity provider group memberships can be read via attributes. This enables you to define SSO groups that correspond to IdP groups and set role assignments for those groups in the WorkOS Dashboard.
+
+Based on these settings, SSO user profiles returned from WorkOS will include a role attribute that reflects their highest priority group membership. The SSO user profile role is calculated during each sign-in.
+
+![Session page showing user profile with role defined](https://images.workoscdn.com/images/ceea13ba-bf6b-4ea1-a25c-0a08e8833fb0.png?auto=format&fit=clip&q=50)
+
+> Supported in both SAML and OIDC-based connection types, except for Okta OIDC. [Reach out to us](mailto:support@workos.com) if you need this for an Okta OIDC connection.
+
+### Sample scenario
+
+Consider the fictional SaaS company _HireOS_. _HireOS_ has set up an SSO Connection and configured group-based role assignment. For example, a _HireOS_ customer would like to assign their engineering team to the application. The customer’s IT admin would take the following steps:
+
+1. Create an “Engineering” group using their identity provider.
+2. Configure the `groups` attribute in their SAML app to return the group memberships.
+3. Provide the developer with the IdP ID for the "Engineering" group.
+
+In the WorkOS dashboard, the developer can then assign users of that group to the role "Developer".
+
+1. Navigate to the _Connection_ section of the WorkOS dashboard.
+
+![SSO group role assignment card](https://images.workoscdn.com/images/28606b9b-fd5b-4219-8b8f-3a640295e784.png?auto=format&fit=clip&q=50)
+
+2. Create an SSO group defining the IdP ID for the "Engineering" group. Then, assign this group to the "Developer" role.
+
+![Dialog to create connection group with role assignment](https://images.workoscdn.com/images/648410f3-1b82-4ebd-97f3-a8f6edbdd27e.png?auto=format&fit=clip&q=50)
+
+From this point on, whenever a user in the "Engineering" group authenticates via SSO, they will be granted the "Developer” role for that session from the WorkOS API. The role will be returned in the [profile response](/reference/sso/profile).
+
+```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": "developer"
+  },
+  "raw_attributes": {}
+}
+```
+
+> When a user is not a member of any groups or their groups do not match any SSO group role assignments, the user will be granted the [default role](/sso/identity-provider-role-assignment/configure-roles/default-role) in the SSO profile.
+
+### Role assignment in Admin Portal
+
+Once [roles](/sso/identity-provider-role-assignment/configure-roles) are configured for your application, enable SSO group role assignment in [Admin Portal](/admin-portal) to allow IT admins to assign roles to groups during SSO connection setup. If enabled, all Admin Portal sessions for SSO connections will have the ability to configure and assign roles to groups.
+
+![Enable SSO group role assignment dashboard setting](https://images.workoscdn.com/images/04f86ccc-87a1-4db6-bd54-54a685d409ef.png?auto=format&fit=clip&q=50)
+
+This is an environment-level setting, but can be configured per organization via the _Roles_ tab under an organization in the WorkOS Dashboard.
+
+## Considerations
+
+Your customers will store role information in different forms, depending on their preferred provisioning workflow. WorkOS allows for flexibility in how you source role data. However, there are some considerations to keep in mind when using SSO-based connection groups for role assignment.
+
+### Drawbacks
+
+**Strictly** assigning roles during [JIT user provisioning](/sso/jit-provisioning) has a few caveats:
+
+- Your customer must explicitly map the SAML `groups` attribute in the SSO setup so that you can retrieve that attribute in the SSO profile.
+- SSO groups need to be manually defined.
+- Your app will receive updates to this user’s group data only once they sign-in with SSO again. This delay can allow unauthorized users to access resources using a stale role.
+
+### Directory group role assignment
+
+Directory Sync supports [group-based role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment) and avoids the pitfalls mentioned above. For organizations with a directory, this method of group-based role assignment is preferred.
+
+It’s recommended to use only one method of role assignment—either from a Directory or an SSO Connection—to avoid overlap.