Custom Data Store

Migrating your users from a custom data store to Descope can be straightforward with the right preparation and tools. This guide will cover everything you need to know about exporting your user data and importing it into Descope using our User Management API.

Preparing for Migration

Exporting User Data

Start by ensuring your user data is accessible for import. This often means exporting your data to a format like CSV or JSON. The key information you'll need includes:

• Login ID (Required): The unique identifier for authentication.
• Email: Optional, but recommended for communication.
• First and Last Name: Optional, for personalization.
• Password: Optional, for importing existing password hashes.

Verifying Data Accessibility

Ensure you can programmatically access the exported data, either directly from your data source or from the exported file.

Creating Users

Utilize the Descope Create User API or Batch Create User API to import each user. This will create a matching record for each user within Descope.

A successful response will include the creation fields, along with a new userId, which you can persist in your data store if desired.

{
  "user": {
    "loginIds": [
      "asdfafw3e"
    ],
    "userId": "U2beSnHc1GhgIw7TscMfj5ASG",
    "name": "",
    "email": "test10@gmail.com",
    "phone": "",
    "verifiedEmail": true,
    "verifiedPhone": false,
    "roleNames": [],
    "userTenants": [],
    "status": "invited",
    "externalIds": [
      "asdfafw3e"
    ],
    "picture": "",
    "test": false,
    "customAttributes": {},
    "createdTime": 1706574216,
    "TOTP": false,
    "SAML": false,
    "OAuth": {},
    "webauthn": false,
    "password": true,
    "ssoAppIds": [],
    "givenName": "",
    "middleName": "",
    "familyName": ""
  }
}

Importing Passwords

If your application users currently have password-based authentication, you can use our Management APIs to migrate over their pre-existing passwords, in either plaintext or hashed form.

When using the Create User API, Descope will create a hash comparison based on your hash, salt, and iterations. Hashed passwords can be migrated to Descope if they are using bcrypt, django, firebase, or pbkdf2.

This is what the password section of the JSON will look like in the API request body:

"password": "string",
// or
"hashedPassword": {
  // Whatever algorithm that you're currently using, code snippets for specific algorithms are documented below
},

By importing passwords this way, users will be able to sign in with their existing password without having to go through a password reset flow.

Password Algorithms

Descope supports migrating hashed passwords using several algorithms. Here’s a quick list of each supported algorithm with links to the full details below:

1. Bcrypt - Secure, adaptive hashing algorithm with increasing iterations.
2. Django - Designed for Django applications with built-in security.
3. Firebase - Specific hashing configuration for Firebase Authentication.
4. PBKDF2 - Key derivation function suitable for security-focused applications.
5. PHPass - A framework for PHP applications using multiple hashing methods.
6. MD5 - Legacy algorithm, supported for backward compatibility.

Let's explore the details and use-cases for each supported algorithm:

1. Bcrypt

• Use Case: Commonly used for secure password hashing. It's resilient against brute-force attacks due to its adaptive nature, which allows the number of iterations (work factor) to be increased as hardware becomes more powerful.
• Parameters:
  • hash: The bcrypt hash string.

"hashedPassword": {
  "bcrypt": {
    "hash": "string"
  },
}

2. Django

• Use Case: Designed for Django applications, this option allows for seamless migration from Django's authentication system to Descope.
• Parameters:
  • hash: The entire hash string as stored in the Django application. Django typically combines the algorithm, iterations, salt, and hash in one string.

"hashedPassword": {
  "django": {
    "hash": "string"
  }
},

3. Firebase

• Use Case: Suitable for migrating users from Firebase authentication, accommodating its specific hashing configurations.
• Parameters:
  • hash: The hash value of the password.
  • salt: Salt value used along with the hash.
  • saltSeparator: A separator used in Firebase's hashing strategy to distinguish between salt and password.
  • signerKey: Key used for additional security during the hashing process.
  • memory: Specifies the amount of memory used for hashing (relevant for some advanced hashing algorithms like Argon2, though not typically used in Firebase's default settings).
  • rounds: The number of hashing iterations.

"hashedPassword": {
  "firebase": {
    "hash": "string",
    "salt": "string",
    "saltSeparator": "string",
    "signerKey": "string",
    "memory": 0,
    "rounds": 0
  }
},

4. PBKDF2

• Use Case: A widely used algorithm that applies a pseudorandom function to derive keys. The number of iterations can be configured to increase the difficulty of deriving keys, enhancing security.
• Parameters:
  • hash: The hash value of the password.
  • salt: Salt value used along with the hash.
  • iterations: The number of iterations the algorithm runs, increasing the time it takes to compute the hash.
  • type: The type of pseudorandom function used (e.g., HMAC-SHA256).

"hashedPassword": {
  "pbkdf2": {
    "hash": "string",
    "salt": "string",
    "iterations": 0,
    "type": "string"
  }
},

5. PHPass

• Use Case: PHPass (PHP Password Hashing Framework) is a portable password hashing framework for PHP applications. It is designed to be secure, using multiple hashing algorithms and iterating over the password to increase security against brute-force attacks.
• Parameters:
  • hash: The hashed value of the password.
  • salt: Salt value used along with the hash.
  • iterations: The number of iterations the algorithm runs, increasing the time it takes to compute the hash.
  • type: The hash format (md5, sha512)

"hashedPassword": {
  "phpass": {
    "hash": "string",
    "salt": "string",
    "iterations": 0,
    "type": "sha512"
  }
}

6. MD5

• Use Case: MD5 (Message-Digest Algorithm) is a widely known cryptographic hash function that was once commonly used to hash passwords. However, due to vulnerabilities, it is no longer considered secure for password hashing. While it is generally discouraged for use in new applications, MD5 might still be found in legacy systems. Descope supports migration of MD5-hashed passwords to allow seamless user transitions during system upgrades.
• Parameters:
  • hash: The hashed value of the password.

"hashedPassword": {
  "md5": {
    "hash": "string"
  }
}

Migration Strategy

• Assessment: Review the current hashing algorithms and parameters used in your existing system.
• Compatibility Check: Ensure the new system supports all features of the old system's hashing mechanisms.
• User Transparency: Migrate hashes without requiring users to reset their passwords, ensuring a seamless transition.

By understanding these parameters and their implications, you can plan an effective password migration strategy that maintains security standards and minimizes user disruption. This approach ensures that the new system respects existing security measures while potentially enhancing them.

Triggering password resets

If user passwords can't be exported, we can trigger password resets. This can happen at any time, not necessarily when the import is happening. It could simply be part of a login flow-after a user inputs their email, they get a password reset message to their inbox.

Social Login

After migrating user Login IDs, social login will work just as previously, no other importing required.

Handling user signups during migrations

You'll want to consider scheduling the migration to occur at a time where user activity is minimal. One option is to disable sign up while the migration is occurring. This way all users will be captured. To prevent downtime, you can implement user syncing between Descope and your future sign ups. This way, you can simply migrate the previous users and new users who sign up during the migration will already exist. This adds complexity into the process as you'll have to account for edge cases: What if an existing user updates their email, password, etc. during the migration?

Example

Check out an example migration script here.