From e36e69a0276c31eb85297b32a257a4647fa4152d Mon Sep 17 00:00:00 2001 From: Ankit Tiwari Date: Wed, 17 Apr 2024 16:06:00 +0530 Subject: [PATCH 1/2] feat: Add bulk import docs --- v2/emailpassword/migration/about.mdx | 43 +-- .../ep-migration-without-password-hash.mdx | 6 +- .../migration/session-migration.mdx | 2 +- v2/passwordless/migration/about.mdx | 43 +-- v2/thirdparty/migration/about.mdx | 43 +-- .../migration/about.mdx | 43 +-- .../bulk-user-import-schema-examples.mdx | 200 ++++++++++++++ .../migration/bulk-user-import.mdx | 253 ++++++++++++++++++ .../ep-migration-without-password-hash.mdx | 8 +- .../migration/session-migration.mdx | 2 +- v2/thirdpartyemailpassword/sidebars.js | 15 +- v2/thirdpartypasswordless/migration/about.mdx | 43 +-- 12 files changed, 535 insertions(+), 166 deletions(-) create mode 100644 v2/thirdpartyemailpassword/migration/bulk-user-import-schema-examples.mdx create mode 100644 v2/thirdpartyemailpassword/migration/bulk-user-import.mdx rename v2/thirdpartyemailpassword/migration/{account-creation => }/ep-migration-without-password-hash.mdx (99%) diff --git a/v2/emailpassword/migration/about.mdx b/v2/emailpassword/migration/about.mdx index 08b0ef756..d653d9910 100644 --- a/v2/emailpassword/migration/about.mdx +++ b/v2/emailpassword/migration/about.mdx @@ -9,42 +9,27 @@ hide_title: true # About -In this guide we will be going through the process of migrating users from an external Authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication provider to SuperTokens. -There are 3 steps to user migration: +Migration involves two main steps: -- Account Migration - - User Creation - - UserId Mapping - - Mark email as verified -- User Data Migration -- Session Migration +Account Migration +Session Migration ## Step 1) Account Migration: -### User Creation -- Our first step involves creating a SuperTokens user by importing their account credentials from the previous authentication provider. -- You can learn more about how to implement these changes in the [User Creation](./account-creation/user-creation) section. +In the first step, use the Bulk User Import API to create a SuperTokens user for each user in your existing authentication provider. This API allows you to: -### User ID Mapping -- If you have stored information against existing userIds in your application table, you can use UserId Mapping to map the existing userId to the user's SuperTokens userId. -- Once the userIds are mapped you can use the existing userId to interact with all of SuperTokens APIs. -- You can learn more about how to implement these changes in the [User Id Mapping](./account-creation/user-id-mapping) section. +- Create a SuperTokens user. +- Map the existing userId to the SuperTokens userId. +- Mark the email as verified (if applicable). +- Add roles, metadata, and MFA devices (if applicable). +- Perform account linking (if applicable). -### Mark email as verified -- Once a SuperTokens user has been created and their userId has been mapped, you need to mark their email as verified (if applicable) so that they do not have to go through the email verification process again. -- You can learn more about how to implement these changes in [this section](./account-creation/email-verification). +For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. -## Step 2) User Data Migration -- Now that your user's account has been migrated over to SuperTokens we can associate additional information like roles and metadata with your user. -- You can learn more about how to implement these changes in the [User Data Migration](./data-migration) section. +## Step 2) Session Migration -## Step 3) Session Migration +If users have active sessions, use [this guide](./session-migration) to migrate their external provider sessions to SuperTokens sessions. This way, users won't need to re-authenticate. -- If you have users with an existing session, you can use [this guide](./session-migration) to migrate their external provider sessions to a SuperTokens session. -- This will prevent users from having to re-authenticate. - -You can learn more about how to implement these changes in the [Session Migration](./session-migration) section. - -## Step 4) MFA migration -If you are using MFA in your app, checkout the MFA migration section [here](/docs/mfa/migration) after you have gone through the above migration steps. +Learn how to implement session migration in the [Session Migration](./session-migration) section. diff --git a/v2/emailpassword/migration/account-creation/ep-migration-without-password-hash.mdx b/v2/emailpassword/migration/account-creation/ep-migration-without-password-hash.mdx index 0b9238935..890f9c6b6 100644 --- a/v2/emailpassword/migration/account-creation/ep-migration-without-password-hash.mdx +++ b/v2/emailpassword/migration/account-creation/ep-migration-without-password-hash.mdx @@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem'; # User Creation without password hashes - + :::caution @@ -758,7 +758,7 @@ func generatePassword() string { - + The code above overrides the `generatePasswordResetTokenPOST` API. This is the first step in the password reset flow and is responsible for generating the password reset token to be sent with the reset password email. @@ -1299,7 +1299,7 @@ func validateAndGetUserInfoFromExternalProvider(email string, password string) * The code above adds the following changes to the `signIn` function: - + - Adds an additional check where if a user exists in SuperTokens, we check if they have the `isUsingTemporaryPassword` flag set in their metadata. diff --git a/v2/emailpassword/migration/session-migration.mdx b/v2/emailpassword/migration/session-migration.mdx index d149f3982..8c7100412 100644 --- a/v2/emailpassword/migration/session-migration.mdx +++ b/v2/emailpassword/migration/session-migration.mdx @@ -1,6 +1,6 @@ --- id: session-migration -title: Step 3) Session Migration +title: Session Migration hide_title: true --- diff --git a/v2/passwordless/migration/about.mdx b/v2/passwordless/migration/about.mdx index 08b0ef756..d653d9910 100644 --- a/v2/passwordless/migration/about.mdx +++ b/v2/passwordless/migration/about.mdx @@ -9,42 +9,27 @@ hide_title: true # About -In this guide we will be going through the process of migrating users from an external Authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication provider to SuperTokens. -There are 3 steps to user migration: +Migration involves two main steps: -- Account Migration - - User Creation - - UserId Mapping - - Mark email as verified -- User Data Migration -- Session Migration +Account Migration +Session Migration ## Step 1) Account Migration: -### User Creation -- Our first step involves creating a SuperTokens user by importing their account credentials from the previous authentication provider. -- You can learn more about how to implement these changes in the [User Creation](./account-creation/user-creation) section. +In the first step, use the Bulk User Import API to create a SuperTokens user for each user in your existing authentication provider. This API allows you to: -### User ID Mapping -- If you have stored information against existing userIds in your application table, you can use UserId Mapping to map the existing userId to the user's SuperTokens userId. -- Once the userIds are mapped you can use the existing userId to interact with all of SuperTokens APIs. -- You can learn more about how to implement these changes in the [User Id Mapping](./account-creation/user-id-mapping) section. +- Create a SuperTokens user. +- Map the existing userId to the SuperTokens userId. +- Mark the email as verified (if applicable). +- Add roles, metadata, and MFA devices (if applicable). +- Perform account linking (if applicable). -### Mark email as verified -- Once a SuperTokens user has been created and their userId has been mapped, you need to mark their email as verified (if applicable) so that they do not have to go through the email verification process again. -- You can learn more about how to implement these changes in [this section](./account-creation/email-verification). +For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. -## Step 2) User Data Migration -- Now that your user's account has been migrated over to SuperTokens we can associate additional information like roles and metadata with your user. -- You can learn more about how to implement these changes in the [User Data Migration](./data-migration) section. +## Step 2) Session Migration -## Step 3) Session Migration +If users have active sessions, use [this guide](./session-migration) to migrate their external provider sessions to SuperTokens sessions. This way, users won't need to re-authenticate. -- If you have users with an existing session, you can use [this guide](./session-migration) to migrate their external provider sessions to a SuperTokens session. -- This will prevent users from having to re-authenticate. - -You can learn more about how to implement these changes in the [Session Migration](./session-migration) section. - -## Step 4) MFA migration -If you are using MFA in your app, checkout the MFA migration section [here](/docs/mfa/migration) after you have gone through the above migration steps. +Learn how to implement session migration in the [Session Migration](./session-migration) section. diff --git a/v2/thirdparty/migration/about.mdx b/v2/thirdparty/migration/about.mdx index 08b0ef756..d653d9910 100644 --- a/v2/thirdparty/migration/about.mdx +++ b/v2/thirdparty/migration/about.mdx @@ -9,42 +9,27 @@ hide_title: true # About -In this guide we will be going through the process of migrating users from an external Authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication provider to SuperTokens. -There are 3 steps to user migration: +Migration involves two main steps: -- Account Migration - - User Creation - - UserId Mapping - - Mark email as verified -- User Data Migration -- Session Migration +Account Migration +Session Migration ## Step 1) Account Migration: -### User Creation -- Our first step involves creating a SuperTokens user by importing their account credentials from the previous authentication provider. -- You can learn more about how to implement these changes in the [User Creation](./account-creation/user-creation) section. +In the first step, use the Bulk User Import API to create a SuperTokens user for each user in your existing authentication provider. This API allows you to: -### User ID Mapping -- If you have stored information against existing userIds in your application table, you can use UserId Mapping to map the existing userId to the user's SuperTokens userId. -- Once the userIds are mapped you can use the existing userId to interact with all of SuperTokens APIs. -- You can learn more about how to implement these changes in the [User Id Mapping](./account-creation/user-id-mapping) section. +- Create a SuperTokens user. +- Map the existing userId to the SuperTokens userId. +- Mark the email as verified (if applicable). +- Add roles, metadata, and MFA devices (if applicable). +- Perform account linking (if applicable). -### Mark email as verified -- Once a SuperTokens user has been created and their userId has been mapped, you need to mark their email as verified (if applicable) so that they do not have to go through the email verification process again. -- You can learn more about how to implement these changes in [this section](./account-creation/email-verification). +For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. -## Step 2) User Data Migration -- Now that your user's account has been migrated over to SuperTokens we can associate additional information like roles and metadata with your user. -- You can learn more about how to implement these changes in the [User Data Migration](./data-migration) section. +## Step 2) Session Migration -## Step 3) Session Migration +If users have active sessions, use [this guide](./session-migration) to migrate their external provider sessions to SuperTokens sessions. This way, users won't need to re-authenticate. -- If you have users with an existing session, you can use [this guide](./session-migration) to migrate their external provider sessions to a SuperTokens session. -- This will prevent users from having to re-authenticate. - -You can learn more about how to implement these changes in the [Session Migration](./session-migration) section. - -## Step 4) MFA migration -If you are using MFA in your app, checkout the MFA migration section [here](/docs/mfa/migration) after you have gone through the above migration steps. +Learn how to implement session migration in the [Session Migration](./session-migration) section. diff --git a/v2/thirdpartyemailpassword/migration/about.mdx b/v2/thirdpartyemailpassword/migration/about.mdx index 08b0ef756..5ee154abe 100644 --- a/v2/thirdpartyemailpassword/migration/about.mdx +++ b/v2/thirdpartyemailpassword/migration/about.mdx @@ -9,42 +9,27 @@ hide_title: true # About -In this guide we will be going through the process of migrating users from an external Authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication provider to SuperTokens. -There are 3 steps to user migration: +Migration involves two main steps: -- Account Migration - - User Creation - - UserId Mapping - - Mark email as verified -- User Data Migration -- Session Migration +Account Migration +Session Migration ## Step 1) Account Migration: -### User Creation -- Our first step involves creating a SuperTokens user by importing their account credentials from the previous authentication provider. -- You can learn more about how to implement these changes in the [User Creation](./account-creation/user-creation) section. +In the first step, use the Bulk User Import API to create a SuperTokens user for each user in your existing authentication provider. This API allows you to: -### User ID Mapping -- If you have stored information against existing userIds in your application table, you can use UserId Mapping to map the existing userId to the user's SuperTokens userId. -- Once the userIds are mapped you can use the existing userId to interact with all of SuperTokens APIs. -- You can learn more about how to implement these changes in the [User Id Mapping](./account-creation/user-id-mapping) section. +- Create a SuperTokens user. +- Map the existing userId to the SuperTokens userId. +- Mark the email as verified (if applicable). +- Add roles, metadata, and MFA devices (if applicable). +- Perform account linking (if applicable). -### Mark email as verified -- Once a SuperTokens user has been created and their userId has been mapped, you need to mark their email as verified (if applicable) so that they do not have to go through the email verification process again. -- You can learn more about how to implement these changes in [this section](./account-creation/email-verification). +For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. -## Step 2) User Data Migration -- Now that your user's account has been migrated over to SuperTokens we can associate additional information like roles and metadata with your user. -- You can learn more about how to implement these changes in the [User Data Migration](./data-migration) section. +## Step 2) Session Migration -## Step 3) Session Migration +If users have active sessions, use [this guide](./session-migration) to migrate their external provider sessions to SuperTokens sessions. This way, users won't need to re-authenticate. -- If you have users with an existing session, you can use [this guide](./session-migration) to migrate their external provider sessions to a SuperTokens session. -- This will prevent users from having to re-authenticate. - -You can learn more about how to implement these changes in the [Session Migration](./session-migration) section. - -## Step 4) MFA migration -If you are using MFA in your app, checkout the MFA migration section [here](/docs/mfa/migration) after you have gone through the above migration steps. +Learn how to implement session migration in the [Session Migration](./session-migration) section. \ No newline at end of file diff --git a/v2/thirdpartyemailpassword/migration/bulk-user-import-schema-examples.mdx b/v2/thirdpartyemailpassword/migration/bulk-user-import-schema-examples.mdx new file mode 100644 index 000000000..0cd39a53b --- /dev/null +++ b/v2/thirdpartyemailpassword/migration/bulk-user-import-schema-examples.mdx @@ -0,0 +1,200 @@ +--- +id: bulk-user-import-schema-examples +title: Bulk User Import Schema and Examples +hide_title: true +--- + +# Bulk User Import Schema and Examples + + +The bulk import API expects the payload in the following format. + +```json +{ + "users": { + "type": "array", + "items": { + "type": "object", + "properties": { + "externalUserId": { + "type": "string", + "description": "The existing user id in your current auth provider." + }, + "userMetadata": { + "type": "object", + "description": "Any JSON serializable data you want to associate with the user." + }, + "userRoles": { + "type": "array", + "items": { + "type": "object", + "properties": { + "tenantIds": { + "type": "array", + "items": { + "type": "string", + "description": "The tenantId of the tenant where this role should be assigned." + }, + }, + "role": { + "type": "string", + "description": "The role of the user. These roles must be pre-created before importing the user." + }, + "required": ["tenantIds", "role"] + }, + } + }, + "totpDevices": { + "type": "array", + "items": { + "type": "object", + "properties": { + "secret": { + "type": "string", + "description": "The OTP secret, used with authenticator apps (e.g., Google Authenticator, Authy), must be supplied in base32 encoding like: MFRGGZDFMZTWQ33Q." + }, + "period": { + "type": "integer", + "description": "Time in seconds a TOTP code is valid. Default is 30 seconds.", + "default": 30 + }, + "skew": { + "type": "integer", + "description": "Allowed time difference in seconds between server and client devices. Default is 0 seconds.", + "default": 0 + }, + "deviceName": { + "type": "string", + "description": "Optional name for the device associated with the TOTP secret (e.g., 'My Phone')." + }, + "required": ["secret"] + } + } + }, + "loginMethods": { + "type": "array", + "items": { + "type": "object", + "properties": { + "recipeId": { + "type": "string", + "description": "The recipe id for this login method.", + "enum": ["emailpassword", "thirdparty", "passwordless"] + }, + "tenantIds": { + "type": "array", + "items": { + "type": "string", + "description": "The tenantId of the tenant where this login method should be created." + }, + "default": ["public"] + }, + "email": { + "type": "string", + "description": "The email of the user. This is applicable for all the recipes but only required in emailpassword and thirdparty recipe.", + }, + "passwordHash": { + "type": "string", + "description": "Hashed password for the user. This is required for the emailpassword recipe.", + }, + "hashingAlgorithm": { + "type": "string", + "description": "The hashing algorithm used to hash the password. This is required for the emailpassword recipe.", + "enum": ["bcrypt", "argon2", "firebase_scrypt"], + }, + "isVerified": { + "type": "boolean", + "description": "Whether the email is verified or not.", + "default": false + }, + "isPrimary": { + "type": "boolean", + "description": "Whether this login method is the primary login method for the user. Only one login method can be primary.", + "default": false + }, + "timeJoinedInMSSinceEpoch": { + "type": "integer", + "description": "The time the user joined in milliseconds since epoch.", + }, + "thirdPartyId": { + "type": "string", + "description": "The id of the third party provider. This is required for the thirdparty recipe.", + }, + "thirdPartyUserId": { + "type": "string", + "description": "The id of the user in the third party provider. This is required for the thirdparty recipe.", + }, + "phoneNumber": { + "type": "string", + "description": "The phone number of the user. This is applicable for the passwordless recipe. Required if email is not passed.", + }, + "required": ["recipeId"] + } + } + }, + } + }, + "required": ["loginMethods"] + } + } + +``` + +## Examples + +### Example 1: Sample Bulk User Import JSON + +```json +{ + "users": [ + { + "externalUserId": "fa7a0841-b533-4478-95533-0fde890c3483", + "userMetadata": { + "subscriptionPlan": "PREMIUM", + "theme": "dark" + }, + "userRoles": [ + { + "tenantIds": ["public"], + "role": "admin" + } + ], + "totpDevices": [ + { + "secret": "MFRGGZDFMZTWQ33Q" + } + ], + "loginMethods": [ + { + "recipeId": "emailpassword", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": true, + "email": "johndoe@gmail.com", + "passwordHash": "$argon2d$v=19$m=12,t=3,p=1$aGI4enNvMmd0Zm0wMDAwMA$r6p7qbr6HD+8CD7sBi4HVw", + "hashingAlgorithm": "argon2", + "timeJoinedInMSSinceEpoch": 1713260578868 + }, + { + "recipeId": "thirdparty", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": false, + "email": "johndoe@gmail.com", + "thirdPartyId": "google", + "thirdPartyUserId": "106347997792363870000", + "timeJoinedInMSSinceEpoch": 1713260578868 + }, + { + "recipeId": "passwordless", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": false, + "email": "johndoe@gmail.com", + "timeJoinedInMSSinceEpoch": 1713260578868 + }, + ] + } + ] +} +``` diff --git a/v2/thirdpartyemailpassword/migration/bulk-user-import.mdx b/v2/thirdpartyemailpassword/migration/bulk-user-import.mdx new file mode 100644 index 000000000..ae79c230e --- /dev/null +++ b/v2/thirdpartyemailpassword/migration/bulk-user-import.mdx @@ -0,0 +1,253 @@ +--- +id: bulk-user-import +title: Bulk User Import +hide_title: true +--- + +import CoreInjector from "/src/components/coreInjector"; +import Tabs from '@theme/Tabs'; +import SelfHostedTabs from "/src/components/tabs/SelfHostedTabs" +import TabItem from '@theme/TabItem'; + +# Bulk User Import + +The Bulk User Import API can be used to import users with both `emailpassword` and `thirdparty` recipes simultaneously. Learn more about this API in the [CDI specs](https://app.swaggerhub.com/apis/supertokens/CDI/5.1.0#/Bulk%20Import/getBulkImportUsers). + +SuperTokens currently supports importing users with `BCrypt`, `Argon2` or `Firebase Scrypt` password hashes. + +:::important +If you do not have access to your user's password hashes, you can use our [guide for migrating them dynamically during login](./ep-migration-without-password-hash). +::: + +## Step 1: Prepare the import JSON file + +Convert your existing authentication provider data to the required format as specified [here](./bulk-user-import-schema-examples.mdx). An example JSON would look like this: + +```json +{ + "users": [ + { + "loginMethods": [ + { + "recipeId": "emailpassword", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": true, + "email": "johndoe@gmail.com", + "passwordHash": "$argon2d$v=19$m=12,t=3,p=1$aGI4enNvMmd0Zm0wMDAwMA$r6p7qbr6HD+8CD7sBi4HVw", + "hashingAlgorithm": "argon2", + "timeJoinedInMSSinceEpoch": 1713260578868 + }, + { + "recipeId": "thirdparty", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": false, + "email": "johndoe@gmail.com", + "thirdPartyId": "google", + "thirdPartyUserId": "106347997792363870000", + "timeJoinedInMSSinceEpoch": 1713260578868 + } + ] + } + ] +} +``` + +:::info +For more info on adding fields like `externalUserId`, `userMetadata`, `userRoles`, and `totpDevices`, review the [examples](./bulk-user-import-schema-examples.mdx) here. +::: + +
+Importing users With Firebase Scrypt Password hashes +Importing users from Firebases requires an update to your supertokens core config and formatting the input password hash. + +#### Step 1: Retrive your Firebase password hashing parameters from your dashboard. + +Firebase password hashing details modal + +#### Step 2: Update the SuperTokens core to use the `base64_signer_key` + + + + +- Edit the core configuration in the SuperTokens Managed Service Dashboard. +- Set the `firebase_password_hashing_signer_key` field in the config to the `base64_signer_key` retrieved from your firebase hashing parameters. + + + + + + + + + +```bash + docker run \ + -p 3567:3567 \ + // highlight-next-line + -e FIREBASE_PASSWORD_HASHING_SIGNER_KEY="gRhC3eDeQOdyEn4bMd9c6kxguWVmcIVq/HbJKnCXdWscZx0l2WbCJ1wbg==" \ + -d registry.supertokens.io/supertokens/supertokens- +``` + + + + +```yaml +# Add your base64_signer_key to the following in the config.yaml file. +# The file path can be found by running the "supertokens --help" command + +firebase_password_hashing_signer_key: "gRhC3eDeQOdyEn4bMd9c6kxguWVmcIVq/HbJKnCXdWscZx0l2WbCJ1wbg==" +``` + + + + + + + + +#### Step 3: SuperTokens requires firebase password hashes to be in a specific format to be parsed. + + For example: + + Your exported firebase user has the following credentials: + ```json + { + "users": [ + { + "localId": "userId", + "email": "johnDoe@example.com" + "passwordHash": "9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==", + "salt": "/cj0jC1br5o4+w==", + } + ] + } + ``` + + The memory cost, rounds and salt separator retrived from the password hashing config are: + ```json + { + mem_cost: 14, + rounds: 8, + base64_salt_separator: "Bw==" + } + ``` + + The password hash would be the following: `$f_scrypt$9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==$/cj0jC1br5o4+w==$m=14$r=8$s=Bw==` + + The example password hash is in the following format `$f_scrypt$$$m=$r=$s=` + +#### Step 4: Use the formatted password hash in the import JSON file + +```json +{ + "users": [ + { + "loginMethods": [ + { + "recipeId": "emailpassword", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": true, + "email": "johndoe@gmail.com", + "passwordHash": "$f_scrypt$9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==$/cj0jC1br5o4+w==$m=14$r=8$s=Bw==", + "hashingAlgorithm": "firebase_scrypt", + "timeJoinedInMSSinceEpoch": 1713260578868 + }, + { + "recipeId": "thirdparty", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": false, + "email": "johndoe@gmail.com", + "thirdPartyId": "google", + "thirdPartyUserId": "106347997792363870000", + "timeJoinedInMSSinceEpoch": 1713260578868 + } + ] + } + ] +} +``` +
+ +## Step 2: Add the users for import + +To import users, make a POST request to the bulk import API with contents of the JSON file as the request body. The API supports up to 10,000 users per request. For larger files, submit multiple requests or use our [script](https://github.com/supertokens/supertokens-core/tree/master/bulkimport_scripts/add_users_for_bulk_import) to automate the process. + +A successful request will return a 200 response. If there are validation errors, you'll receive a 400 response with error messages, including the user's index in the input JSON. No users will be imported if validation errors occur. Retry after fixing the errors. + + + +```bash +curl --location --request POST '^{coreInjector_uri_without_quotes}/bulk-import/users' \ +--header 'api-key: ^{coreInjector_api_key_without_quotes}' \ +--header 'Content-Type: application/json; charset=utf-8' \ +--data-raw '{ + "users": [ + { + "loginMethods": [ + { + "recipeId": "emailpassword", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": true, + "email": "johndoe@gmail.com", + "passwordHash": "$argon2d$v=19$m=12,t=3,p=1$aGI4enNvMmd0Zm0wMDAwMA$r6p7qbr6HD+8CD7sBi4HVw", + "hashingAlgorithm": "argon2", + "timeJoinedInMSSinceEpoch": 1713260578868 + }, + { + "recipeId": "thirdparty", + "tenantIds": ["public"], + "isVerified": true, + "isPrimary": false, + "email": "johndoe@gmail.com", + "thirdPartyId": "google", + "thirdPartyUserId": "106347997792363870000", + "timeJoinedInMSSinceEpoch": 1713260578868 + } + ] + } + ] +}' +``` + + +## Step 3: Monitor the import status + +Monitor the import status with a GET request to the bulk import API. Filter the response using the `status` query parameter, which can be 'NEW', 'PROCESSING', or 'FAILED'. Completed entries are automatically deleted. + +Entries with `FAILED` status will have errors in the `errorMessage` field. Fix the errors and re-import the users. + + + +```bash +curl --location --request GET '^{coreInjector_uri_without_quotes}/bulk-import/users?status=FAILED' \ +--header 'api-key: ^{coreInjector_api_key_without_quotes}' +``` + + +## Step 4: Delete the failed entries + +Failed entries aren't automatically deleted. Remove them with a DELETE request to the bulk import API. Deleting the entries is not required for re-importing them but it is a good practice to delete them to keep the data clean. + +The response will indicate which entries were deleted and which couldn't be due to invalid IDs. + + + +```bash +curl --location --request DELETE '^{coreInjector_uri_without_quotes}/bulk-import/users' \ +--header 'api-key: ^{coreInjector_api_key_without_quotes}' \ +--header 'Content-Type: application/json; charset=utf-8' \ +--data-raw '{ + "ids": ["29d90b2a-0e19-4d2c-b7b9-2005c2906f34", "bad3741b-a0d0-4ad3-b6aa-f4d38e1066a4"] +}' +``` + diff --git a/v2/thirdpartyemailpassword/migration/account-creation/ep-migration-without-password-hash.mdx b/v2/thirdpartyemailpassword/migration/ep-migration-without-password-hash.mdx similarity index 99% rename from v2/thirdpartyemailpassword/migration/account-creation/ep-migration-without-password-hash.mdx rename to v2/thirdpartyemailpassword/migration/ep-migration-without-password-hash.mdx index 39533a118..a92694651 100644 --- a/v2/thirdpartyemailpassword/migration/account-creation/ep-migration-without-password-hash.mdx +++ b/v2/thirdpartyemailpassword/migration/ep-migration-without-password-hash.mdx @@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem'; # User Creation without password hashes - + :::caution @@ -814,7 +814,7 @@ func generatePassword() string { - + The code above overrides the `generatePasswordResetTokenPOST` API. This is the first step in the password reset flow and is responsible for generating the password reset token to be sent with the reset password email. @@ -989,7 +989,7 @@ func main() { - + @@ -1382,7 +1382,7 @@ func validateAndGetUserInfoFromExternalProvider(email string, password string) * The code above adds the following changes to the `emailPasswordSignIn` function: - + - Adds an additional check where if a user exists in SuperTokens, we check if they have the `isUsingTemporaryPassword` flag set in their metadata. diff --git a/v2/thirdpartyemailpassword/migration/session-migration.mdx b/v2/thirdpartyemailpassword/migration/session-migration.mdx index dd6d5a8f9..fff8857e2 100644 --- a/v2/thirdpartyemailpassword/migration/session-migration.mdx +++ b/v2/thirdpartyemailpassword/migration/session-migration.mdx @@ -1,6 +1,6 @@ --- id: session-migration -title: Step 3) Session Migration +title: Session Migration hide_title: true --- diff --git a/v2/thirdpartyemailpassword/sidebars.js b/v2/thirdpartyemailpassword/sidebars.js index be470a6c1..6d7929c30 100644 --- a/v2/thirdpartyemailpassword/sidebars.js +++ b/v2/thirdpartyemailpassword/sidebars.js @@ -737,19 +737,10 @@ module.exports = { label: 'Migration', items: [ "migration/about", - { - type: 'category', - label: 'Step 1) Account Creation', - items: [ - "migration/account-creation/user-creation", - "migration/account-creation/user-id-mapping", - "migration/account-creation/email-verification", - "migration/account-creation/ep-migration-without-password-hash" - ], - }, - "migration/data-migration", + "migration/bulk-user-import", "migration/session-migration", - "migration/mfa-migration" + "migration/bulk-user-import-schema-examples", + "migration/ep-migration-without-password-hash" ], }, { diff --git a/v2/thirdpartypasswordless/migration/about.mdx b/v2/thirdpartypasswordless/migration/about.mdx index 08b0ef756..d653d9910 100644 --- a/v2/thirdpartypasswordless/migration/about.mdx +++ b/v2/thirdpartypasswordless/migration/about.mdx @@ -9,42 +9,27 @@ hide_title: true # About -In this guide we will be going through the process of migrating users from an external Authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication provider to SuperTokens. -There are 3 steps to user migration: +Migration involves two main steps: -- Account Migration - - User Creation - - UserId Mapping - - Mark email as verified -- User Data Migration -- Session Migration +Account Migration +Session Migration ## Step 1) Account Migration: -### User Creation -- Our first step involves creating a SuperTokens user by importing their account credentials from the previous authentication provider. -- You can learn more about how to implement these changes in the [User Creation](./account-creation/user-creation) section. +In the first step, use the Bulk User Import API to create a SuperTokens user for each user in your existing authentication provider. This API allows you to: -### User ID Mapping -- If you have stored information against existing userIds in your application table, you can use UserId Mapping to map the existing userId to the user's SuperTokens userId. -- Once the userIds are mapped you can use the existing userId to interact with all of SuperTokens APIs. -- You can learn more about how to implement these changes in the [User Id Mapping](./account-creation/user-id-mapping) section. +- Create a SuperTokens user. +- Map the existing userId to the SuperTokens userId. +- Mark the email as verified (if applicable). +- Add roles, metadata, and MFA devices (if applicable). +- Perform account linking (if applicable). -### Mark email as verified -- Once a SuperTokens user has been created and their userId has been mapped, you need to mark their email as verified (if applicable) so that they do not have to go through the email verification process again. -- You can learn more about how to implement these changes in [this section](./account-creation/email-verification). +For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. -## Step 2) User Data Migration -- Now that your user's account has been migrated over to SuperTokens we can associate additional information like roles and metadata with your user. -- You can learn more about how to implement these changes in the [User Data Migration](./data-migration) section. +## Step 2) Session Migration -## Step 3) Session Migration +If users have active sessions, use [this guide](./session-migration) to migrate their external provider sessions to SuperTokens sessions. This way, users won't need to re-authenticate. -- If you have users with an existing session, you can use [this guide](./session-migration) to migrate their external provider sessions to a SuperTokens session. -- This will prevent users from having to re-authenticate. - -You can learn more about how to implement these changes in the [Session Migration](./session-migration) section. - -## Step 4) MFA migration -If you are using MFA in your app, checkout the MFA migration section [here](/docs/mfa/migration) after you have gone through the above migration steps. +Learn how to implement session migration in the [Session Migration](./session-migration) section. From 3f024b8619828ab8031f0b302ad65cbf92b6f065 Mon Sep 17 00:00:00 2001 From: Ankit Tiwari Date: Tue, 30 Apr 2024 13:45:44 +0530 Subject: [PATCH 2/2] fix: PR changes --- v2/emailpassword/migration/about.mdx | 8 ++++---- v2/passwordless/migration/about.mdx | 8 ++++---- v2/thirdparty/migration/about.mdx | 8 ++++---- v2/thirdpartyemailpassword/migration/about.mdx | 8 ++++---- .../migration/bulk-user-import.mdx | 13 +++++++++---- v2/thirdpartypasswordless/migration/about.mdx | 8 ++++---- 6 files changed, 29 insertions(+), 24 deletions(-) diff --git a/v2/emailpassword/migration/about.mdx b/v2/emailpassword/migration/about.mdx index d653d9910..6e86d15d1 100644 --- a/v2/emailpassword/migration/about.mdx +++ b/v2/emailpassword/migration/about.mdx @@ -9,12 +9,12 @@ hide_title: true # About -This guide explains how to migrate users from an external authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication providers like `Auth0` to SuperTokens. Migration involves two main steps: -Account Migration -Session Migration +- Account Migration +- Session Migration ## Step 1) Account Migration: @@ -24,7 +24,7 @@ In the first step, use the Bulk User Import API to create a SuperTokens user for - Map the existing userId to the SuperTokens userId. - Mark the email as verified (if applicable). - Add roles, metadata, and MFA devices (if applicable). -- Perform account linking (if applicable). +- Link multiple login methods for the same user (if applicable). For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. diff --git a/v2/passwordless/migration/about.mdx b/v2/passwordless/migration/about.mdx index d653d9910..6e86d15d1 100644 --- a/v2/passwordless/migration/about.mdx +++ b/v2/passwordless/migration/about.mdx @@ -9,12 +9,12 @@ hide_title: true # About -This guide explains how to migrate users from an external authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication providers like `Auth0` to SuperTokens. Migration involves two main steps: -Account Migration -Session Migration +- Account Migration +- Session Migration ## Step 1) Account Migration: @@ -24,7 +24,7 @@ In the first step, use the Bulk User Import API to create a SuperTokens user for - Map the existing userId to the SuperTokens userId. - Mark the email as verified (if applicable). - Add roles, metadata, and MFA devices (if applicable). -- Perform account linking (if applicable). +- Link multiple login methods for the same user (if applicable). For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. diff --git a/v2/thirdparty/migration/about.mdx b/v2/thirdparty/migration/about.mdx index d653d9910..6e86d15d1 100644 --- a/v2/thirdparty/migration/about.mdx +++ b/v2/thirdparty/migration/about.mdx @@ -9,12 +9,12 @@ hide_title: true # About -This guide explains how to migrate users from an external authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication providers like `Auth0` to SuperTokens. Migration involves two main steps: -Account Migration -Session Migration +- Account Migration +- Session Migration ## Step 1) Account Migration: @@ -24,7 +24,7 @@ In the first step, use the Bulk User Import API to create a SuperTokens user for - Map the existing userId to the SuperTokens userId. - Mark the email as verified (if applicable). - Add roles, metadata, and MFA devices (if applicable). -- Perform account linking (if applicable). +- Link multiple login methods for the same user (if applicable). For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. diff --git a/v2/thirdpartyemailpassword/migration/about.mdx b/v2/thirdpartyemailpassword/migration/about.mdx index 5ee154abe..bc5fade44 100644 --- a/v2/thirdpartyemailpassword/migration/about.mdx +++ b/v2/thirdpartyemailpassword/migration/about.mdx @@ -9,12 +9,12 @@ hide_title: true # About -This guide explains how to migrate users from an external authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication providers like `Auth0` to SuperTokens. Migration involves two main steps: -Account Migration -Session Migration +- Account Migration +- Session Migration ## Step 1) Account Migration: @@ -24,7 +24,7 @@ In the first step, use the Bulk User Import API to create a SuperTokens user for - Map the existing userId to the SuperTokens userId. - Mark the email as verified (if applicable). - Add roles, metadata, and MFA devices (if applicable). -- Perform account linking (if applicable). +- Link multiple login methods for the same user (if applicable). For implementation details, refer to the [Bulk User Import](./bulk-user-import) section. diff --git a/v2/thirdpartyemailpassword/migration/bulk-user-import.mdx b/v2/thirdpartyemailpassword/migration/bulk-user-import.mdx index ae79c230e..87894e6e4 100644 --- a/v2/thirdpartyemailpassword/migration/bulk-user-import.mdx +++ b/v2/thirdpartyemailpassword/migration/bulk-user-import.mdx @@ -222,9 +222,12 @@ curl --location --request POST '^{coreInjector_uri_without_quotes}/bulk-import/u ## Step 3: Monitor the import status -Monitor the import status with a GET request to the bulk import API. Filter the response using the `status` query parameter, which can be 'NEW', 'PROCESSING', or 'FAILED'. Completed entries are automatically deleted. -Entries with `FAILED` status will have errors in the `errorMessage` field. Fix the errors and re-import the users. +After adding users for import, a cron job will start processing them one by one. Initially, all entries will have the status `NEW`, which will change to `PROCESSING` as the cron job begins working through the list. If an entry fails, its status updates to `FAILED`, and an error message is recorded with the entry. Successfully imported entries are removed from the database. + +You can check the import status by sending a GET request to the bulk import API. Use the status query parameter to filter results by `NEW`, `PROCESSING`, or `FAILED`. + +Entries with FAILED status will contain the error message in the `errorMessage` field. @@ -234,16 +237,18 @@ curl --location --request GET '^{coreInjector_uri_without_quotes}/bulk-import/us ``` +An import is complete when there are no more entries with a `NEW` or `PROCESSING` status. If any entries have a `FAILED` status, you'll need to fix the errors and re-import them. + ## Step 4: Delete the failed entries -Failed entries aren't automatically deleted. Remove them with a DELETE request to the bulk import API. Deleting the entries is not required for re-importing them but it is a good practice to delete them to keep the data clean. +Failed entries aren't automatically deleted. Remove them with a POST request to the remove bulk import users API. Deleting the entries is not required for re-importing them but it is a good practice to delete them to keep the data clean. The response will indicate which entries were deleted and which couldn't be due to invalid IDs. ```bash -curl --location --request DELETE '^{coreInjector_uri_without_quotes}/bulk-import/users' \ +curl --location --request POST '^{coreInjector_uri_without_quotes}/bulk-import/users/remove' \ --header 'api-key: ^{coreInjector_api_key_without_quotes}' \ --header 'Content-Type: application/json; charset=utf-8' \ --data-raw '{ diff --git a/v2/thirdpartypasswordless/migration/about.mdx b/v2/thirdpartypasswordless/migration/about.mdx index d653d9910..6e86d15d1 100644 --- a/v2/thirdpartypasswordless/migration/about.mdx +++ b/v2/thirdpartypasswordless/migration/about.mdx @@ -9,12 +9,12 @@ hide_title: true # About -This guide explains how to migrate users from an external authentication provider to SuperTokens. +This guide explains how to migrate users from an external authentication providers like `Auth0` to SuperTokens. Migration involves two main steps: -Account Migration -Session Migration +- Account Migration +- Session Migration ## Step 1) Account Migration: @@ -24,7 +24,7 @@ In the first step, use the Bulk User Import API to create a SuperTokens user for - Map the existing userId to the SuperTokens userId. - Mark the email as verified (if applicable). - Add roles, metadata, and MFA devices (if applicable). -- Perform account linking (if applicable). +- Link multiple login methods for the same user (if applicable). For implementation details, refer to the [Bulk User Import](./bulk-user-import) section.