Esquema y ejemplos de importación masiva de usuarios

Aprenda a realizar importaciones masivas de usuarios con Management API.

El archivo de usuarios debe contener un arreglo con la información de los usuarios en formato JSON.

El límite de tamaño de archivo para una importación masiva es de 500 KB. Deberá iniciar varias importaciones si sus datos superan ese tamaño.

​

Esquema JSON de usuario

El siguiente esquema JSON describe los usuarios válidos:

{
  "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: [phone]"
              }
            },
            "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
}

Para obtener más información sobre esquema JSON, consulta jsonschema.org.

​

Propiedades

Puede importar usuarios con las siguientes propiedades:

Propiedad	Tipo	Descripción	¿Upsert durante la importación?
app_metadata	object	Datos que pueden afectar la funcionalidad principal de la aplicación o aquello a lo que el usuario puede acceder. Los datos almacenados en app_metadata no pueden ser editados por los usuarios. Esto puede incluir elementos como planes de soporte, roles o grupos de acceso.	Sí
blocked	boolean	Indica si el usuario ha sido bloqueado.	No
email	string	La dirección de correo electrónico del usuario.	No
email_verified	boolean	Indica si el usuario ha verificado su dirección de correo electrónico. Se establece en false de forma predeterminada si email se actualiza mediante upsert, pero no email_verified.	Sí
family_name	string	El apellido del usuario.	Sí
given_name	string	El nombre de pila del usuario.	Sí
name	string	El nombre completo del usuario.	Sí
nickname	string	El apodo del usuario.	Sí
picture	string	URL que apunta a la foto de perfil del usuario.	Sí
user_id	string	El identificador único del usuario. La estrategia de la conexión se antepondrá a este valor.	No
user_metadata	object	Datos que no afectan a aquello a lo que los usuarios pueden o no acceder, como la dirección del trabajo, la dirección del hogar o las preferencias del usuario.	Sí
username	string	El username del usuario.	No
password_hash	string	Hash de contraseña para la conexión del usuario. Cuando se crean usuarios, Auth0 usa bcrypt para proteger la contraseña. Importar contraseñas con hash permite que los usuarios conserven sus contraseñas para disfrutar de una experiencia más fluida. Las contraseñas compatibles deben tener hash con bcrypt $2a$ o $2b$ y 10 saltRounds. Esta propiedad solo se puede proporcionar cuando el usuario se importa por primera vez y no se puede actualizar después.	No
custom_password_hash	object	Una forma más genérica de proporcionar el hash de contraseña del usuario. Puede usarse en lugar del campo password_hash cuando el hash de contraseña del usuario se creó con un algoritmo alternativo. Durante el proceso de importación masiva, puede actualizar custom_password_hash si el usuario no inició sesión con el custom_password_hash importado inicialmente.	Sí
mfa_factors	array	Los factores de MFA que pueden usarse para autenticar a este usuario	No

Para obtener más información sobre app_metadata y user_metadata, lea Comprender cómo funcionan los metadatos en los perfiles de usuario.

​

Metadatos de la aplicación

El objeto user.app_metadata no debe contener ninguna de estas propiedades:

• __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

​

Hash de contraseña personalizado

El objeto user.custom_password_hash se puede usar en lugar de la propiedad user.password_hash cuando el hash de contraseña del usuario se creó con un algoritmo distinto. Tenga en cuenta que este campo y password_hash son mutuamente excluyentes.

El objeto user.custom_password_hash tiene las siguientes propiedades:

