Bulk migration via API

Frontegg supports importing users with their passwords hashed with Bcrypt, Scrypt, and Firebase, making user migration from a previous authentication vendor simple. If another hashing method was used, Frontegg prompts users to reset their passwords, ensuring a secure transition.

To minimize friction and enhance user experience, Frontegg offers passwordless authentication, eliminating the need for traditional passwords for a secure and convenient login.

Migrating users to your Frontegg account is done via API and therefore requires the acquisition of a vendor JWT (JSON Web Token). Detailed steps on how to authenticate your environment and obtain a vendor JWT can be found here.

Migration with multi-apps

Please note that automatic migration of users to different applications is not available. When migrating users, ensure that there is at least one default or auto-assigned application. If you need to segment user assignments across applications, you can assign users to their specific applications via this API after the migration.

Migrating users from Auth0

To migrate users from Auth0:

Recreate your Tenants / Accounts on Auth0 using one of the methods mentioned in the Migrate Accounts below. In Auth0, go to Applications → API section → System API:

Auth0 requirements and prerequisites

• Your Auth0 application will need to possess the following permissions: read:users, read:user_idp_tokens, read:roles. Check for your existing permissions via the /api/v2/client-grants endpoint on Auth0.
• Ensure your management API has your application listed under Machine to Machine Applications.
• If any of these permissions are missing, make sure to update the grant via /api/v2/client-grants/{id} and use the ID received from the previous GET request with the following payload:

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

Migrate a user with the below object:

{  
    "email": "[test@frontegg.com](mailto: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"  
    }  
}

Send a POST request to the 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"  
}

The following user object will be created on Frontegg:

{  
"id": "xxxxx",  
"sub": "xxxxx",  
"email": "[test@frontegg.com](mailto: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 under the tenant_id field.

Migrating users with passwords

Recreate the Tenants / Accounts previously had within the environment you'd like to migrate the users to (use one of the methods mentioned in the Migrate Accounts section in this topic).

Obtain your environment token on Frontegg, per the instructions here.

Send a POST request to Migrate a vendor user route with one of the below options, using the migrate single user endpoint or the bulk.

Bcrypt

To migrate users with Bcrypt passwords, send the following payload:

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

Scrypt

To migrate users with Scrypt passwords, send the following payload

{  
"name": "SCrypt Test User",  
"metadata": "{\"Test\":\"Test\"}",  
"email": "[test@frontegg.com](mailto: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}"  
}

Note that metadata will be used as the user metadata in Frontegg. You can also send an empty stringified object.

Firebase

{  
"name": "Firebase 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}"  
}

pbkdf2

To migrate users with pbkdf2, send the following payload:

{  
"name": "pbkdf2 Test User",  
"metadata": "{\"Test\":\"Test\"}",  
"email": "[test@frontegg.com]",  
"verifyUser": true,  
"tenantId": "Frontegg_Test",  
"passwordHash":"[salt-phrase];[hashed-password]", 
"passwordHashType": "pbkdf2",  
"passwordHashConfig":"{\"saltSeparator\":\";\",\"iterations\":1000,\"keyLen\":32,\"digest\":\"sha256\"}"  
}

Keycloak

To migrate users with pbkdf2 from Keycloak, send the following payload:

{
"name": "Keycloak pbkdf2 Test User",
"provider": "local",
"verifyUser": true,
"email": "[test@frontegg.com]",
"tenantId": "Frontegg_Test",
"passwordHash": "[salt-phrase];[base64-hashed-password]",
"passwordHashType": "pbkdf2",
"passwordHashConfig": "{\"saltSeparator\":\";\",\"iterations\":27500,\"keyLen\":32,\"digest\":\"sha256\", \"keyEncodingType\":\"base64\", \"keyEncodingType\":\"base64\"}"
 // change iterations, keyLen, according to what is provided by Keycloak export
}

Migrating users with phone numbers

To migrate users with their phone numbers for SMS login or MFA, add their phone number along with the designated authentication type. Please note that SMS cannot be used simultaneously as both an MFA method and a login method. Once migrated, the user will be able to either login via SMS, or will promoted to MFA via SMS, depending on the chosen phoneNumberType method.

curl -i -X POST \
  https://api.frontegg.com/identity/resources/migrations/v1/local \
  -H 'Authorization: Bearer VENDOR-JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "string",
    "provider": "local",
    "metadata": "string",
    "vendorMetadata": "string",
    "verifyUser": true,
    "roleIds": [],
    "email": "string",
    "tenantId": "string",
    "name": "string",
    "authenticatorAppMfaSecret": "string",
    "phoneNumberType": "auth" / "mfa"
  }'

Migrating users in bulk

Frontegg's Bulk Migration API allows you to migrate users to tenants in batches of up to 1000 users. The bulk migration endpoint supports all the attributes that are supported in the single user migration endpoint.

1. Recreate the Tenants / Accounts previously had within the environment you'd like to migrate the users to (use one of the methods mentioned in the Migrate Accounts section in this topic). You can use this API to create accounts in bulk.

2. To migrate users in batches of 1000 at a time, send an Authorization POST request with your environment token to the migrate users in bulk endpoint. The payload of the users' data can contain any of the attributes mentioned in the single-user migration examples mentioned in the Migrating Users Using Passwords section.

curl --location --request POST '<https://api.frontegg.com/identity/resources/migrations/v1/local/bulk>' \
--header 'Authorization: Bearer VENDOR-JWT' \
--header 'Content-Type: application/json' \
--data-raw '{  
    "users": [{  
       "email": "aaa@frontegg.com",  
       "tenantId": "123456"  
    }, {  
       "email": "bbb@frontegg.com",  
       "tenantId": "123456"  
    }, {  
       "email": "ccc@frontegg.com",  
       "tenantId": "123456"  
    }]  
    }'

In the response, you will get a migrationId. Use this id to monitor the status of the migration, by sending a GET request to the dedicated endpoint.

Migrating accounts

To migrate accounts to Frontegg, go to the environment you'd like to create your new accounts under; then, choose to either recreate tenants via your backoffice or via the tenant creation API. Alternatively, you can Migrate Accounts in Bulk as indicated in the next section:

• Recreate tenants using the Backoffice UI - Use the same Tenant ID that you have for a different vendor and insert it under the ID field.

• Recreate Tenants via API - Use tenant creation API, or the bulk tenant migration API and make sure to set your previous tenant ID as the tenantId property.

The tenant migration API allows you to migrate tenants in batches of 1000 tenants per batch and in the response, you will get a migrationId. Use this id to monitor the status of the migration by sending a GET request to the dedicated endpoint.