ユーザーの一括インポートのスキーマと例

Management API を使用したユーザーの一括インポートの方法について説明します。

ユーザーファイルには、JSON 形式のユーザー情報の配列を含める必要があります。

一括インポートのファイルサイズ上限は 500KB です。データがこのサイズを超える場合は、複数回に分けてインポートを実行する必要があります。

​

ユーザー JSON スキーマ

次の JSON スキーマは、有効なユーザーを定義します。

{
  "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
}

JSON スキーマの詳細については、jsonschema.orgを参照してください。

​

プロパティ

次のプロパティを使用してユーザーをインポートできます。

プロパティ	型	説明	インポート時にアップサート?
app_metadata	object	アプリケーションの中核機能や、ユーザーがアクセスできる内容に影響する可能性があるデータです。app_metadata に保存されたデータはユーザーが編集できません。これには、サポートプラン、ロール、アクセスグループなどが含まれる場合があります。	はい
blocked	boolean	ユーザーがブロックされているかどうかを示します。	いいえ
email	string	ユーザーのメールアドレスです。	いいえ
email_verified	boolean	ユーザーがメールアドレスを確認済みかどうかを示します。upsert によって email のみを更新し、email_verified を更新しない場合、デフォルトで false に設定されます。	はい
family_name	string	ユーザーの姓です。	はい
given_name	string	ユーザーの名です。	はい
name	string	ユーザーの氏名です。	はい
nickname	string	ユーザーのニックネームです。	はい
picture	string	ユーザーのプロフィール画像を指す URL です。	はい
user_id	string	ユーザーの一意の識別子です。これには接続ストラテジーが先頭に付加されます。	いいえ
user_metadata	object	勤務先住所、自宅住所、ユーザー設定など、ユーザーがアクセスできる内容に影響しないデータです。	はい
username	string	ユーザーのユーザー名です。	いいえ
password_hash	string	ユーザーの接続用のハッシュ化されたパスワードです。ユーザーの作成時、Auth0 はパスワードを保護するために bcrypt を使用します。ハッシュ化されたパスワードをインポートすると、ユーザーは既存のパスワードをそのまま使用できるため、よりスムーズに利用できます。互換性のあるパスワードは、bcrypt $2a$ または $2b$ を使用し、saltRounds を 10 にしてハッシュ化する必要があります。このプロパティは、ユーザーの初回インポート時にのみ指定でき、その後は更新できません。	いいえ
custom_password_hash	object	ユーザーのパスワードハッシュを指定する、より汎用的な方法です。ユーザーのパスワードハッシュが別のアルゴリズムで作成されている場合は、password_hash フィールドの代わりにこれを使用できます。一括インポート処理中に、ユーザーが最初にインポートされた custom_password_hash を使用してログインしていない場合は、custom_password_hash を更新できます。	はい
mfa_factors	array	このユーザーの認証に使用できる MFA ファクターです。	いいえ

app_metadata と user_metadata の詳細については、ユーザープロフィールにおけるメタデータの仕組みを理解する を参照してください。

​

アプリメタデータ

user.app_metadata オブジェクトには、次のプロパティを含めないでください。

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

​

カスタムパスワードハッシュ

ユーザーのパスワードハッシュが別のアルゴリズムで作成されている場合は、user.password_hash プロパティの代わりに user.custom_password_hash オブジェクトを使用できます。なお、このフィールドと password_hash は相互に排他的です。

user.custom_password_hash オブジェクトには、次のプロパティがあります。