Propiedad	Tipo	Descripción
algorithm	string	El algoritmo utilizado para generar el hash de la contraseña. Debe ser uno de los siguientes: argon2 bcrypt hmac ldap md4 md5 sha1 sha256 sha512 pbkdf2 scrypt
hash	object
hash.value	string	El hash de la contraseña.
hash.encoding	string	La codificación del hash proporcionado. Debe ser una de las siguientes: base64 hex utf8 Se admiten variantes hexadecimales en mayúsculas y minúsculas, así como base64 codificado para URL.
hash.digest	string	El algoritmo utilizado para generar el hash HMAC. Debe ser uno de los siguientes: md4 md5 ripemd160 sha1 sha224 sha256 sha384 sha512 whirlpool
hash.key	object	La clave utilizada para generar el hash HMAC.
hash.key.value	string	El valor de la clave.
hash.key.encoding	string	La codificación de la clave. Debe ser una de las siguientes: base64 hex utf8 De forma predeterminada, hash.key.encoding es utf8.
salt	object
salt.value	string	El valor de la sal utilizada para generar el hash.
salt.encoding	string	La codificación de la sal proporcionada. Debe ser una de las siguientes: base64 hex utf8 Se admiten variantes hexadecimales en mayúsculas y minúsculas, así como base64 codificado para URL. De forma predeterminada, salt.encoding es utf8.
salt.position	string	La posición de la sal cuando se calculó el hash. De forma predeterminada, salt.position es prefix.
password.encoding	string	La codificación de la contraseña utilizada para generar el hash. Debe ser una de las siguientes: ascii utf8 utf16le ucs2 latin1 binary Al iniciar sesión, la contraseña proporcionada por el usuario se transcodificará desde password.encoding antes de comprobarse con el hash proporcionado. Por ejemplo, si su hash se generó a partir de una cadena codificada en ucs2, debe establecer lo siguiente: "encoding": "ucs2"
keylen	integer	Longitud de clave deseada en bytes para el hash scrypt. Debe ser un entero mayor que cero. Este parámetro es obligatorio cuando algorithm se establece en scrypt.
cost	integer	Parámetro de costo de CPU/memoria utilizado para el hash scrypt. Debe ser una potencia de dos mayor que uno. De forma predeterminada, cost es 16384. Este parámetro solo se usa cuando algorithm se establece en scrypt.
blockSize	integer	Parámetro de tamaño de bloque utilizado para el hash scrypt. Debe ser un entero positivo. De forma predeterminada, blockSize es 8. Este parámetro solo se usa cuando algorithm se establece en scrypt.
parallelization	integer	Parámetro de paralelización utilizado para el hash scrypt. Debe ser un entero positivo. De forma predeterminada, parallelization es 1. Este parámetro solo se usa cuando algorithm se establece en scrypt.

​

Actualizar el hash de contraseña personalizado

Durante el proceso de importación masiva, puedes actualizar custom_password_hash si el usuario no inició sesión con el custom_password_hash importado inicialmente. Por ejemplo, puedes enviar el siguiente JSON dos veces al endpoint /api/v2/jobs/users-imports con valores diferentes para custom_password_hash. En el segundo envío, establece la marca upsert en true.

[
    {
    	"user_id": "2000",
        "email": "[e-mail]",
        "given_name": "ExampleCo User",
        "name" : "ExampleCoUser20",
        "custom_password_hash": {
            "algorithm": "bcrypt",
            "hash": {
                "value": "$2a$10$aHF7mbpWT6tZ7PJVtwtjNelaKbszikcYBCB2jibvbFcGFmOsu/s4K"
            }
        }
    }
]

Puede usar el Bcrypt Password Generator de browserling.com para generar hashes bcrypt de contraseñas.

​

Algoritmos hash compatibles

Actualmente, Auth0 admite la importación de contraseñas de usuario con hash generado mediante:

• Argon2
• bcrypt
• LDAP (RFC-2307 "userPassword")
• HMAC
• MD4
• MD5
• SHA1
• SHA256 y SHA512
• PBKDF2
• scrypt

Tenga en cuenta las siguientes secciones al proporcionar un custom_password_hash.

​

Argon2

Cuando algorithm está establecido en argon2:

• hash.encoding debe ser utf8.
• hash.salt no está permitido.
• hash.value debe estar en formato de cadena PHC, como se especifica en P-H-C / phc-string-format en GitHub. También debe cumplir con los requisitos especificados en Auth0 / magic en GitHub.
• hash.value debe incluir la sal codificada en base64 (como se especifica en la documentación de PHC).

​

bcrypt

Cuando algorithm se establece en bcrypt:

• hash.encoding debe ser utf8.

• hash.salt se puede usar junto con la codificación y la posición de la sal.

