@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/demo/punctuation.mdx

@@ -0,0 +1,37 @@
+---
+title: Punctionation
+description: This will be SEO description.
+originalPath: .tmp-workos-clone/packages/docs/content/demo/punctuation.mdx
+---
+
+The punctuation should use proper typographic symbols, like dashes and curly quotes via [SmartyPants](https://daringfireball.net/projects/smartypants/).
+
+## Apostrophe and smart quotes
+
+"It'll be great" they said. Here's a sentence. "Great", he said. They said it'll be great. "We'll do that" they said. "You'll do that" he said. _They_ can't do that.
+
+`don't replace the apostrophe here`.
+
+`"string"`
+
+```plaintext
+Don't replace the "apostrophe" and "quotes" here too.
+```
+
+## Dashes
+
+One - a hyphen. Two – an en-dash. Three—an em dash.
+
+All should be transformed into en-dashes.
+
+Code should not be transformed:
+
+```plaintext
+One - a hyphen. Two – an en-dash. Three—an em dash.
+```
+
+`One - a hyphen. Two – an en-dash. Three—an em dash.`
+
+## Ellipsis
+
+Counting...

package/.docs/organized/docs/demo/replacements.mdx

@@ -0,0 +1,26 @@
+---
+title: Code Block Replacements
+description: Test page for the code block replacements
+originalPath: .tmp-workos-clone/packages/docs/content/demo/replacements.mdx
+---
+
+```js
+'foo@foo-corp.com foo-corp.com foo@foo-corp.com';
+```
+
+```js
+'foo-corp.com';
+```
+
+```js
+'afoo-corp.com';
+```
+
+```js
+'foo-corp.com foo-corp.com';
+```
+
+```js
+const api_key = 'sk_example_123456789';
+const client_id = 'client_123456789';
+```

package/.docs/organized/docs/demo/table.mdx

@@ -0,0 +1,26 @@
+---
+title: Table
+description: Demo example of a table.
+originalPath: .tmp-workos-clone/packages/docs/content/demo/table.mdx
+---
+
+## Default table
+
+| First Header | Second Header |
+| ------------ | ------------- |
+| Content Cell | Content Cell  |
+| Content Cell | Content Cell  |
+
+## Formatting with `inline code blocks`, `links`, and `text styles`
+
+| Command      | Description                                                              |
+| ------------ | ------------------------------------------------------------------------ |
+| `git status` | List all _new or modified_ files                                         |
+| `git diff`   | Show [file](https://workos.com) differences that **haven’t been** staged |
+
+## Text alignment
+
+| Left-aligned | Center-aligned | Right-aligned |
+| ------------ | -------------: | ------------: |
+| git status   |     git status |    git status |
+| git diff     |       git diff |      git diff |

package/.docs/organized/docs/demo/tabs.mdx

@@ -0,0 +1,17 @@
+---
+title: Tabs
+description: Test page for the tabs component
+originalPath: .tmp-workos-clone/packages/docs/content/demo/tabs.mdx
+---
+
+- | Directory User
+
+  Whether to parse strikethrough with a single tilde (boolean, default: true).
+
+- | List Directory
+
+  Get the details of an existing Directory User.
+
+- | Get Directory Group
+
+  <CodeBlock title="Example Code" file="webhook-endpoint" />

package/.docs/organized/docs/directory-sync/_navigation.mdx

@@ -0,0 +1,28 @@
+---
+title: Directory Sync
+links:
+  - title: Getting Started
+    links:
+      - title: Fundamentals
+        url: /directory-sync
+      - title: Quick Start
+        url: /directory-sync/quick-start
+      - title: Example Apps
+        url: /directory-sync/example-apps
+  - title: Going Live
+    links:
+      - title: Handle Inactive Users
+        url: /directory-sync/handle-inactive-users
+      - title: Understanding Events
+        url: /directory-sync/understanding-events
+      - title: User Attributes
+        url: /directory-sync/attributes
+      - title: On-prem Deployment
+        url: /on-prem-deployment
+  - title: Mapping Roles
+    links:
+      - title: IdP Role Assignment
+        url: /directory-sync/identity-provider-role-assignment
+originalPath: .tmp-workos-clone/packages/docs/content/directory-sync/_navigation.mdx
+---
+

package/.docs/organized/docs/directory-sync/attributes.mdx

@@ -0,0 +1,209 @@
+---
+title: User Attributes
+description: Configure how attributes map from directory providers to Directory Users.
+originalPath: .tmp-workos-clone/packages/docs/content/directory-sync/attributes.mdx
+---
+
+## Introduction
+
+WorkOS can automatically find and normalize most common attributes from directory providers into the [Directory User](/reference/directory-sync/directory-user) object, which represents an enterprise user. More unique cases can be mapped by your customers admins.
+
+- ### Directory User object
+
+  Here is an example Directory User. The data stored varies per directory provider and may include attributes such as photo URLs, pay groups, supervisors, etc.
+
+  ```json language="json" title="Directory User"
+  {
+    "id": "directory_user_01E1X7B89OH8Z3SXFJR4H7RGX7",
+    "idp_id": "821991",
+    "first_name": "Jane",
+    "last_name": "Doe",
+    "email": "jane@example.com",
+    "state": "active",
+    "created_at": "2021-06-25T19:07:33.155Z",
+    "updated_at": "2021-06-25T19:07:33.155Z",
+    "object": "directory_user",
+    "directory_id": "directory_01E1X194NTJ3PXMAY79DYV0F0P",
+    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3PJNY",
+    "custom_attributes": {
+      "emails": [
+        {
+          "type": "work",
+          "value": "jane@example.com",
+          "primary": true
+        }
+      ],
+      "employee_type": "Full Time",
+      "employment_start_date": "2021-06-27T12:00:00.000Z",
+      "department_name": "Engineering",
+      "manager_email": "john@example.com",
+      "division_name": "Analytics",
+      "cost_center_name": "IT",
+      "job_title": "Software Engineer",
+      "addresses": [
+        {
+          "type": "work",
+          "street_address": "101 123rd Ave",
+          "locality": "Brooklyn",
+          "region": "New York",
+          "postal_code": "12345",
+          "country": "USA",
+          "raw_address": "101 123rd Ave, Brooklyn,  New York, 12345, USA",
+          "primary": true
+        },
+        {
+          "type": "home",
+          "street_address": "102 W 321st St",
+          "locality": "Brooklyn",
+          "region": "New York",
+          "postal_code": "54321",
+          "country": "USA",
+          "raw_address": "102 W 321st St, Brooklyn,  New York, 54321, USA",
+          "primary": false
+        }
+      ],
+      "username": "jane@example.com",
+      "my_new_key": "<custom-mapped value>"
+    },
+    "raw_attributes": {
+      "name": {
+        "givenName": "Jane",
+        "familyName": "Doe"
+      },
+      "active": true,
+      "emails": [
+        {
+          "type": "work",
+          "value": "jane@example.com",
+          "primary": true
+        }
+      ],
+      "groups": [],
+      "locale": "en_US",
+      "schemas": ["urn:directory:schemas:core:1.0"],
+      "password": "redacted",
+      "userName": "jane@example.com",
+      "externalId": "821991",
+      "displayName": "Jane Doe"
+    }
+  }
+  ```
+
+In this guide, we’ll explain how to map data from directory providers to the Directory Users.
+
+## 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 auto-mapped.
+
+**Custom attributes**
+: For unique cases, you can create custom attributes your customers can map when setting up a directory.
+
+## Standard attributes
+
+Every Directory User 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 Directory User payload.
+
+| Attribute    | Type and description                                                                                                     | Status   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------ | -------- |
+| `idp_id`     | The user’s unique identifier, assigned by the directory provider. Different directory providers use different ID formats | Required |
+| `first_name` | The user’s first name                                                                                                    | Optional |
+| `last_name`  | The user’s last name                                                                                                     | Optional |
+| `email`      | The user’s email                                                                                                         | Optional |
+| `state`      | The user’s state. May be `active`, or `inactive`                                                                         | Required |
+
+> `emails`, `job_title`, and `username` were previously considered standard attributes, but have been deprecated in favor of equivalent [auto-mapped custom attributes](/directory-sync/attributes/custom-attributes/predefined-attributes).
+
+---
+
+## 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 [Directory User](/reference/directory-sync/directory-user) objects and can be configured in the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+### Predefined attributes
+
+When enabled, the values will be mapped without additional setup. Not every directory provider has data for every field, so they are always optional if enabled. These fields are named and schematized by WorkOS – they cannot be renamed.
+
+| Attribute               | Type and description                                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `addresses`             | The user’s list of address objects (`street_address`, `locality`, `region`, `postal_code`, `country`, `primary`, `raw_address`) |
+| `cost_center_name`      | The user’s cost center name                                                                                                     |
+| `department_name`       | The user’s department name                                                                                                      |
+| `division_name`         | The user’s division name                                                                                                        |
+| `emails`                | The user’s list of email objects (`type`, `value`, `primary`)                                                                   |
+| `employee_type`         | The user’s employment type                                                                                                      |
+| `employment_start_date` | The user’s start date                                                                                                           |
+| `job_title`             | The user’s job title                                                                                                            |
+| `manager_email`         | The email address for the user’s manager                                                                                        |
+| `username`              | The user’s username                                                                                                             |
+
+#### 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)
+
+> Updates to these settings may take up to an hour to reflect in your Directory User API response. A [dsync.user.updated](/events/directory-sync) event is emitted for each Directory User changed by toggling auto-mapped attributes.
+
+### Support per directory provider
+
+The following support table outlines the attribute availability across directory providers.
+
+<DirectorySyncAttributeSupportTable />
+
+### Custom attributes
+
+Custom attributes can be utilized to enrich [Directory User](/reference/directory-sync/directory-user) objects 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 Directory Sync 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)
+
+#### Delete a custom attribute
+
+When a custom attribute is deleted, the attribute will be deleted from all [Directory User](/reference/directory-sync/directory-user) objects.
+
+> Updates to custom attributes may take up to an hour to reflect in your Directory User API response. A [dsync.user.updated](/events/directory-sync) event is emitted for each Directory User changed.
+
+#### Nested attributes
+
+Nested attributes are not currently supported. These admin-defined attributes must be defined as top-level flat keys.
+
+For instance, in the following example `top_level_attribute` can be mapped, but `top_level_with_nested.nested_attribute` cannot be mapped:
+
+```json language="json" title="Attributes Example"
+{
+  "top_level_attribute": "value",
+  "top_level_with_nested": {
+    "nested_attribute": "nested_value"
+  }
+}
+```
+
+> If you are interested in nested attributes support, please [contact support](mailto:support@workos.com).
+
+---
+
+## Raw attributes [**Deprecated**]
+
+These are unfiltered and unstructured attributes that are unique to each directory provider. These attributes are included as fields in the `raw_attributes` object that is included in the [Directory User](/reference/directory-sync/directory-user). The `raw_attributes` property will be phased out by July 22, 2025. [IdP role assignment](/directory-sync/identity-provider-role-assignment) or [custom attributes](/directory-sync/attributes/custom-attributes) should be used instead.
+
+---
+
+## Frequently asked questions
+
+### Are existing directories required to update the attribute mapping when new required custom attributes are added?
+
+No, when you add a new required custom attribute to your settings, this won’t be retroactively required for directories that have already been set up and configured. However, in the WorkOS dashboard, you will be able to navigate directly to the existing directory and fill in details for those attributes manually.
+
+### Can our customers add their own custom attributes outside of what is defined in the WorkOS dashboard?
+
+We do not currently support this functionality, as you have to define any custom attributes in the 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 [Directory User](/reference/directory-sync/directory-user) will result in a `null` value for the attribute. [dsync.user.updated](/events/directory-sync) events are not emitted when an attribute changes from `null` to `undefined` or vice versa.

package/.docs/organized/docs/directory-sync/example-apps.mdx

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

package/.docs/organized/docs/directory-sync/handle-inactive-users.mdx

@@ -0,0 +1,52 @@
+---
+title: Handle Inactive Users
+description: >-
+  Learn why inactive users are deleted from directories by default and how to
+  configure this behavior.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/directory-sync/handle-inactive-users.mdx
+---
+
+## Introduction
+
+Traditionally, user provisioning involves the ingestion of user information from various providers (either through SCIM or non-SCIM integrations). This process typically includes categorizing users into states such as `active`, or `inactive` as provided by the IdP data source.
+
+However, the challenge arises when businesses need to handle these `inactive` users differently based on their unique operational and security requirements. Some developers may prefer a security-first approach, automatically deleting these users to enhance data security, while others may opt to retain this information for reactivation processes or comprehensive directory management.
+
+---
+
+## Configuration
+
+To provide improved security and customizability, you can choose how `inactive` users are handled during the provisioning process. Here is an overview of the two options available:
+
+### Secure flow (default)
+
+By selecting this option, customers can opt for a security-focused workflow. Any user marked as `inactive` will be automatically deleted from the directory, resulting in cleaner and potentially more secure data. This approach reduces the data footprint and minimizes potential security risks associated with unused accounts.
+
+### Custom management flow
+
+Alternatively, customers can choose to maintain the existing flow, keeping the `inactive` users in the directory. This approach supports reactivation processes and ensures a comprehensive view of the directory, allowing for easier reintegration of users when needed.
+
+> Contact [customer support](mailto:support@workos.com) to enable custom management flow for your environment.
+
+![A breakdown of the different events for each configuration path on handling inactive users.](https://images.workoscdn.com/images/2304739c-17e9-4521-96d2-81fa3fa83110.png?auto=format&fit=clip&q=80)
+
+## Weighing the tradeoffs
+
+Both options offer distinct advantages, and the right choice depends on your organization's unique needs and security posture:
+
+### Security vs. flexibility
+
+The automatic deletion option prioritizes data security by minimizing the data footprint, while the customized management option provides flexibility for reactivation flows and comprehensive directory oversight.
+
+### Compliance and regulations
+
+Depending on industry regulations and compliance requirements, one option may align better with your organization's obligations.
+
+### Operational efficiency
+
+Consider how each option impacts operational efficiency using WorkOS to handle a set of the computation for you.
+
+### Reactivation
+
+If a user is temporarily removed, does the same user information need to be retained when they return? A new directory user will be created by default on return, whereas using the `inactive` user will retain the same information on reactivation.

package/.docs/organized/docs/directory-sync/identity-provider-role-assignment.mdx

@@ -0,0 +1,134 @@
+---
+title: Identity Provider Role Assignment
+description: >-
+  Learn how to map role data from identity providers to roles in your app with
+  Directory Sync.
+showNextPage: true
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/directory-sync/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 Directory Sync [users](/directory-sync/api-overview/directory-user) through their group memberships. These role assignments 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 directory user. This 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
+
+If a user is provisioned from multiple groups with conflicting roles, the role with the highest priority will be assigned.
+
+### Delete roles
+
+When a role is deleted, all users with that role, will be granted the default role. Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating all directory users.
+
+> To migrate from one default role to another, set the new default role and delete the old one. All directory users will then be reassigned to the new default role.
+
+## Directory 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. This can be defined within the WorkOS dashboard or Admin Portal for your application to receive automatic role updates.
+
+> Only supported in directories using SCIM-based or Google Workspace providers.
+
+### Sample scenario
+
+Consider the fictional SaaS company _HireOS_. _HireOS_ has integrated Directory Sync and supports group-based role assignment. For example, a _HireOS_ customer would like to assign their engineering team to it. The customer’s IT admin would take the following steps:
+
+1. Create a group “Engineering” using their identity provider.
+2. Push the group to _HireOS_ via the identity provider. This is configured in the identity provider admin console.
+
+The developer on the WorkOS dashboard can then assign users of that group to the role "Developer".
+
+1. Navigate to the directory page on the WorkOS dashboard.
+
+![The directory page on the WorkOS dashboard](https://images.workoscdn.com/images/88d4701b-7e6d-4655-ad74-48bc7c14959f.png?auto=format&fit=clip&q=50)
+
+2. Create an assignment for “Engineering" to the "Developer" role.
+
+![The role assignment dialog on the WorkOS dashboard](https://images.workoscdn.com/images/bdd4cc91-11cb-49b1-858b-f2509ce3675e.png?auto=format&fit=clip&q=50)
+
+From this point on, all new users added to “Engineering" will be given "Developer” role from the WorkOS API. The role will be in the [directory user response](/reference/directory-sync/directory-user).
+
+![Screenshot of directory user page](https://images.workoscdn.com/images/18f584f6-d758-4f11-bfc8-e93c16452580.png?auto=format&fit=clip&q=50)
+
+### Role assignment in Admin Portal
+
+Once [roles](/directory-sync/identity-provider-role-assignment/configure-roles) are configured for your application, enable directory group role assignment in [Admin Portal](/admin-portal) to allow IT admins to assign roles to groups during directory setup.
+
+![Enable directory group role assignment dashboard setting](https://images.workoscdn.com/images/157af155-1cd5-4714-9a4e-f56dd0005e36.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. If your application is integrated with Directory Sync, it is recommended to use directory group role assignment as the environment default.
+
+![Screenshot of admin portal with role assignment step](https://images.workoscdn.com/images/74d09b62-b2b2-4aba-9803-3ec6305897e0.png?auto=format&fit=clip&q=50)
+
+If enabled, all Admin Portal sessions for SCIM-based or Google Workspace directories will have the ability to see and assign roles to identity provider groups.
+
+## Other forms of role assignment
+
+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, though these formats are not automated today and not available on the role property on the [directory user response](/reference/directory-sync/directory-user). You can fetch role data via two distinct mechanisms:
+
+- A custom-mapped role attribute from the directory user profile.
+- A groups attribute in the SSO user profile.
+
+The type of mechanism needed will depend on the level of support for roles in your app, your app’s architecture, and your customer’s workflows:
+
+| Approach                        | Your app                                               | Your customer                                                      |
+| ------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------ |
+| SSO group role assignment       | Receives role data each time a user logs in            | Uses identity provider groups to assign roles in your app          |
+| Attribute-based role assignment | Sets roles based on a per-user custom-mapped attribute | Assigns roles using attributes on users in their identity provider |
+
+### SSO group role assignment
+
+[SSO group role assignment](/sso/identity-provider-role-assignment/sso-group-role-assignment) involves mapping identity provider (IdP) groups to roles within your application during [Single Sign-On](/sso) and [JIT Provisioning](/sso/jit-provisioning). In this method, SSO groups corresponding to IdP groups are defined in the WorkOS Dashboard, and roles are assigned based on these group memberships.
+
+The user’s role is then included in the [SSO profile](/reference/sso/profile) returned from WorkOS. [Read more](/sso/identity-provider-role-assignment/considerations/drawbacks) on this approach, including [drawbacks](/sso/identity-provider-role-assignment/considerations/drawbacks) to consider.
+
+### Attribute-based role
+
+You can use [custom-mapped attributes](/directory-sync/attributes/custom-attributes/custom-attributes) if your customers do not use groups to establish and manage user roles.
+
+You can create a custom-mapped attribute role (e.g., `myRole`) in the [WorkOS Dashboard](https://dashboard.workos.com/) under Configuration → Directory Sync. You can set the status of a role attribute to “Required” or “Optional”.
+
+```json language="json" title="Directory user with a custom-mapped attribute"
+{
+  "id": "directory_user_01E1X7B89OH8Z3SXFJR4H7RGX7",
+  "idp_id": "821991",
+  "first_name": "Jane",
+  "last_name": "Doe",
+  "email": "jane@example.com",
+  "state": "active",
+  "created_at": "2021-06-25T19:07:33.155Z",
+  "updated_at": "2021-06-25T19:07:33.155Z",
+  "object": "directory_user",
+  "directory_id": "directory_01E1X194NTJ3PXMAY79DYV0F0P",
+  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3PJNY",
+  "custom_attributes": {
+    "myRole": "admin"
+  },
+  "raw_attributes": {}
+}
+```
+
+The newly created attribute will appear as a field in the [Admin Portal](/admin-portal). When setting up Directory Sync with their identity provider in Admin Portal, your customers can map this role field to a field in their identity provider. You’ll have to communicate with your customer what value(s) you expect in the custom-mapped attribute.
+
+An example being that `myRole` should be one of `"admin"`, `"viewer"`, or `"editor"`. This allows your app to parse the `myRole` field value correctly.
+
+## Common edge cases
+
+### A user is part of multiple groups
+
+Having a user who belongs to multiple groups is a common scenario. 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](/directory-sync/identity-provider-role-assignment/configure-roles/priority-order).
+
+### Role assignment availability on Directory Sync
+
+Identity provider role assignment through groups is only available through SCIM compliant and Google Workspace directories.