Property	Type	Description
algorithm	string	パスワードのハッシュ化に使用するアルゴリズム。次のいずれかである必要があります: argon2 bcrypt hmac ldap md4 md5 sha1 sha256 sha512 pbkdf2 scrypt
hash	object
hash.value	string	パスワードハッシュ。
hash.encoding	string	指定したハッシュのエンコーディング。次のいずれかである必要があります: base64 hex utf8 大文字・小文字の両方の 16 進表記と、URL エンコードされた base64 がサポートされています。
hash.digest	string	HMAC ハッシュの生成に使用するアルゴリズム。次のいずれかである必要があります: md4 md5 ripemd160 sha1 sha224 sha256 sha384 sha512 whirlpool
hash.key	object	HMAC ハッシュの生成に使用するキー。
hash.key.value	string	キーの値。
hash.key.encoding	string	キーのエンコーディング。次のいずれかである必要があります: base64 hex utf8 デフォルトでは、hash.key.encoding は utf8 です。
salt	object
salt.value	string	ハッシュの生成に使用するソルト値。
salt.encoding	string	指定したソルトのエンコーディング。次のいずれかである必要があります: base64 hex utf8 大文字・小文字の両方の 16 進表記と、URL エンコードされた base64 がサポートされています。デフォルトでは、salt.encoding は utf8 です。
salt.position	string	ハッシュ計算時のソルトの位置。デフォルトでは、salt.position は prefix です。
password.encoding	string	ハッシュの生成に使用するパスワードのエンコーディング。次のいずれかである必要があります: ascii utf8 utf16le ucs2 latin1 binary Login 時には、ユーザーが入力したパスワードは、指定されたハッシュと照合される前に password.encoding に基づいてトランスコードされます。たとえば、ハッシュが ucs2 でエンコードされた文字列から生成されている場合は、次のように設定します: "encoding": "ucs2"
keylen	integer	scrypt ハッシュで使用する、バイト単位のキー長。0 より大きい整数である必要があります。 このパラメーターは、algorithm が scrypt に設定されている場合は必須です。
cost	integer	scrypt ハッシュで使用する CPU/メモリーのコストパラメーター。1 より大きい 2 の累乗である必要があります。デフォルトでは、cost は 16384 です。 このパラメーターは、algorithm が scrypt に設定されている場合にのみ使用されます。
blockSize	integer	scrypt ハッシュで使用するブロックサイズパラメーター。正の整数である必要があります。デフォルトでは、blockSize は 8 です。 このパラメーターは、algorithm が scrypt に設定されている場合にのみ使用されます。
parallelization	integer	scrypt ハッシュで使用する並列化パラメーター。正の整数である必要があります。デフォルトでは、parallelization は 1 です。 このパラメーターは、algorithm が scrypt に設定されている場合にのみ使用されます。

​

カスタムパスワードハッシュを更新する

一括インポート中に、ユーザーが最初にインポートした custom_password_hash を使ってログインしていない場合は、custom_password_hash を更新できます。たとえば、以下の JSON を custom_password_hash に異なる値を指定して /api/v2/jobs/users-imports エンドポイントに 2 回送信できます。2 回目の送信時には、upsert フラグを true に設定してください。

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

browserling.com の Bcrypt Password Generator を使用して、bcrypt のパスワードハッシュを生成できます。

​

サポートされているハッシュアルゴリズム

Auth0 は現在、次の方式でハッシュ化されたユーザーのパスワードのインポートをサポートしています。

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

custom_password_hash を指定する際は、以下のセクションを参照してください。

​

Argon2

algorithm が argon2 に設定されている場合:

• hash.encoding は utf8 でなければなりません。
• hash.salt は使用できません。
• hash.value は、GitHub の P-H-C / phc-string-format で規定されている PHC 文字列形式である必要があります。また、GitHub の Auth0 / magic で指定されている要件にも準拠している必要があります。
• hash.value には、base64 エンコードされた ソルト (PHC ドキュメントで規定されているとおり) を含める必要があります。

​

bcrypt

algorithm が bcrypt に設定されている場合:

• hash.encoding は utf8 である必要があります。

• hash.salt は、ソルト のエンコーディングおよび位置とあわせて使用できます。

• hash.value には、次のいずれかのプレフィックスが含まれている必要があります。

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

  現時点では、$2$、$sha1$、$2x$ などの他のプレフィックスはサポートされていません。

たとえば、次の値は、コストパラメーター 10 を使用して文字列 hello から生成されたものです。

$2b$10$nFguVi9LsCAcvTZFKQlRKeLVydo8ETv483lkNsSFI/Wl1Rz1Ypo1K

bcrypt アルゴリズムは、パスワードハッシュの計算時または比較時に最大 72 バイトの入力を処理します。また、salt.value の長さもこの 72 バイトの入力上限に含まれます。72 バイトの上限を超える入力は切り詰められます。たとえば、ソルト が 10 バイトを使用する場合、ハッシュ化または比較に使用できるパスワードの最大長は 62 バイトです。

