Bulk User Import Database Schema and Examples
The users file must have an array with the users' information in JSON format.
User JSON schema
The following JSON schema describes valid users:
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "The user's email address.",
"format": "email"
},
"email_verified": {
"type": "boolean",
"default": false,
"description": "Indicates whether the user has verified their email address."
},
"user_id": {
"type": "string",
"description": "The user's unique identifier. This will be prepended by the connection strategy."
},
"username": {
"type": "string",
"description": "The user's username."
},
"given_name": {
"type": "string",
"description": "The user's given name."
},
"family_name": {
"type": "string",
"description": "The user's family name."
},
"name": {
"type": "string",
"description": "The user's full name."
},
"nickname": {
"type": "string",
"description": "The user's nickname."
},
"picture": {
"type": "string",
"description": "URL pointing to the user's profile picture."
},
"blocked": {
"type": "boolean",
"description": "Indicates whether the user has been blocked."
},
"password_hash": {
"type": "string",
"description": "Hashed password for the user. Passwords should be hashed using bcrypt $2a$ or $2b$ and have 10 saltRounds."
},
"custom_password_hash": {
"type": "object",
"description": "A more generic way to provide the users password hash. This can be used in lieu of the password_hash field when the users password hash was created with an alternate algorithm. Note that this field and password_hash are mutually exclusive.",
"properties": {
"algorithm": {
"type": "string",
"enum": [
"argon2",
"bcrypt",
"hmac",
"ldap",
"md4",
"md5",
"sha1",
"sha256",
"sha512",
"pbkdf2",
"scrypt"
],
"description": "The algorithm that was used to hash the password."
},
"hash": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "The password hash."
},
"encoding": {
"type": "string",
"enum": [
"base64",
"hex",
"utf8"
],
"description": "The encoding of the provided hash. Note that both upper and lower case hex variants are supported, as well as url-encoded base64."
},
"digest": {
"type": "string",
"description": "The algorithm that was used to generate the HMAC hash",
"enum": [
"md4",
"md5",
"ripemd160",
"sha1",
"sha224",
"sha256",
"sha384",
"sha512",
"whirlpool"
]
},
"key": {
"type": "object",
"description": "The key that was used to generate the HMAC hash",
"required": [
"value"
],
"properties": {
"value": {
"type": "string",
"description": "The key value"
},
"encoding": {
"type": "string",
"enum": [
"base64",
"hex",
"utf8"
],
"default": "utf8",
"description": "The key encoding"
}
}
}
}
},
"salt": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "The salt value used to generate the hash."
},
"encoding": {
"type": "string",
"enum": [
"base64",
"hex",
"utf8"
],
"default": "utf8",
"description": "The encoding of the provided salt. Note that both upper and lower case hex variants are supported, as well as url-encoded base64."
},
"position": {
"type": "string",
"enum": [
"prefix",
"suffix"
],
"default": "prefix",
"description": "The position of the salt when the hash was calculated. For example; MD5('salt' + 'password') = '67A1E09BB1F83F5007DC119C14D663AA' would have \"position\":\"prefix\"."
}
},
"required": [
"value"
]
},
"password": {
"type": "object",
"properties": {
"encoding": {
"type": "string",
"enum": [
"ascii",
"utf8",
"utf16le",
"ucs2",
"latin1",
"binary"
],
"default": "utf8",
"description": "The encoding of the password used to generate the hash. On login, the user-provided password will be transcoded from utf8 before being checked against the provided hash. For example; if your hash was generated from a ucs2 encoded string, then you would supply \"encoding\":\"ucs2\"."
}
}
},
"keylen" : {
"type": "integer",
"description": "Desired key length in bytes for the scrypt hash. Must be an integer greater than zero. Required when algorithm is set to scrypt."
},
"cost" : {
"type": "integer",
"default": 16384,
"description": "CPU/memory cost parameter used for the scrypt hash. Must be a power of two greater than one. Only used when algorithm is set to scrypt."
},
"blockSize" : {
"type": "integer",
"default": 8,
"description": "Block size parameter used for the scrypt hash. Must be a positive integer. Only used when algorithm is set to scrypt."
},
"parallelization" : {
"type": "integer",
"default": 1,
"description": "Parallelization parameter used for the scrypt hash. Must be a positive integer. Only used when algorithm is set to scrypt."
}
},
"required": [
"algorithm",
"hash"
],
"additionalProperties": false
},
"app_metadata": {
"type": "object",
"description": "Data related to the user that does affect the application's core functionality."
},
"user_metadata": {
"type": "object",
"description": "Data related to the user that does not affect the application's core functionality."
},
"mfa_factors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"totp": {
"type": "object",
"properties": {
"secret": {
"type": "string",
"pattern": "^[A-Z2-7]+$",
"description": "The OTP secret is used with authenticator apps (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass). It must be supplied in un-padded Base32 encoding, such as: JBTWY3DPEHPK3PNP"
}
},
"additionalProperties": false,
"required": [
"secret"
]
},
"phone": {
"type": "object",
"properties": {
"value": {
"type": "string",
"pattern": "^\\+[0-9]{1,15}$",
"description": "The phone number for SMS MFA. The phone number should include a country code and begin with +, such as: +12125550001"
}
},
"additionalProperties": false,
"required": [
"value"
]
},
"email": {
"type": "object",
"properties": {
"value": {
"type": "string",
"format": "email",
"description": "The email address for MFA"
}
},
"additionalProperties": false,
"required": [
"value"
]
}
},
"maxProperties": 1,
"additionalProperties": false
},
"minItems": 1,
"maxItems": 10
}
},
"required": [
"email"
],
"additionalProperties": false
}
Was this helpful?
To learn more about JSON schema, read jsonschema.org.
Properties
You can import users with the following properties:
Property | Type | Description | Upsert During Import? |
---|---|---|---|
app_metadata |
object | Data that can affect the application's core functionality or what the user can access. Data stored in app_metadata cannot be edited by users. This may include things such as support plans, roles or access groups. |
Yes |
blocked |
boolean | Indicates whether the user has been blocked. | No |
email |
string | The user's email address. | No |
email_verified |
boolean | Indicates whether the user has verified their email address. Set to false by default if email is updated by upsert but not email_verified . |
Yes |
family_name |
string | The user's family name. | Yes |
given_name |
string | The user's given name. | Yes |
name |
string | The user's full name. | Yes |
nickname |
string | The user's nickname. | Yes |
picture |
string | URL pointing to the user's profile picture. | Yes |
user_id |
string | The user's unique identifier. This will be prepended by the connection strategy. | No |
user_metadata |
object | Data that does not impact what users can or cannot access, such as work address, home address, or user preferences. | Yes |
username |
string | The user's username. | No |
password_hash |
string | Hashed password for the user's connection. When users are created, Auth0 uses bcrypt to secure the password. Importing hashed passwords lets users keep their passwords for a smoother experience. Compatible passwords should be hashed using bcrypt $2a$ or $2b$ and have 10 saltRounds. This property can only be provided when the user is first imported and cannot be updated later. | No |
custom_password_hash |
object | A more generic way to provide the user's password hash. This can be used instead of the password_hash field when the user's password hash was created with an alternate algorithm. During the bulk import process, you can update the custom_password_hash if the user did not login using the initially imported custom_password_hash . |
Yes |
mfa_factors |
array | The MFA factors that can be used to authenticate this user | No |
To learn more about app_metadata
and user_metadata
, read Understand How Metadata Works in User Profiles.
App metadata
The user.app_metadata
object must not contain any of these properties:
__tenant
_id
blocked
clientID
created_at
email_verified
email
globalClientID
global_client_id
identities
lastIP
lastLogin
loginsCount
metadata
multifactor_last_modified
multifactor
updated_at
user_id
Custom password hash
The user.custom_password_hash
object can be used instead of the user.password_hash
property when the user's password hash was created with an alternate algorithm. Note this field and password_hash
are mutually exclusive.
The user.custom_password_hash
object has the following properties:
Property | Type | Description |
---|---|---|
algorithm |
string | The algorithm used to hash the password. Must be one of:
|
hash |
object | |
hash.value |
string | The password hash. |
hash.encoding |
string | The encoding of the provided hash. Must be one of:
|
hash.digest |
string | The algorithm used to generate the HMAC hash. Must be one of:
|
hash.key |
object | The key used to generate the HMAC hash. |
hash.key.value |
string | The key value. |
hash.key.encoding |
string | The key encoding. Must be one of:
hash.key.encoding is utf8 . |
salt |
object | |
salt.value |
string | The salt value used to generate the hash. |
salt.encoding |
string | The encoding of the provided salt. Must be one of:
salt.encoding is utf8 . |
salt.position |
string | The position of the salt when the hash was calculated. By default, salt.position is prefix . |
password.encoding |
string | The encoding of the password used to generate the hash. Must be one of:
password.encoding before being checked against the provided hash. For example, if your hash was generated from a ucs2 encoded string, then you would set: "encoding": "ucs2" |
keylen |
integer | Desired key length in bytes for the scrypt hash. Must be an integer greater than zero. This parameter is required when algorithm is set to scrypt . |
cost |
integer | CPU/memory cost parameter used for the scrypt hash. Must be a power of two greater than one. By default, cost is 16384.This parameter is only used when algorithm is set to scrypt . |
blockSize |
integer | Block size parameter used for the scrypt hash. Must be a positive integer. By default, blockSize is 8.This parameter is only used when algorithm is set to scrypt . |
parallelization |
integer | Parallelization parameter used for the scrypt hash. Must be a positive integer. By default, parallelization is 1.This parameter is only used when algorithm is set to scrypt . |
Update custom password hash
During the bulk import process, you can update the custom_password_hash
if the user did not login using the initially imported custom_password_hash
. For example, you can submit the below JSON twice to the
/api/v2/jobs/users-imports
endpoint with different values for custom_password_hash
. On the second submit, send the upsert
flag to true
.
[
{
"user_id": "2000",
"email": "examplecouser20@gmail.com",
"given_name": "ExampleCo User",
"name" : "ExampleCoUser20",
"custom_password_hash": {
"algorithm": "bcrypt",
"hash": {
"value": "$2a$10$aHF7mbpWT6tZ7PJVtwtjNelaKbszikcYBCB2jibvbFcGFmOsu/s4K"
}
}
}
]
Was this helpful?
You can use the Bcrypt Password Generator at browserling.com to generate bcrypt password hashes.
Supported hash algorithms
Auth0 currently supports imports of user passwords hashed by:
Please consider the following sections when providing a custom_password_hash
.
Argon2
When the algorithm
is set to argon2
:
hash.encoding
must beutf8
.hash.salt
is not allowed.hash.value
must be in PHC string format, specified in P-H-C / phc-string-format on GitHub. It also must conform to the requirements specified in Auth0 / magic on GitHub.hash.value
must include the base64 encoded salt (as specified in thePHC
documentation).
bcrypt
When the algorithm
is set to bcrypt
:
hash.encoding
must beutf8
.hash.salt
is not allowed.hash.value
must include one of these prefixes:$2a$
$2b$
$2y$
Other prefixes, such as
$2$
,$sha1$
, and$2x$
, are not supported at this time.
For example, this was generated from the string hello
using a cost parameter of 10:
$2b$10$nFguVi9LsCAcvTZFKQlRKeLVydo8ETv483lkNsSFI/Wl1Rz1Ypo1K
HMAC
When the algorithm
is set to hmac
:
hash.encoding
must be eitherhex
orbase64
.hash.digest
is required and must be one of these:md4
md5
ripemd160
sha1
sha224
sha256
sha384
sha512
whirlpool
hash.key.value
is required.hash.key.encoding
must be eitherbase64
orhex
orutf8
.
LDAP
When the algorithm
is set to ldap
:
hash.encoding
must beutf8
.salt
is not allowed.hash.value
must adhere to the format outlined in RFC-2307 section-5.3 on IETF Datatracker.The scheme should be one of
md5|smd5|sha*|ssha*
see here for more info.Note that the crypt scheme is not supported due to system/implementation dependent behavior. To learn more, read Open LDAP Admin Guide - 14.4.2. CRYPT password storage scheme.
MD or SHA
When the algorithm
is set to md4
, md5
, sha1
, sha256
, or sha512
:
hash.encoding
must be eitherhex
orbase64
.
PBKDF2
When the algorithm
is set to pbkdf2
:
hash.encoding
must beutf8
.hash.salt
is not allowed.hash.value
should be in PHC string format, specified in P-H-C / phc-string-format on GitHub.hash.value
must include the B64 encoded salt (base64 omitting padding characters=
, as specified in thePHC
documentation).hash.value
should includei
(iterations) andl
(keylen) parameters. If these parameters are omitted, they will default toi=100000
andl=64
.The
id
should be in apbkdf2-<digest>
format (pbkdf2-sha512
,pbkdf2-md5
, etc). The supported digests are:RSA-MD4
RSA-MD5
RSA-MDC2
RSA-RIPEMD160
RSA-SHA1
RSA-SHA1-2
RSA-SHA224
RSA-SHA256
RSA-SHA384
RSA-SHA512
md4
md4WithRSAEncryption
md5
md5WithRSAEncryption
mdc2
mdc2WithRSA
ripemd
ripemd160
ripemd160WithRSA
rmd160
sha1
sha1WithRSAEncryption
sha224
sha224WithRSAEncryption
sha256
sha256WithRSAEncryption
sha384
sha384WithRSAEncryption
sha512
sha512WithRSAEncryption
ssl3-md5
ssl3-sha1
whirlpool
scrypt
When the algorithm
is set to scrypt
:
hash.encoding
must be eitherhex
orbase64
.keylen
parameter is required.cost
parameter can be specified; if not, it will default to 16384.blockSize
parameter can be specified; if not, it will default to 8.parallelization
parameter can be specified; if not, it will default to 1.
MFA factors
The user.mfa_factors
array contains MFA enrollments for the user. To learn more, read Multi-Factor Authentication in Auth0. Importing enrollments prevents the need for users to re-enroll in MFA after they're imported. The supported enrollment types are:
Property | Type | Description |
---|---|---|
email |
object | |
email.value |
string | The email address for MFA. |
phone |
object | |
phone.value |
string | The phone number for SMS MFA. Must have a country code and begin with + , such as: "+12125550001" |
totp |
object | |
totp.secret |
string | The OTP secret for MFA authentication with authenticator apps (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass). Must be in un-padded Base32 encoding, for example: "JBTWY3DPEHPK3PNP" |
Examples
Basic example
A file with the following contents is valid:
[
{
"email": "john.doe@contoso.com",
"email_verified": false,
"app_metadata": {
"roles": ["admin"],
"plan": "premium"
},
"user_metadata": {
"theme": "light"
}
}
]
Was this helpful?
Custom password hash examples
Some example users with hashes provided:
[
{
"email": "antoinette@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "md4",
"hash": {
"value": "AbuUujgF0pPPkJPSFRTpmA==",
"encoding": "base64"
}
}
},
{
"email": "mary@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "sha256",
"hash": {
"value": "d24e794fce503c3ddb1cd1ba1dd5d9b250cf9917336a0316fefd87fecf79200f",
"encoding": "hex"
},
"salt": {
"value": "abc123",
"position": "prefix"
}
}
},
{
"email": "velma@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "bcrypt",
"hash": {
"value": "$2b$10$C9hB01.YxRSTcn/ZOOo4j.TW7xCKKFKBSF.C7E0xiUwumqIDqWUXG"
}
}
},
{
"email": "edward@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "argon2",
"hash": {
"value": "$argon2id$v=19$m=65536,t=2,p=1$J6Q/82PCyaNpYKRELJyTZg$m04qUAB8rexWDR4+/0f+SFB+4XMFxt7YAvAq2UycYos"
}
}
},
{
"email": "terrell@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "pbkdf2",
"hash": {
"value": "$pbkdf2-md4$i=100000,l=64$+N375B8q0Fw$fp2R9KAM4hK/votGHC5Fu+jhqbxUD8+Nic/EMSGvNC3UP/k7wSHI0uXluHRSkZfl/BOheYqNOemayG90ZaSSQw",
"encoding": "utf8"
}
}
},
{
"email": "cecil@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "pbkdf2",
"hash": {
"value": "$pbkdf2-sha512$i=100000,l=64$KNyFsA2rWoE$I2CQGI9H0JxdDf3kERRI97kPCGxh0KWBIV3MxyaS191gDGfzVBGyS4BibhgqWQ0/ails8mHuU9ckASxHOOq58w"
}
}
},
{
"email": "sean@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "ldap",
"hash": {
"value": "{SSHA384}/cgEjdoZh85DhurDeOQEMO1rMlAur93SVPbYe5XSD4lF7nNuvrBju5hUeg9A6agRemgSXGl5YuE=",
"encoding": "utf8"
}
}
},
{
"email": "peter@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "hmac",
"hash": {
"value": "cg7f42jH39/2EaAU4wNd4s2lKIk=",
"encoding": "base64",
"digest": "sha1",
"key": {
"value": "736868",
"encoding": "hex"
}
}
}
},
{
"email": "carmella@contoso.com",
"email_verified": false,
"custom_password_hash": {
"algorithm": "scrypt",
"hash": {
"value": "097f6197e1b41538f723e32aa7a68e8d76227d8e432ce5faa4882a913032db29",
"encoding": "hex"
},
"salt": {
"value": "abc123",
"encoding": "utf8"
},
"keylen": 32,
"cost": 4096
}
}
]
Was this helpful?
MFA factors examples
As you might expect, the user.mfa_factors
array allows you to provide the user's MFA enrollments. The supported enrollment types are:
Phone: Used for sms-based verification.
TOTP: OTP secret for use with MFA type apps (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass).
Email: Used for email-based verification.
Some examples of users with MFA factors:
[
{
"email": "antoinette@contoso.com",
"mfa_factors": [
{
"totp": {
"secret": "2PRXZWZAYYDAWCD"
}
},
{
"phone": {
"value": "+15551112233"
}
},
{
"email": {
"value": "antoinette@antoinette.biz"
}
}
]
},
{
"email": "mary@contoso.com",
"mfa_factors": [
{
"totp": {
"secret": "JBTWY3DPEHPK3PNP"
}
}
]
},
{
"email": "velma@contoso.com",
"mfa_factors": [
{
"phone": {
"value": "+15551234567"
}
},
]
},
{
"email": "edward@contoso.com",
"mfa_factors": [
{
"email": {
"value": "edward@edward.biz"
}
}
]
}
]
Was this helpful?