How do I migrate my users from another vendor to Frontegg?

Hooray! We're happy you chose Frontegg and now it's time to migrate all of your users. 

Frontegg supports imports of Bcrypt, Scrypt and Firebase hashed passwords. If your previous authentication vendor had one of these hashing methods, you can import users easily with their passwords. If your vendor does not use any of these, after migrating the users they will be requested to reset their password (which is always a good practice). If you'd prefer to avoid friction as much as possible, you could use a passwordless authentication method in your application, instead of a password. For more details about the passwordless options with Frontegg, check the Going Passwordless section. 

The migration process can be performed via Frontegg APIs and requires obtaining a vendor JWT. Detailed steps on how to authenticate your environment and obtain a vendor JWT, can be found here.

Migrate Users from Auth0: 

1. Recreate the Tenants / Accounts you have on Auth0 using one of the methods mentioned on the last section of this article `Migrate Accounts in Bulks`.

2. On Auth0, go to the Applications > API section > System API:

3. Make sure that your management API has your application under Machine to Machine Applications:  

4. Your application on Auth0 will be required to have the following permissions: `read:users`, `read:user_idp_tokens`, `read:roles`. 

5. You can check the existing permissions via /api/v2/client-grants endpoint on Auth0. 

6. If any of these permissions are missing, make sure to update the grant via /api/v2/client-grants/{id} and use the id you've got from the previous GET request with the below payload: 

{"scope":[
      "read:users",
      "read:user_idp_tokens",
      "read:roles"
    ]}

7. Frontegg searches for the field that refers to the user's tenant on `app_metadata` or 'user_metadata`. 

8. Obtain your vendor JWT on Frontegg, per the instructions here. 

9. For the below raw user object:

{
    "email": "test@frontegg.com",
    "email_verified": true,
    "family_name": "Doe",
    "given_name": "John",
    "identities": [
        {
            "connection": "Username-Password-Authentication",
            "user_id": "xxxxx",
            "provider": "auth0",
            "isSocial": false
        }
    ],
    "name": "Frontegg Test",
    "user_id": "auth0|xxxxxxx",
    "username": "Test",
    "user_metadata": {},
    "app_metadata": {
        "tenant_id": "Frontegg_Test"
    }
}
 

10. Send a POST request to Migrate from Auth0 route with the following sample payload:

{
     "isTenantIdOnUserMetadata": false, 
     "domain": "https://[your-auth0-subdomain]",
     "clientId": "your-auth0-client-ID",
     "secret": "your-auth0-secret",
     "tenantIdFieldName": "tenant_id"
}

11. Below is the user object that will be created on Frontegg:

{
"id": "xxxxx",
"sub": "xxxxx",
"email": "test@frontegg.com",
"verified": null,
"name": "Frontegg Test",
"phoneNumber": null,
"profilePictureUrl": "xxx",
"provider": "local",
"mfaEnrolled": false,
"metadata": "{\"tenantIdFieldName\":\"Frontegg_Test\",\"auth0_id\":\"auth0|xxxxxxx\"}",
"tenantIds": ["Frontegg_Test"],
"tenantId": "Frontegg_Test",
"roles": [],
"permissions": [],
"createdAt": "2023-01-05T09:37:03.000Z",
"lastLogin": null,
"isLocked": false,
"tenants": [{
"tenantId": "Frontegg_Test",
"roles": []
}],
"managedBy": "frontegg",
"activatedForTenant": true
}

That's it! Frontegg will create a user and assign the user to the tenant with the same id that appears in tenant_id.

Migrate Users With Passwords:

1. Recreate the Tenants / Accounts you had before under the environment where you'd like to migrate the users, using one of the methods mentioned in the last section of this article `Migrate Accounts in Bulks`.

2. Obtain your vendor JWT on Frontegg, per the instructions here. 

3. Send a POST request to Migrate a vendor user route with one of the below options - 

For migrating users with Bcrypt passwords, send the below:

{
"name": "BCrypt Test User"
"metadata": "{\"Test\":\"Test\"}",
"verifyUser": true,
"email": "test@frontegg.com",
"tenantId": "Frontegg_Test",
"passwordHash": "hashed-password",
"passwordHashType": "bcrypt"
}

//metadata will be used as the user metadata on Frontegg, you can send an empty stringified object. 

{
"name": "SCrypt Test User",
"metadata": "{\"Test\":\"Test\"}",
"email": "test@frontegg.com",
"verifyUser": true,
"tenantId": "Frontegg_Test",
"passwordHash":"[salt-value];[hex-hashed-password]",
"passwordHashType": "scrypt",
"passwordHashConfig":"{\"saltSeparator\":\";\",\"N\":16384,\"r\":8,\"p\":1,\"keyLen\":64}"
}

//metadata will be used as the user metadata on Frontegg, you can send an empty stringified object. 

{ 
"name": "SCrypt Test User",
"metadata": "{\"Test\":\"Test\"}", 
"email": "test@frontegg.com",
"verifyUser": true, 
"tenantId": "Frontegg_Test", 
"passwordHash":"hashed-password", 
"passwordHashType": "firebase-scrypt", 
"passwordHashConfig":"{\"saltSeparator\":\";\",\"signerKey\":"",\"memCost\":14,\"rounds\":8}" 
}

//metadata will be used as the user metadata on Frontegg, you can send an empty stringified object. 

https://api.frontegg.com/identity/resources/migrations/v1/local/bulk

{
"users": [{
   "email": "aaa@frontegg.com",
   "tenantId": "123456"
}, {
   "email": "bbb@frontegg.com",
   "tenantId": "123456"
}, {
   "email": "ccc@frontegg.com",
   "tenantId": "123456"
}]
}

https://api.frontegg.com/identity/resources/migrations/v1/local/bulk/status/{{migration_id}}

https://api.frontegg.com/tenants/resources/migrations/v1/tenants

{
  "tenants": [{
   "tenantId": "your-tenant-id",
   "name": "Test_Tenant_1"
},
{
   "tenantId": "your-tenant-id",
   "name": "Test_Tenant_2"
},
{
  "tenantId": "your-tenant-id",
  "name": "Test_Tenant_3"
}]
}

https://api.frontegg.com/tenants/resources/migrations/v1/tenants/status/{{migrationId}}