この短縮後の上限を超えるパスワードは切り詰められるため、パスワード強度が低下したり、ハッシュ衝突が発生したりする可能性があります。ハッシュ化する前に、必ずパスワードの長さを検証してください.

​

HMAC

algorithm が hmac に設定されている場合:

• hash.encoding は hex または base64 のいずれかである必要があります。

• hash.digest は必須であり、次のいずれかである必要があります。

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

• hash.key.value は必須です。

• hash.key.encoding は base64、hex、utf8 のいずれかである必要があります。

​

LDAP

algorithm が ldap に設定されている場合:

• hash.encoding は utf8 でなければなりません。
• ソルト は使用できません。
• hash.value は、IETF Datatracker の RFC-2307 section-5.3 で定義されている形式に準拠している必要があります。
• スキームは md5|smd5|sha*|ssha* のいずれかである必要があります。詳細については こちら を参照してください。
• crypt スキームは、システムや実装によって動作が異なるため サポートされていません。詳細については、Open LDAP Admin Guide - 14.4.2. CRYPT password storage scheme を参照してください。

​

MD または SHA

algorithm が md4、md5、sha1、sha256、または sha512 に設定されている場合:

• hash.encoding は hex または base64 のいずれかである必要があります。

​

PBKDF2

algorithm が pbkdf2 に設定されている場合:

• hash.encoding は utf8 である必要があります。

• hash.salt は使用できません。

• hash.value は、GitHub の P-H-C / phc-string-format で規定されている PHC 文字列形式である必要があります。

• hash.value には、B64 エンコードされた ソルト (PHC ドキュメントで指定されているとおり、パディング文字 = を除いた base64) を含める必要があります。

• hash.value には i (反復回数) および l (keylen) パラメーターを含める必要があります。これらのパラメーターを省略した場合、デフォルトで i=100000 および l=64 が使用されます。

• id は pbkdf2-<digest> 形式 (pbkdf2-sha512、pbkdf2-md5 など) である必要があります。サポートされているダイジェストは次のとおりです。

  • 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

algorithm が scrypt に設定されている場合:

• hash.encoding は hex または base64 のいずれかである必要があります。
• keylen パラメーターは必須です。
• cost パラメーターは省略可能です。指定しない場合、デフォルト値は 16384 です。
• blockSize パラメーターは省略可能です。指定しない場合、デフォルト値は 8 です。
• parallelization パラメーターは省略可能です。指定しない場合、デフォルト値は 1 です。

​

MFA ファクター

user.mfa_factors 配列には、ユーザーの MFA 登録情報が含まれます。詳細については、Auth0 の多要素認証 を参照してください。登録情報をインポートすると、インポート後にユーザーが MFA に再登録する必要がなくなります。サポートされている登録タイプは次のとおりです。

プロパティ	型	説明
email	object
email.value	string	MFA 用のメールアドレス。
phone	object
phone.value	string	SMS MFA 用の電話番号。国コードを含み、+ で始まっている必要があります。例: "[phone]"
totp	object
totp.secret	string	認証アプリ (Google Authenticator、Microsoft Authenticator、Authy、1Password、LastPass) を使用する MFA 認証用の OTP シークレット。パディングなしの Base32 エンコードである必要があります。例: "JBTWY3DPEHPK3PNP"

​

例

​

基本的な例

次の内容を含むファイルは有効です。

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

​

カスタムパスワードハッシュの例

ハッシュが指定されたユーザーの例:

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

​

MFA ファクターの例

user.mfa_factors 配列では、ユーザーの MFA 登録情報を指定できます。サポートされている登録タイプは次のとおりです。

• 電話番号: SMS ベースの認証に使用します。
• TOTP: MFA アプリ (Google Authenticator、Microsoft Authenticator、Authy、1Password、LastPass) で使用する OTP シークレットです。
• メールアドレス: メールベースの認証に使用します。

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]"
                }
            }
        ]
    }
]

​

詳しく見る

• ユーザーの一括インポート
• ユーザーの一括エクスポート
• データベースからの自動移行を設定する