@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/mfa/ux/sign-in.mdx

@@ -0,0 +1,30 @@
+---
+title: Sign-In UX
+description: User experience considerations for MFA sign-in.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/mfa/ux/sign-in.mdx
+---
+
+## Introduction
+
+Once a user has setup two-factor authentication, their sign-in process will be different from the standard sign-in flow. This guide will walk you through the adjustments you need to make to support this in your application.
+
+## Prompt user to verify the extra factor
+
+At the very least, assuming the user has enrolled in one method (e.g. SMS/Text message) you should present the user with a new screen for the extra verification step after they have entered their username and password.
+
+<MfaSignInDemoSingleMethod />
+
+## When the user has enrolled in multiple methods
+
+If the user has enrolled in multiple methods, consider including both methods in the verification step after they have entered their username and password. Following what we discussed in the [enrollment guide](mfa/ux/enrollment/let-users-choose-their-primary-method), consider presenting the user with their primary method first as well as letting them switch.
+
+<MfaSignInDemoMultipleMethods />
+
+---
+
+## Full interactive UI example
+
+The following interactive example shows a full UI for signing-in using MFA encompassing all the considerations mentioned above.
+
+<MfaSignInDemoFull />

package/.docs/organized/docs/migrate/_navigation.mdx

@@ -0,0 +1,6 @@
+---
+title: Migrations
+links: []
+originalPath: .tmp-workos-clone/packages/docs/content/migrate/_navigation.mdx
+---
+

package/.docs/organized/docs/migrate/auth0.mdx