• hash.value debe incluir uno de estos prefijos:

  • $2a$
  • $2b$
  • $2y$

  Otros prefijos, como $2$, $sha1$ y $2x$, no son compatibles en este momento.

Por ejemplo, el siguiente valor se generó a partir de la cadena hello con un factor de coste de 10:

$2b$10$nFguVi9LsCAcvTZFKQlRKeLVydo8ETv483lkNsSFI/Wl1Rz1Ypo1K

El algoritmo bcrypt procesa un máximo de 72 bytes de entrada al calcular hashes de contraseñas o realizar comparaciones, y la longitud de salt.value cuenta para el límite de entrada de 72 bytes. Cualquier entrada que supere el límite de 72 bytes se trunca; por ejemplo, si la sal consume 10 bytes, la longitud máxima de la contraseña para el cálculo del hash o la comparación es de 62 bytes.

Las contraseñas que superan ese límite reducido se truncan, lo que puede debilitar la seguridad de la contraseña o provocar colisiones de hash. Valide siempre la longitud de las contraseñas antes de generar el hash.

​

HMAC

Cuando algorithm está configurado como hmac:

• hash.encoding debe ser hex o base64.

• hash.digest es obligatorio y debe ser uno de los siguientes:

  • md4
  • md5
  • ripemd160
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512
  • whirlpool

• hash.key.value es obligatorio.

• hash.key.encoding debe ser base64, hex o utf8.

​

LDAP

Cuando algorithm está establecido en ldap:

• hash.encoding debe ser utf8.
• salt no está permitido.
• hash.value debe ajustarse al formato descrito en la sección 5.3 de RFC-2307 en IETF Datatracker.
• El esquema debe ser uno de md5|smd5|sha*|ssha*; consulta aquí para obtener más información.
• Ten en cuenta que el esquema crypt no es compatible debido a un comportamiento que depende del sistema o de la implementación. Para obtener más información, consulta Open LDAP Admin Guide - 14.4.2. CRYPT password storage scheme.

​

MD o SHA

Cuando algorithm está configurado como md4, md5, sha1, sha256 o sha512:

• hash.encoding debe ser hex o base64.

​

PBKDF2

Cuando algorithm se establece en pbkdf2:

• hash.encoding debe ser utf8.

• hash.salt no está permitido.

• hash.value debe estar en formato de cadena PHC, como se especifica en P-H-C / phc-string-format en GitHub.

• hash.value debe incluir la sal codificada en B64 (base64 sin los caracteres de relleno =, como se especifica en la documentación de PHC).

• hash.value debería incluir los parámetros i (iteraciones) y l (keylen). Si se omiten estos parámetros, se usarán los valores predeterminados i=100000 y l=64.

• El id debe tener el formato pbkdf2-<digest> (pbkdf2-sha512, pbkdf2-md5, etc.). Los algoritmos de resumen compatibles son:

  • 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

Cuando algorithm está establecido en scrypt:

• hash.encoding debe ser hex o base64.
• El parámetro keylen es obligatorio.
• Se puede especificar el parámetro cost; si no se especifica, el valor predeterminado será 16384.
• Se puede especificar el parámetro blockSize; si no se especifica, el valor predeterminado será 8.
• Se puede especificar el parámetro parallelization; si no se especifica, el valor predeterminado será 1.

​

Factores de MFA

El array user.mfa_factors contiene las inscripciones de MFA del usuario. Para obtener más información, consulte Autenticación multifactor en Auth0. Importar las inscripciones evita que los usuarios tengan que volver a inscribirse en MFA después de importarlos. Los tipos de inscripción admitidos son:

Propiedad	Tipo	Descripción
email	object
email.value	string	La dirección de correo electrónico para MFA.
phone	object
phone.value	string	El número de teléfono para MFA por SMS. Debe incluir un código de país y comenzar con +, por ejemplo: "[phone]"
totp	object
totp.secret	string	El secreto de OTP para la autenticación MFA con aplicaciones de autenticación (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass). Debe estar en codificación Base32 sin relleno, por ejemplo: "JBTWY3DPEHPK3PNP"

