Skip to content

Commit ab2356c

Browse files
bcbogdanbcbogdan
committed
Add missing user migration data
1 parent 5bb30b4 commit ab2356c

File tree

2 files changed

+157
-1
lines changed

2 files changed

+157
-1
lines changed

‎v3/docs/migration/account-creation/user-creation.mdx

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,133 @@ hide_title: true
55
sidebar_position: 1
66
---
77

8+
import { SelfHostingTabs } from "/src/components/tabs"
9+
810
# User Creation
911

12+
## Email Password Migration
13+
14+
:::important
15+
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).
16+
:::
17+
18+
SuperTokens allows you to import users with password hashes generated with `BCrypt`, `Argon2` and `Firebase SCrypt` with our import user API.
19+
You can find the API spec [here](https://app.swaggerhub.com/apis/supertokens/CDI/2.16.0#/EmailPassword%20Recipe/userImport).
20+
21+
### Migrating users With Argon2 or BCrypt Password hashes
22+
23+
For users with `BCrypt` or `Argon2` password hashes you can use the following curl command to import your user.
24+
25+
```bash
26+
curl --location --request POST '^{coreInfo.uri}/recipe/user/passwordhash/import' \
27+
--header 'api-key: ^{coreInfo.key}' \
28+
--header 'Content-Type: application/json; charset=utf-8' \
29+
--data-raw '{
30+
"email": "[email protected]",
31+
"passwordHash": "$argon2d$v=19$m=12,t=3,p=1$NWd0eGp4ZW91b3IwMDAwMA$57jcfXF19MyiUXSjkVBpEQ"
32+
}'
33+
```
34+
35+
:::important
36+
SuperTokens accepts `BCrypt` and `Argon2` hashes in standard format. When exporting password hashes from authentication providers the structure might be changed. For example, Auth0 prepends an identifier to the exported password hashes which needs to removed before importing into SuperTokens.
37+
38+
Sample password hashes for BCrypt and Argon2 in standard format:
39+
40+
- BCrypt: `$2a$10$GzEm3vKoAqnJCTWesRARCe/ovjt/07qjvcH9jbLUg44Fn77gMZkmm`
41+
- Argon2: `$argon2id$v=19$m=16,t=2,p=1$VG1Oa1lMbzZLbzk5azQ2Qg$kjcNNtZ/b0t/8HgXUiQ76A`
42+
:::
43+
44+
45+
### Migrating users with Firebase SCrypt Password hashes
46+
47+
Importing users from Firebases requires an update to your supertokens core config and formatting the input password hash.
48+
49+
#### Step 1: Retrive your Firebase password hashing parameters from your dashboard.
50+
51+
<img src="/img/migration/firebase_password_hashing_params.png" alt="Firebase password hashing details modal" />
52+
53+
#### Step 2: Update the SuperTokens core to use the `base64_signer_key`
54+
55+
- ** For Managed Service **
56+
57+
58+
- Edit the core configuration in the SuperTokens Managed Service Dashboard.
59+
- Set the `firebase_password_hashing_signer_key` field in the config to the `base64_signer_key` retrieved from your firebase hashing parameters.
60+
61+
62+
63+
<SelfHostingTabs>
64+
65+
<SelfHostingTabs.TabItem value="with-docker">
66+
67+
```bash
68+
docker run \
69+
-p 3567:3567 \
70+
// highlight-next-line
71+
-e FIREBASE_PASSWORD_HASHING_SIGNER_KEY="gRhC3eDeQOdyEn4bMd9c6kxguWVmcIVq/HbJKnCXdWscZx0l2WbCJ1wbg==" \
72+
-d registry.supertokens.io/supertokens/supertokens-<db_name>
73+
```
74+
75+
</SelfHostingTabs.TabItem>
76+
<SelfHostingTabs.TabItem value="without-docker">
77+
78+
```yaml
79+
# Add your base64_signer_key to the following in the config.yaml file.
80+
# The file path can be found by running the "supertokens --help" command
81+
82+
firebase_password_hashing_signer_key: "gRhC3eDeQOdyEn4bMd9c6kxguWVmcIVq/HbJKnCXdWscZx0l2WbCJ1wbg=="
83+
```
84+
85+
</SelfHostingTabs.TabItem>
86+
</SelfHostingTabs>
87+
88+
89+
90+
#### Step 3: SuperTokens requires firebase password hashes to be in a specific format to be parsed.
91+
92+
For example:
93+
94+
Your exported firebase user has the following credentials:
95+
```json
96+
{
97+
"users": [
98+
{
99+
"localId": "userId",
100+
"email": "[email protected]"
101+
"passwordHash": "9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==",
102+
"salt": "/cj0jC1br5o4+w==",
103+
}
104+
]
105+
}
106+
```
107+
108+
The memory cost, rounds and salt separator retrived from the password hashing config are:
109+
```json
110+
{
111+
mem_cost: 14,
112+
rounds: 8,
113+
base64_salt_separator: "Bw=="
114+
}
115+
```
116+
117+
The password hash would be the following: `$f_scrypt$9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==$/cj0jC1br5o4+w==$m=14$r=8$s=Bw==`
118+
119+
The example password hash is in the following format `$f_scrypt$<passwordHash>$<salt>$m=<mem_cost>$r=<rounds>$s=<base64_salt_separator>`
120+
121+
#### Step 4: Run the following `curl` command to import the user
122+
123+
```bash
124+
curl --location --request POST '^{coreInfo.uri}/recipe/user/passwordhash/import' \
125+
--header 'Content-Type: application/json; charset=utf-8' \
126+
--header 'api-key: ^{coreInfo.key}' \
127+
--data-raw '{
128+
"email": "[email protected]",
129+
"passwordHash": "$f_scrypt$9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==$/cj0jC1br5o4+w==$m=14$r=8$s=Bw==",
130+
"hashingAlgorithm": "firebase_scrypt"
131+
}'
132+
```
133+
134+
10135
## Passwordless Migration
11136

12137
To migrate a Passwordless user from your previous authentication provider to SuperTokens, you will first need to generate a code for the user and then call the consume code API.
@@ -77,3 +202,26 @@ curl --location --request PUT '^{coreInfo.uri}/recipe/user' \
77202
"phoneNumber": "+14155552671"
78203
}'
79204
```
205+
206+
207+
## ThirdParty Migration
208+
209+
To migrate users with social accounts we can simply call the SuperTokens Core's `signInUp` API with the provider Id and the user's third party userId.
210+
211+
For example:
212+
213+
If we were importing a user with Google as their provider with their third party userId being `106347997792363870000`, we can run the following curl command to import the user.
214+
215+
```bash
216+
curl --location --request POST '^{coreInfo.uri}/recipe/signinup' \
217+
--header 'api-key: ^{coreInfo.key}' \
218+
--header 'Content-Type: application/json; charset=utf-8' \
219+
--data-raw '{
220+
"thirdPartyId": "google",
221+
"thirdPartyUserId": "106347997792363870000",
222+
"email": {
223+
"id": "[email protected]",
224+
"isVerified": true
225+
}
226+
}'
227+
```

‎v3/docusaurus.config.ts

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,15 @@ const config: Config = {
105105
},
106106
prism: {
107107
theme: prismThemes.vsDark,
108-
additionalLanguages: ["kotlin", "java", "swift", "dart", "csharp", "php"],
108+
additionalLanguages: [
109+
"kotlin",
110+
"java",
111+
"swift",
112+
"dart",
113+
"csharp",
114+
"php",
115+
"bash",
116+
],
109117
},
110118
} satisfies Preset.ThemeConfig,
111119
plugins: [

0 commit comments

Comments
 (0)