@@ -0,0 +1,98 @@
+---
+title: Migrate from Auth0
+description: Learn how to migrate users and organizations from Auth0.
+icon: auth0
+breadcrumb:
+  title: Migrations
+  url: /migrate
+originalPath: .tmp-workos-clone/packages/docs/content/migrate/auth0.mdx
+---
+
+## Introduction
+
+The WorkOS User Management API allows you to migrate your existing user data from a variety of existing sources. In this guide, we will walk through the steps to export, and then import your users from Auth0.
+
+## (1) Exporting Auth0 user data
+
+Auth0 allows their customers to export user data using several tools, which are outlined in [Auth0’s export documentation](https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions/export-data). A combination of exports may be necessary to retrieve all of the desired user information, including passwords.
+
+The first tool is [Auth0’s “Bulk User Export” jobs](https://auth0.com/docs/manage-users/user-migration/bulk-user-exports). These export jobs can be created programmatically using the [Auth0 Management API](https://auth0.com/docs/api/management/v2/jobs/post-users-exports), or through the official [Auth0 "User Import / Export Extension"](https://auth0.com/docs/customize/extensions/user-import-export-extension).
+
+In both cases, an Auth0 customer can request which fields they’d like exported for each user, with the final output of the process being a newline-delimited JSON
+file.
+
+### Exporting passwords
+
+If your Auth0 users currently sign-in using password-based authentication, and you’d like to import those passwords into WorkOS, then you will need to [contact Auth0 support](https://auth0.com/docs/troubleshoot/customer-support).
+
+After opening a ticket with Auth0, it can take up to a week or more for your request to be processed. At the end you’ll be given another newline-delimited JSON file, containing a subset of user data such as ID, but more importantly the password hash.
+
+> Auth0 does not make the plaintext passwords available for export.
+
+---
+
+## (2) Importing Users into WorkOS
+
+Once you’ve obtained the necessary export files, you have two options for importing your user data into WorkOS.
+
+### (A) Using the WorkOS import tool
+
+WorkOS has a public [GitHub repository](https://github.com/workos/migrate-auth0-users) containing code that can be run to import users into WorkOS using the data retrieved in the previous step.
+
+If you’d rather write your own code, the same process can be completed using the public WorkOS APIs, as described below.
+
+### (B) Using WorkOS APIs
+
+With the data from Auth0’s “Bulk User Export” job, you can use the WorkOS [Create User API](/reference/user-management/user/create) to import each of the users. Using the default fields from the [Auth0 export](https://auth0.com/docs/customize/extensions/user-import-export-extension#export-users), use the following mapping from Auth0 to parameters in your WorkOS Create User API calls:
+
+| Auth0          |     | WorkOS API       |
+| -------------- | --- | ---------------- |
+| Email          | →   | `email`          |
+| Email Verified | →   | `email_verified` |
+| Given Name     | →   | `first_name`     |
+| Family Name    | →   | `last_name`      |
+
+### Importing passwords
+
+If you also exported passwords from Auth0, you can import them during the [user creation](/reference/user-management/user/create) process, or later using the WorkOS [Update User API](/reference/user-management/user/update).
+
+Auth0 uses the `bcrypt` password hashing algorithm, which is supported by WorkOS. Make sure to pass the following parameters to the WorkOS API:
+
+- The `password_hash_type` set to `'bcrypt'`
+- The `password_hash` set to the `passwordHash` field from your Auth0 export
+
+### Migrating social auth users
+
+If you have users who previously signed in through Auth0 using social auth providers, such as [Google](/integrations/google-oauth) or [Microsoft](/integrations/google-oauth), those users can continue to sign in with those providers after you’ve migrated to WorkOS.
+
+Check out our [integrations](/integrations) page for guidance on configuring the relevant provider’s client credentials in WorkOS.
+
+After your provider is configured in WorkOS, users can sign in with their provider credentials and will be automatically linked to a WorkOS user. WorkOS uses the **email address** from the social auth provider to determine this match.
+
+> Some users may need to verify their email address through WorkOS if email verification is enabled in your WorkOS environment’s authentication settings.
+
+Email verification behavior varies depending on whether the provider is known to verify email addresses. For example, users signing in using Google OAuth and a `gmail.com` email domain will not need to perform the extra verification step.
+
+---
+
+## Organizations
+
+Auth0 has a concept of [“Organizations”](https://auth0.com/docs/manage-users/organizations) which are analogous to [WorkOS Organizations](/reference/organization), in that both represent a B2B customer.
+
+### Creating Organizations
+
+If you’d like to export your Auth0 organizations, you can use the [Auth0 Management API](https://auth0.com/docs/api/management/v2/organizations/get-organizations) to programmatically paginate through each Organization. You can then call the WorkOS [Create Organization API](/reference/organization/create) to create matching Organizations in WorkOS.
+
+### Adding user memberships
+
+You can export Auth0 organization memberships using Auth0’s “Bulk User Export” as described in the [Exporting Auth0 user data](/migrate/auth0/1-exporting-auth0-user-data) step, and then use the WorkOS [Organization Membership API](/reference/user-management/organization-membership/create) to add each user to their respective organization.
+
+## Multi-Factor Auth
+
+There are some differences between the Multi-Factor Auth (MFA) strategies offered by Auth0 and WorkOS.
+
+Auth0 supports SMS-based second factors, however WorkOS does not due to known security issues with SMS. Users who have SMS-based second factors will need to switch to using email-based Magic Auth, or re-enroll in MFA using a TOTP-based authenticator instead.
+
+## Wrapping-up
+
+With your users now imported, you can now start using WorkOS to manage your Auth0 users. If you haven’t, take a look at our [Quick Start guide](/user-management) to learn how to integrate WorkOS User Management into your application.

package/.docs/organized/docs/migrate/aws-cognito.mdx

@@ -0,0 +1,115 @@
+---
+title: Migrate from AWS Cognito
+description: "Learn how to migrate users to\_WorkOS from AWS Cognito."
+icon: aws
+breadcrumb:
+  title: Migrations
+  url: /migrate
+originalPath: .tmp-workos-clone/packages/docs/content/migrate/aws-cognito.mdx
+---
+
+## Introduction
+
+The WorkOS User Management API allows you to migrate your existing user data from a variety of existing sources. In this guide, we’ll walk through the steps to export, and then import your users from AWS Cognito.
+
+> AWS Cognito does not offer exports of user password hashes or MFA keys. This means that your imported users will need to reset their passwords and reconfigure any required MFA.
+
+## (1) Exporting Cognito user data
+
+User data in an AWS Cognito User Pool can be exported using the AWS CLI’s [list-users command](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/list-users.html).
+
+To retrieve the first page of results, use the command:
+
+```bash title="List users using the Cognito CLI"
+aws cognito-idp list-users --user-pool-id <your-user-pool> --region <region>
+```
+
+Add the `--pagination-token <next-token>` argument to paginate subsequent requests:
+
+```bash title="export-aws-cognito-users.sh"
+#!/bin/bash
+user_pool_id="<your-user-pool-id>"
+region="<your-region>"
+output_dir="cognito_exports"
+file_index=1
+
+mkdir -p "$output_dir"
+
+export_users() {
+  aws cognito-idp list-users --user-pool-id "$user_pool_id" --region "$region" $1 | \
+  jq '.' > "$output_dir/users_$2.json"
+}
+
+next_token=""
+while true; do
+  next_token=$(export_users "${next_token:+--pagination-token $next_token}" "$file_index" | jq -r '.PaginationToken // empty')
+  [ -z "$next_token" ] && break
+  ((file_index++))
+done
+echo "Export complete."
+```
+
+## (2) Importing users into WorkOS
+
+After obtaining your user data from Cognito, it’s time to import them into WorkOS, mapping attributes from the AWS Cognito User format to WorkOS API parameters.
+
+```json title="Example AWS Cognito list-users response object"
+{
+  "Users": [
+    {
+      "Username": "22704aa3-fc10-479a-97eb-2af5806bd327",
+      "Enabled": true,
+      "UserStatus": "FORCE_CHANGE_PASSWORD",
+      "UserCreateDate": 1548089817.683,
+      "UserLastModifiedDate": 1548089817.683,
+      "Attributes": [
+        {
+          "Name": "sub",
+          "Value": "22704aa3-fc10-479a-97eb-2af5806bd327"
+        },
+        {
+          "Name": "family_name",
+          "Value": "Mouse"
+        },
+        {
+          "Name": "given_name",
+          "Value": "Mickey"
+        },
+        {
+          "Name": "email_verified",
+          "Value": "true"
+        },
+        {
+          "Name": "email",
+          "Value": "mary@example.com"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Using the WorkOS [Create User API](/reference/user-management/user/create), you can create a corresponding record in WorkOS for each exported user. Use the following mapping from the AWS Cognito object to parameters in your WorkOS Create User API calls:
+
+| AWS Cognito     |     | WorkOS API       |
+| --------------- | --- | ---------------- |
+| `email`         | →   | `email`          |
+| `emailVerified` | →   | `email_verified` |
+| `given_name`    | →   | `first_name`     |
+| `family_name`   | →   | `last_name`      |
+
+> Migrated users **must reset their passwords** before they can sign in.
+
+### Triggering password resets
+
+It’s important to have a strategy for triggering password resets after importing your users into WorkOS. You may want to ask users to reset their password the next time they attempt to sign in, or proactively send them password reset emails.
+
+In either case, you can trigger the password reset flow by using the WorkOS [Send Password Reset Email API](/reference/user-management/password-reset/create).
+
+## Other authentication methods
+
+In addition to migrating username and password users to WorkOS, you can migrate users who authenticate using third-party identity providers, such as Google, without re-obtaining access.
+
+Ensure you use the same credentials (i.e. Client ID and Client Secret) in WorkOS as those used for your connection in AWS Cognito.
+
+For OAuth providers, you will need to add WorkOS as an additional Redirect URI. See the [Google OAuth integration guide](/integrations/google-oauth/customize-google-oauth-domain/3-add-new-redirect-uri-to-google) as an example of what this process looks like.

package/.docs/organized/docs/migrate/clerk.mdx

@@ -0,0 +1,106 @@
+---
+title: Migrate from Clerk
+description: Learn how to migrate users and organizations from Clerk.
+icon: clerk
+breadcrumb:
+  title: Migrations
+  url: /migrate
+originalPath: .tmp-workos-clone/packages/docs/content/migrate/clerk.mdx
+---
+
+## Introduction
+
+The WorkOS User Management API allows you to migrate your existing user data from a variety of existing sources. In this guide, we will walk through the steps to export, and then import your users from Clerk.
+
+---
+
+## (1) Export Clerk user data
+
+Clerk allows for exporting user data [directly from their API](https://clerk.com/docs/deployments/exporting-users) using their Backend SDK.
+
+### Export passwords
+
+If your Clerk users currently sign in using password-based authentication, and you'd like to import those passwords into WorkOS, then you'll need to [contact Clerk support](https://clerk.com/support).
+
+After opening a ticket with Clerk, it can take up to a week or more for your request to be processed. At the end you’ll be given a JSON file that includes user data and hashed passwords.
+
+> Clerk does not make the plaintext passwords available for export.
+
+---
+
+## (2) Import users into WorkOS
+
+Once you’ve obtained the necessary export files, you have two options for importing your user data into WorkOS.
+
+### (A) Using the WorkOS import tool
+
+WorkOS has a public [GitHub repository](https://github.com/workos/migrate-clerk-users) containing code that can be run to import users into WorkOS using the data retrieved from Clerk support in the previous step.
+
+If you’d rather write your own code, or if you chose to not export data via Clerk support, the same process can be completed using the public WorkOS APIs, as described below.
+
+### (B) Using WorkOS APIs
+
+Using the data either from the Clerk API or from a JSON file received from their support team, you can use the WorkOS API to [create users](/reference/user-management/user/create) during the import. Keep in mind that user creation is rate-limited. You can view the docs on the [rate limits](/reference/rate-limits) for more information.
+
+Using the default fields from the [Clerk export](https://clerk.com/docs/deployments/exporting-users), use the following mapping from Clerk to parameters in your WorkOS Create User API calls:
+
+| Clerk             |     | WorkOS API   |
+| ----------------- | --- | ------------ |
+| `email_addresses` | →   | `email`      |
+| `first_name`      | →   | `first_name` |
+| `last_name`       | →   | `last_name`  |
+
+### Handle users with multiple email addresses
+
+In the case of a user with multiple email addresses, Clerk separates them with a pipe symbol:
+
+```json
+"email_addresses": "john@example.com|john.doe@example.com",
+```
+
+Unfortunately there's no way to know which email is the primary one from the export alone. Clerk does expose this information by retrieving the [User object from their API](https://clerk.com/docs/references/javascript/user/user#properties).
+
+### Import passwords
+
+If you also exported passwords from Clerk, you can import them during the [user creation](/reference/user-management/user/create) process, or later using the WorkOS [Update User API](/reference/user-management/user/update).
+
+Clerk uses the `bcrypt` password hashing algorithm, which is supported by WorkOS. Make sure to pass the following parameters to the WorkOS API:
+
+- The `password_hash_type` set to `'bcrypt'`
+- The `password_hash` set to the `password_digest` field from your Clerk export
+
+### Migrate social auth users
+
+If you have users who previously signed in through Clerk using social auth providers, such as [Google](/integrations/google-oauth) or [Microsoft](/integrations/google-oauth), those users can continue to sign in with those providers after you’ve migrated to WorkOS.
+
+Check out our [integrations](/integrations) page for guidance on configuring the relevant provider’s client credentials in WorkOS.
+
+After your provider is configured in WorkOS, users can sign in with their provider credentials and will be automatically linked to a WorkOS user. WorkOS uses the **email address** from the social auth provider to determine this match.
+
+---
+
+### (3) Create organizations
+
+Clerk’s [organizations](https://clerk.com/docs/organizations/overview) are analogous to WorkOS [organizations](/reference/organization) – both represent a B2B customer.
+
+### Creating Organizations
+
+If you’d like to export your Clerk organizations, you can use the [Clerk Backend SDK](https://clerk.com/docs/references/backend/organization/get-organization-list) to programmatically paginate through each organization. You can then use the WorkOS API to [create matching organizations](/reference/organization/create).
+
+### Adding user memberships
+
+You can export Clerk organization memberships using Clerk’s [Backend SDK](https://clerk.com/docs/references/backend/organization/get-organization-membership-list), and then use the WorkOS [Organization Membership API](/reference/user-management/organization-membership/create) to add each user to their respective organization.
+
+---
+
+### (4) Multi-Factor Auth
+
+There are some differences between the MFA strategies offered by Clerk and WorkOS.
+
+Clerk supports SMS-based second factors, however WorkOS does not due to known security issues with SMS. Users who have SMS-based second factors will need to switch to using email-based Magic Auth, or re-enroll in MFA using a TOTP-based authenticator instead. See the [MFA guide](/user-management/mfa) for more information on enrolling users.
+
+---
+
+## Next steps
+
+After the import, you can now start using WorkOS to manage your users. If you haven’t, take a look at the [Quick Start guide](/user-management) to learn how to integrate WorkOS User Management into your application.

package/.docs/organized/docs/migrate/firebase.mdx

@@ -0,0 +1,80 @@
+---
+title: Migrate from Firebase
+description: Learn how to migrate users to WorkOS from Firebase.
+icon: firebase
+breadcrumb:
+  title: Migrations
+  url: /migrate
+originalPath: .tmp-workos-clone/packages/docs/content/migrate/firebase.mdx
+---
+
+## Introduction
+
+The WorkOS User Management API allows you to migrate your existing user data from a variety of existing sources. In this guide, we’ll walk through the steps to export your users from Firebase, and then import them into WorkOS.
+
+## (1) Exporting Firebase user data
+
+Firebase customers can export their user data using either the [Firebase CLI](https://firebase.google.com/docs/cli/auth#auth-export) or the [Firebase API](https://firebase.google.com/docs/reference). In this guide we’ll be using the Firebase CLI, use the following command to retrieve a dump of all users in JSON or CSV format.
+
+```bash title="Exporting users with the Firebase CLI"
+firebase auth:export --project=<your_firebase_project_id> --format=json users.json
+```
+
+## (2) Importing users into WorkOS
+
+After obtaining your user data from Firebase, it’s time to import it into WorkOS, mapping attributes from the [Firebase User format](https://firebase.google.com/docs/cli/auth#JSON) to WorkOS API parameters.
+
+Using the WorkOS [Create User API](/reference/user-management/user/create), you can create a corresponding record in WorkOS for each exported user. Use the following mapping from the Firebase format to parameters in your WorkOS Create User API calls:
+
+| Firebase        |     | WorkOS API       |
+| --------------- | --- | ---------------- |
+| `email`         | →   | `email`          |
+| `emailVerified` | →   | `email_verified` |
+| `displayName`   | →   | `first_name`     |
+| `displayName`   | →   | `last_name`      |
+
+### Importing passwords
+
+If your users sign in to your Firebase application using passwords, you can choose to also import those password hashes. Firebase uses a [forked version of `scrypt`](https://firebaseopensource.com/projects/firebase/scrypt/) which can be directly imported during the [user creation](/reference/user-management/user/create) process into WorkOS, or later using the [Update User API](/reference/user-management/user/update).
+
+First, retrieve your Firebase project's password hash parameters from the Firebase console following the [export documentation](https://firebase.google.com/docs/cli/auth#password_hash_parameters). These parameters are the `base64_signer_key`, `base64_salt_separator`, `rounds`, and `mem_cost`.
+
+Next, retrieve the password salts and hashes for each of your individual Firebase users by running the [Firebase CLI `auth:export` command](https://firebase.google.com/docs/cli/auth#auth-export). Your Firebase users that have a password set will have a `passwordHash` and `salt` field present which will be imported into WorkOS.
+
+Finally, you will need to format these parameters into a [PHC-compatible](https://github.com/P-H-C/phc-string-format/blob/5f1e4ec633845d43776849f503f8ce8314b5290c/phc-sf-spec.md) password hash following this Firebase to PHC hash parameter mapping:
+
+| Firebase value          |     | PHC hash parameter |
+| ----------------------- | --- | ------------------ |
+| `base64_signer_key`     | →   | `sk`               |
+| `base64_salt_separator` | →   | `ss`               |
+| `rounds`                | →   | `r`                |
+| `mem_cost`              | →   | `m`                |
+
+The hash, salt, along with `sk` and `ss` parameters, should be [B64 encoded](https://github.com/P-H-C/phc-string-format/blob/5f1e4ec633845d43776849f503f8ce8314b5290c/phc-sf-spec.md#b64), which means trimming the `=` characters that represent base64 padding. Using a PHC-formatting library, like [`@phc/format`](https://www.npmjs.com/package/@phc/format) for Node, should handle this for you.
+
+<CodeBlock
+  title="Import Firebase password hash"
+  file="import-firebase-password-hash"
+/>
+
+## Other authentication methods
+
+Firebase authentication methods vary depending on your specific usage, and corresponding connections can be easily configured in WorkOS. This allows users to continue signing in with the same authentication methods, matching the previous sign in experience.
+
+### Social Auth Providers
+
+If your users “Sign in with Google” or similar, you can configure WorkOS to continue using those sign in methods. Migrating these connections involves providing the same client credentials (i.e. Client ID and Client Secret) to WorkOS as configured in Firebase.
+
+For more details on supported connections, see the provider-specific integration guides, such as for [Microsoft](/integrations/microsoft-oauth) and [Google](/integrations/google-oauth).
+
+Reach out to [support@workos.com](mailto:support@workos.com) if there are additional Social Auth providers you would like to see supported.
+
+### Email Link
+
+If your users sign in using [Email Link](https://firebase.google.com/docs/auth/web/email-link-auth), sometimes called “passwordless”, you can achieve the same experience by adding WorkOS [Magic Auth](/reference/user-management/magic-auth) to your application.
+
+### OIDC and SAML
+
+Enterprise authentication often uses standard protocols such as [OpenID Connect (OIDC)](https://firebase.google.com/docs/auth/web/openid-connect) or [SAML](https://firebase.google.com/docs/auth/web/saml) between your service and identity provider.
+
+The same identity providers can be configured in WorkOS, preserving the sign in process familiar to your users. For specific instructions, see the guides on setting up [OIDC](/integrations/oidc) and [SAML](/integrations/saml) connections with WorkOS.

package/.docs/organized/docs/migrate/other-services.mdx

@@ -0,0 +1,179 @@
+---
+title: Migrate from other services
+description: Learn how to export and import users from your own data store.
+breadcrumb:
+  title: Migrations
+  url: /migrate
+originalPath: .tmp-workos-clone/packages/docs/content/migrate/other-services.mdx
+---
+
+## Introduction
+
+The WorkOS User Management API allows you to migrate your existing user data from a variety of sources. In this guide, we’ll walk through the steps to export, and then import users from your own data store.
+
+## (1) Exporting data
+
+While moving authentication related metadata to WorkOS, most applications will continue to store certain user information in their data store. This common subset of data will usually be the following:
+
+| Field               | Description                                                                                                                    | Status   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| Email               | The user’s email address. Used for various authentication and verification purposes.                                           | Required |
+| First Name          | The user’s first, or given name.                                                                                               | Optional |
+| Last Name           | The user’s last, or family name.                                                                                               | Optional |
+| Verification Status | The user’s email verification status if they have gone through a verification flow. Assumed as “not verified” unless supplied. | Optional |
+| Password            | The user’s password hash, if they use password-based authentication.                                                           | Optional |
+
+While preparing the migration, you’ll want to ensure this information is programmatically available for use in the import step, this can mean:
+
+- Exporting the relevant data to a file such as JSON or CSV.
+- Allowing the data to be queried from the data store directly.
+
+After the data is accessible, we can configure the import.
+
+---
+
+## (2) Importing Users into WorkOS
+
+Now that the User data is available, we can import it into WorkOS.
+
+### Creating users
+
+For each of your users, you can call the WorkOS [Create User API](/reference/user-management/user/create). This will create a matching [User object](/reference/user-management/user) within WorkOS.
+
+A successful response will include a new WorkOS user ID, most apps will want to persist this WorkOS user ID alongside the application-local user object.
+
+```json
+{
+  "object": "user",
+  /* highlight-start */
+  "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
+  /* highlight-end */
+  "email": "marcelina.davis@gmail.com",
+  "firstName": "Marcelina",
+  "lastName": "Davis",
+  "emailVerified": true,
+  "createdAt": "2021-06-25T19:07:33.155Z",
+  "updatedAt": "2021-06-25T19:07:33.155Z"
+}
+```
+
+> **Email addresses are unique** to each WorkOS environment. If you have a subset of users already in WorkOS, you may need to handle constraint violation errors.
+
+There are now several options on how to proceed, depending on your application’s needs:
+
+### Importing passwords
+
+If your users currently use password-based authentication, you can import existing password hashes during the [users creation](/reference/user-management/user/create) process, or later using the WorkOS [Update User API](/reference/user-management/user/update).
+
+WorkOS currently supports the following password hashing algorithms:
+
+- `bcrypt`
+- `scrypt`
+- `firebase-scrypt`
+- `ssha`
+- `pbkdf2`
+
+For `scrypt` and `pbkdf2` passwords, use the PHC string format.
+The hash and salt should be B64 encoded: trim the `=` characters that represent Base64 padding. Using a PHC-formatting library, like
+Node's [`@phc/format`](https://www.npmjs.com/package/@phc/format), should handle this for you.
+
+The following table shows how to map the `scrypt` and `pbkdf2` parameters to the PHC parameters.
+
+#### scrypt
+
+| `Scrypt` value    |     | PHC hash parameter |
+| ----------------- | --- | ------------------ |
+| `key length`      | →   | `kl`               |
+| `cost`            | →   | `n`                |
+| `rounds`          | →   | `r`                |
+| `parallelization` | →   | `p`                |
+
+A valid `scrypt` PHC formatted string looks like this:
+
+```txt
+$scrypt$v=1$n=16384,r=8,p=1,kl=64$Swhqd4iUYTtWfbCYIPeuMw$q7pfdBQMJujd5FX/qX+ozM2O6aNqP+mo1ZnHGH15XM2vlhroQfPA037UpbdfpH4H66OrSPjsUhfkAMuNoBiQvw
+```
+
+#### pbkdf2
+
+| `pbkdf2` value |     | PHC hash parameter |
+| -------------- | --- | ------------------ |
+| `digest`       | →   | `d`                |
+| `iterations`   | →   | `i`                |
+
+For `pbkdf2` allowed values for digest are `sha256` or `sha512`. The value for iterations is dependent on digest. For `sha256` there is a minimum of 600,000 iterations and a max of 1,000,000. For `sha512` there is a minimum of 210,000 and a max of 1,000,000.
+
+A valid `pbkdf2` PHC formatted string looks like this:
+
+```txt
+$pbkdf2$i=600000,d=sha256$T2ptRFh6MXhDQVh2SWZuUGdpQXBUTg$xXiyTisD7390NijyCv5ICMhFW4eDuMlzypRoLGLyIvA
+```
+
+For `firebase-scrypt` passwords, refer to the [Firebase Migration guide](/migrate/firebase) for an example of how to format the `password_hash`.
+
+For `ssha` passwords, use the following algorithm:
+
+1. Generate a `salt`: random bytes
+2. Hash the user’s password and the `salt` using the SHA1 algorithm
+3. Base64 encode the hash followed by the salt
+4. Prepend the string with `{SSHA}`
+
+A high-level representation is: `{SSHA}base64(sha1(password + salt) + salt)`.
+
+Once imported, users can continue to sign-in with their existing password, **without** having to go through a password reset flow.
+
+### Triggering password resets
+
+If you are unable to export passwords from your existing data store, whether for security reasons or other limitations, you can programmatically trigger a password reset flow using the WorkOS [Password Reset API](/reference/user-management/password-reset).
+
+This process can be initiated at any time, and doesn’t need to happen during the user import process.
+
+Some applications may want to remove password-based authentication when switching to WorkOS, in favor of another method like Magic Auth. If this is the case for your application, you can skip dealing with passwords entirely.
+
+### Migrating social auth users
+
+If you have users who previously signed in using social auth providers, such as [Google](/integrations/google-oauth) or [Microsoft](/integrations/google-oauth), those users can continue to sign in with those providers after you’ve migrated to WorkOS.
+
+Check out our [integrations](/integrations) page for guidance on configuring the relevant provider’s client credentials in WorkOS.
+
+After your provider is configured in WorkOS, users can sign in with their provider credentials and will be automatically linked to a WorkOS user. WorkOS uses the **email address** from the social auth provider to determine this match.
+
+> Some users may need to verify their email address through WorkOS if email verification is enabled in your WorkOS environment’s authentication settings.
+
+Email verification behavior varies depending on whether the provider is known to verify email addresses. For example, users signing in using Google OAuth and a `gmail.com` email domain will not need to perform the extra verification step.
+
+---
+
+## (3) Handling interim new users
+
+Many applications allow users to sign up at any time. If your app offers this feature, then you should consider the timing of your migration. If any users sign up after you’ve completed importing users into WorkOS, but before you’ve switched to WorkOS for authentication, then those users will have been omitted from the migration process.
+
+There are two main strategies to handle this:
+
+### (A) Disable signups during migration
+
+The simplest solution is to schedule an appropriate time for the migration and disable signup while in progress. This may be done using temporary code added to your application and controlled by a feature flagging system.
+
+After the migration is complete, your application should be updated to perform authentication using WorkOS, and the signup flag block disabled. This helps to ensure the export/import process captures all active users.
+
+### (B) Use a dual-write strategy
+
+For applications that want to avoid disabling signups, a “dual-write” strategy can be used.
+
+![Diagram demonstrating the dual-write process.](https://images.workoscdn.com/images/656fbbac-adb1-4f99-b416-056d80e408ac.png?auto=format&fit=clip&q=80)[border=false]
+
+When a new user signs-up, in addition to creating a user record in the existing user store, the application should also create a matching record in WorkOS using the [Create User API](/reference/user-management/user/create). As time passes, WorkOS will stay consistent with future new users, but a migration will still need to be performed for the historical set of users.
+
+You will need to perform the same export and import process into WorkOS, but keeping in mind that some users will already exist in WorkOS as a result from the “dual-write”.
+
+While this minimizes forms of downtime for your application, there are other complications. For example, if a user updates their email or authentication method, you will need to perform the same update in WorkOS, at least until the migration process is complete.
+
+### Which to choose?
+
+Your timeline for completing the migration, along with your user’s tolerances for disruption, will affect which strategy makes more sense for your application.
+
+Disabling signups, or even sign-in entirely, and doing a “big-bang” migration by moving all users at the same time, could be reasonable for a smaller application. However, larger applications that are on the critical path for their customers may need a more careful path in order to provide consistent access.
+
+## Wrapping-up
+
+User management migration complexity can vary, so it is important to consider how existing application constraints will transfer to WorkOS. If you have any questions, reach out to [support@workos.com](mailto:support@workos.com) or via your team’s WorkOS Slack channel for more help planning your migration.