​

Ejemplos

​

Ejemplo básico

Un archivo con el contenido siguiente es válido:

[
  {
    "email": "[e-mail]",
    "email_verified": false,
    "app_metadata": {
        "roles": ["admin"],
        "plan": "premium"
    },
    "user_metadata": {
        "theme": "light"
    }
  }
]

​

Ejemplos de hashes de contraseñas personalizados

Algunos usuarios de ejemplo con los hashes proporcionados:

[
    {
        "email": "[e-mail]",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "md4",
            "hash": {
                "value": "AbuUujgF0pPPkJPSFRTpmA==",
                "encoding": "base64"
            }
        }
    },
    {
        "email": "[e-mail]",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "sha256",
            "hash": {
                "value": "d24e794fce503c3ddb1cd1ba1dd5d9b250cf9917336a0316fefd87fecf79200f",
                "encoding": "hex"
            },
            "salt": {
                "value": "abc123",
                "position": "prefix"
            }
        }
    },
    {
        "email": "[e-mail]",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "bcrypt",
            "hash": {
                "value": "$2b$10$C9hB01.YxRSTcn/ZOOo4j.TW7xCKKFKBSF.C7E0xiUwumqIDqWUXG"
            }
        }
    },
    {
        "email": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "pbkdf2",
            "hash": {
                "value": "$pbkdf2-sha512$i=100000,l=64$KNyFsA2rWoE$I2CQGI9H0JxdDf3kERRI97kPCGxh0KWBIV3MxyaS191gDGfzVBGyS4BibhgqWQ0/ails8mHuU9ckASxHOOq58w"
            }
        }
    },
    {
        "email": "[e-mail]",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "ldap",
            "hash": {
                "value": "{SSHA384}/cgEjdoZh85DhurDeOQEMO1rMlAur93SVPbYe5XSD4lF7nNuvrBju5hUeg9A6agRemgSXGl5YuE=",
                "encoding": "utf8"
            }
        }
    },
    {
        "email": "[e-mail]",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "hmac",
            "hash": {
                "value": "cg7f42jH39/2EaAU4wNd4s2lKIk=",
                "encoding": "base64",
                "digest": "sha1",
                "key": {
                    "value": "736868",
                    "encoding": "hex"
                }
            }
        }
    },
    {
        "email": "[e-mail]",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "scrypt",
            "hash": {
                "value": "097f6197e1b41538f723e32aa7a68e8d76227d8e432ce5faa4882a913032db29",
                "encoding": "hex"
            },
            "salt": {
                "value": "abc123",
                "encoding": "utf8"
            },
            "keylen": 32,
            "cost": 4096
        }
    }
]

​

Ejemplos de factores de MFA

Como cabría esperar, el arreglo user.mfa_factors permite proporcionar las inscripciones del usuario en MFA. Los tipos de inscripción admitidos son:

• Teléfono: se usa para la verificación por SMS.
• TOTP: secreto de OTP para usar con aplicaciones de tipo MFA (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass).
• Correo electrónico: se usa para la verificación por correo electrónico.

Algunos ejemplos de usuarios con factores de MFA:

[
    {
        "email": "[e-mail]",
        "mfa_factors": [
            {
                "totp": {
                    "secret": "2PRXZWZAYYDAWCD"
                }
            },
            {
                "phone": {
                    "value": "[phone]"
                }
            },
            {
                "email": {
                    "value": "[e-mail]"
                }
            }
        ]
    },
    {
        "email": "[e-mail]",
        "mfa_factors": [
            {
                "totp": {
                    "secret": "JBTWY3DPEHPK3PNP"
                }
            }
        ]
    },
    {
        "email": "[e-mail]",
        "mfa_factors": [
            {
                "phone": {
                    "value": "[phone]"
                }
            },
        ]
    },
    {
        "email": "[e-mail]",
        "mfa_factors": [
            {
                "email": {
                    "value": "[e-mail]"
                }
            }
        ]
    }
]

​

Más información

• Importación masiva de usuarios
• Exportación masiva de usuarios
• Configurar la migración automática desde tu base de datos