导入用户

Firebase Admin SDK 提供了 auth.importUsers() API,支持以更高的权限将用户批量导入 Firebase 身份验证。尽管 Firebase CLI 中也有此功能,但 Admin SDK 允许您以编程方式上传外部身份验证系统或其他 Firebase 项目中的现有用户,而无需创建过渡用的 CSV 或 JSON 文件。

用户导入 API 具有以下优势:

  • 能够从使用不同密码哈希算法的外部身份验证系统迁移用户。
  • 能够从其他 Firebase 项目迁移用户。
  • 经过优化,能够快速而高效地执行批量导入操作。此操作在处理用户时不会核实 uidemailphoneNumber 或其他标识符的重复情况。
  • 能够迁移现有 OAuth 用户或创建新的 OAuth 用户(Google、Facebook 等)。
  • 能够直接批量导入使用了自定义声明的用户。

用法

一次 API 调用最多可以导入 1000 名用户。请注意,此操作针对速度进行了优化,不会核实 uidemailphoneNumber 和其他唯一标识符的重复情况。因此,在您使用此 API 时,必须确保独一无二的字段不会出现重复。

Node.js

// Up to 1000 users can be imported at once.
var userImportRecords = [
  {
    uid: 'uid1',
    email: 'user1@example.com',
    passwordHash: Buffer.from('passwordHash1'),
    passwordSalt: Buffer.from('salt1')
  },
  {
    uid: 'uid2',
    email: 'user2@example.com',
    passwordHash: Buffer.from('passwordHash2'),
    passwordSalt: Buffer.from('salt2')
  },
  ...
];

Java

// Up to 1000 users can be imported at once.
List<ImportUserRecord> users = new ArrayList<>();
users.add(ImportUserRecord.builder()
    .setUid("uid1")
    .setEmail("user1@example.com")
    .setPasswordHash("passwordHash1".getBytes())
    .setPasswordSalt("salt1".getBytes())
    .build());
users.add(ImportUserRecord.builder()
    .setUid("uid2")
    .setEmail("user2@example.com")
    .setPasswordHash("passwordHash2".getBytes())
    .setPasswordSalt("salt2".getBytes())
    .build());

Python

# Up to 1000 users can be imported at once.
users = [
    auth.ImportUserRecord(
        uid='uid1',
        email='user1@example.com',
        password_hash=b'password_hash_1',
        password_salt=b'salt1'
    ),
    auth.ImportUserRecord(
        uid='uid2',
        email='user2@example.com',
        password_hash=b'password_hash_2',
        password_salt=b'salt2'
    ),
]

Go

// Up to 1000 users can be imported at once.
var users []*auth.UserToImport
users = append(users, (&auth.UserToImport{}).
	UID("uid1").
	Email("user1@example.com").
	PasswordHash([]byte("passwordHash1")).
	PasswordSalt([]byte("salt1")))
users = append(users, (&auth.UserToImport{}).
	UID("uid2").
	Email("user2@example.com").
	PasswordHash([]byte("passwordHash2")).
	PasswordSalt([]byte("salt2")))

此示例中指定了哈希选项,目的是在用户下次尝试通过 Firebase 身份验证登录时,帮助 Firebase 安全地对这些用户进行身份验证。成功登录后,Firebase 会使用内部 Firebase 哈希算法重新对用户密码进行哈希处理。您可以在下面详细了解每种算法的必填字段。

即使发生与特定用户相关的错误,Firebase 身份验证也会尽量上传所提供的全部用户。此操作会返回一个结果,其中对导入成功和导入失败的情况进行了总结。每一次的用户导入失败都会有对应的错误详情。

Node.js

var userImportOptions = {
  hash: {
    algorithm: 'HMAC_SHA256',
    key: Buffer.from('secretKey')
  }
};

admin.auth().importUsers(userImportRecords, userImportOptions)
  .then(function(userImportResult) {
    // The number of successful imports is determined via: userImportResult.successCount.
    // The number of failed imports is determined via: userImportResult.failureCount.
    // To get the error details.
    userImportResult.forEach(function(indexedError) {
        // The corresponding user that failed to upload.
        console.log(userImportRecords[indexedError.index].uid +' failed to import',
            indexedError.error);
    });
  })
  .catch(function(error) {
    // Some unrecoverable error occurred that prevented the operation from running.
  });

Java

UserImportOptions options = UserImportOptions.withHash(
    HmacSha256.builder()
        .setKey("secretKey".getBytes())
        .build());
try {
  UserImportResult result = FirebaseAuth.getInstance().importUsers(users, options);
  System.out.println("Successfully imported " + result.getSuccessCount() + " users");
  System.out.println("Failed to import " + result.getFailureCount() + " users");
  for (ErrorInfo indexedError : result.getErrors()) {
    System.out.println("Failed to import user at index: " + indexedError.getIndex()
        + " due to error: " + indexedError.getReason());
  }
} catch (FirebaseAuthException e) {
  // Some unrecoverable error occurred that prevented the operation from running.
}

Python

hash_alg = auth.UserImportHash.hmac_sha256(key=b'secret_key')
try:
    result = auth.import_users(users, hash_alg=hash_alg)
    print('Successfully imported {0} users. Failed to import {1} users.'.format(
        result.success_count, result.failure_count))
    for err in result.errors:
        print('Failed to import {0} due to {1}'.format(users[err.index].uid, err.reason))
except auth.AuthError:
    # Some unrecoverable error occurred that prevented the operation from running.
    pass

Go

client, err := app.Auth(ctx)
if err != nil {
	log.Fatalln("Error initializing Auth client", err)
}

h := hash.HMACSHA256{
	Key: []byte("secretKey"),
}
result, err := client.ImportUsers(ctx, users, auth.WithHash(h))
if err != nil {
	log.Fatalln("Unrecoverable error prevented the operation from running", err)
}

log.Printf("Successfully imported %d users\n", result.SuccessCount)
log.Printf("Failed to import %d users\n", result.FailureCount)
for _, e := range result.Errors {
	log.Printf("Failed to import user at index: %d due to error: %s\n", e.Index, e.Reason)
}

如果不需要对密码进行哈希处理(电话号码、自定义令牌用户、OAuth 用户等),则无需提供哈希选项。

导入密码经过 HMAC 哈希处理的用户

HMAC 哈希算法包括:HMAC_MD5HMAC_SHA1HMAC_SHA256HMAC_SHA512。对于这些哈希算法,您必须提供哈希签名者密钥。

Node.js

admin.auth().importUsers([{
  uid: 'some-uid',
  email: 'user@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('password-hash'),
  // Must be provided in a byte buffer.
  passwordSalt: Buffer.from('salt')
}], {
  hash: {
    algorithm: 'HMAC_SHA256',
    // Must be provided in a byte buffer.
    key: Buffer.from('secret')
  }
}).then(function(results) {
  results.errors.forEach(function(indexedError) {
    console.log('Error importing user ' + indexedError.index);
  });
}).catch(function(error) {
  console.log('Error importing users:', error);
});

Java

try {
  List<ImportUserRecord> users = Collections.singletonList(ImportUserRecord.builder()
      .setUid("some-uid")
      .setEmail("user@example.com")
      .setPasswordHash("password-hash".getBytes())
      .setPasswordSalt("salt".getBytes())
      .build());
  UserImportOptions options = UserImportOptions.withHash(
      HmacSha256.builder()
          .setKey("secret".getBytes())
          .build());
  UserImportResult result = FirebaseAuth.getInstance().importUsers(users, options);
  for (ErrorInfo indexedError : result.getErrors()) {
    System.out.println("Failed to import user: " + indexedError.getReason());
  }
} catch (FirebaseAuthException e) {
  System.out.println("Error importing users: " + e.getMessage());
}

Python

users = [
    auth.ImportUserRecord(
        uid='some-uid',
        email='user@example.com',
        password_hash=b'password_hash',
        password_salt=b'salt'
    ),
]

hash_alg = auth.UserImportHash.hmac_sha256(key=b'secret')
try:
    result = auth.import_users(users, hash_alg=hash_alg)
    for err in result.errors:
        print('Failed to import user:', err.reason)
except auth.AuthError as error:
    print('Error importing users:', error)

Go

users := []*auth.UserToImport{
	(&auth.UserToImport{}).
		UID("some-uid").
		Email("user@example.com").
		PasswordHash([]byte("password-hash")).
		PasswordSalt([]byte("salt")),
}
h := hash.HMACSHA256{
	Key: []byte("secret"),
}
result, err := client.ImportUsers(ctx, users, auth.WithHash(h))
if err != nil {
	log.Fatalln("Error importing users", err)
}
for _, e := range result.Errors {
	log.Println("Failed to import user", e.Reason)
}

导入使用 MD5、SHA 和 PBKDF 哈希密码的用户

MD5、SHA 和 PBKDF 哈希算法包括:MD5SHA1SHA256SHA512PBKDF_SHA1PBKDF2_SHA256。对于这些哈希算法,您必须提供对密码进行哈希处理的轮数(介于 0 到 120000 之间)。

Node.js

admin.auth().importUsers([{
  uid: 'some-uid',
  email: 'user@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('password-hash'),
  // Must be provided in a byte buffer.
  passwordSalt: Buffer.from('salt')
}], {
  hash: {
    algorithm: 'PBKDF2_SHA256',
    rounds: 100000
  }
}).then(function(results) {
  results.errors.forEach(function(indexedError) {
    console.log('Error importing user ' + indexedError.index);
  });
}).catch(function(error) {
  console.log('Error importing users:', error);
});

Java

try {
  List<ImportUserRecord> users = Collections.singletonList(ImportUserRecord.builder()
      .setUid("some-uid")
      .setEmail("user@example.com")
      .setPasswordHash("password-hash".getBytes())
      .setPasswordSalt("salt".getBytes())
      .build());
  UserImportOptions options = UserImportOptions.withHash(
      Pbkdf2Sha256.builder()
          .setRounds(100000)
          .build());
  UserImportResult result = FirebaseAuth.getInstance().importUsers(users, options);
  for (ErrorInfo indexedError : result.getErrors()) {
    System.out.println("Failed to import user: " + indexedError.getReason());
  }
} catch (FirebaseAuthException e) {
  System.out.println("Error importing users: " + e.getMessage());
}

Python

users = [
    auth.ImportUserRecord(
        uid='some-uid',
        email='user@example.com',
        password_hash=b'password_hash',
        password_salt=b'salt'
    ),
]

hash_alg = auth.UserImportHash.pbkdf2_sha256(rounds=100000)
try:
    result = auth.import_users(users, hash_alg=hash_alg)
    for err in result.errors:
        print('Failed to import user:', err.reason)
except auth.AuthError as error:
    print('Error importing users:', error)

Go

users := []*auth.UserToImport{
	(&auth.UserToImport{}).
		UID("some-uid").
		Email("user@example.com").
		PasswordHash([]byte("password-hash")).
		PasswordSalt([]byte("salt")),
}
h := hash.PBKDF2SHA256{
	Rounds: 100000,
}
result, err := client.ImportUsers(ctx, users, auth.WithHash(h))
if err != nil {
	log.Fatalln("Error importing users", err)
}
for _, e := range result.Errors {
	log.Println("Failed to import user", e.Reason)
}

导入密码经过标准 SCRYPT 哈希处理的用户

Firebase 身份验证支持 SCRYPT 算法的标准版本和内部修订版本。对于标准 SCRYPT 算法,需要提供以下哈希参数:

  • memoryCost:哈希算法的 CPU/内存开销。
  • parallelization:哈希算法的并行化。
  • blockSize:哈希算法的块大小(通常为 8)。
  • derivedKeyLength:哈希算法的派生密钥长度。

Node.js

admin.auth().importUsers([{
  uid: 'some-uid',
  email: 'user@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('password-hash'),
  // Must be provided in a byte buffer.
  passwordSalt: Buffer.from('salt')
}], {
  hash: {
    algorithm: 'STANDARD_SCRYPT',
    memoryCost: 1024,
    parallelization: 16,
    blockSize: 8,
    derivedKeyLength: 64
  }
}).then(function(results) {
  results.errors.forEach(function(indexedError) {
    console.log('Error importing user ' + indexedError.index);
  });
}).catch(function(error) {
  console.log('Error importing users:', error);
});

Java

try {
  List<ImportUserRecord> users = Collections.singletonList(ImportUserRecord.builder()
      .setUid("some-uid")
      .setEmail("user@example.com")
      .setPasswordHash("password-hash".getBytes())
      .setPasswordSalt("salt".getBytes())
      .build());
  UserImportOptions options = UserImportOptions.withHash(
      StandardScrypt.builder()
          .setMemoryCost(1024)
          .setParallelization(16)
          .setBlockSize(8)
          .setDerivedKeyLength(64)
          .build());
  UserImportResult result = FirebaseAuth.getInstance().importUsers(users, options);
  for (ErrorInfo indexedError : result.getErrors()) {
    System.out.println("Failed to import user: " + indexedError.getReason());
  }
} catch (FirebaseAuthException e) {
  System.out.println("Error importing users: " + e.getMessage());
}

Python

users = [
    auth.ImportUserRecord(
        uid='some-uid',
        email='user@example.com',
        password_hash=b'password_hash',
        password_salt=b'salt'
    ),
]

hash_alg = auth.UserImportHash.standard_scrypt(
    memory_cost=1024, parallelization=16, block_size=8, derived_key_length=64)
try:
    result = auth.import_users(users, hash_alg=hash_alg)
    for err in result.errors:
        print('Failed to import user:', err.reason)
except auth.AuthError as error:
    print('Error importing users:', error)

Go

users := []*auth.UserToImport{
	(&auth.UserToImport{}).
		UID("some-uid").
		Email("user@example.com").
		PasswordHash([]byte("password-hash")).
		PasswordSalt([]byte("salt")),
}
h := hash.StandardScrypt{
	MemoryCost:       1024,
	Parallelization:  16,
	BlockSize:        8,
	DerivedKeyLength: 64,
}
result, err := client.ImportUsers(ctx, users, auth.WithHash(h))
if err != nil {
	log.Fatalln("Error importing users", err)
}
for _, e := range result.Errors {
	log.Println("Failed to import user", e.Reason)
}

导入密码经过 BCRYPT 哈希处理的用户

对于 BCRYPT 哈希密码,既不需要额外的哈希参数,也不需要每个用户的密码盐。

Node.js

admin.auth().importUsers([{
  uid: 'some-uid',
  email: 'user@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('password-hash')
}], {
  hash: {
    algorithm: 'BCRYPT'
  }
}).then(function(results) {
  results.errors.forEach(function(indexedError) {
    console.log('Error importing user ' + indexedError.index);
  });
}).catch(function(error) {
  console.log('Error importing users:', error);
});

Java

try {
  List<ImportUserRecord> users = Collections.singletonList(ImportUserRecord.builder()
      .setUid("some-uid")
      .setEmail("user@example.com")
      .setPasswordHash("password-hash".getBytes())
      .setPasswordSalt("salt".getBytes())
      .build());
  UserImportOptions options = UserImportOptions.withHash(Bcrypt.getInstance());
  UserImportResult result = FirebaseAuth.getInstance().importUsers(users, options);
  for (ErrorInfo indexedError : result.getErrors()) {
    System.out.println("Failed to import user: " + indexedError.getReason());
  }
} catch (FirebaseAuthException e) {
  System.out.println("Error importing users: " + e.getMessage());
}

Python

users = [
    auth.ImportUserRecord(
        uid='some-uid',
        email='user@example.com',
        password_hash=b'password_hash',
        password_salt=b'salt'
    ),
]

hash_alg = auth.UserImportHash.bcrypt()
try:
    result = auth.import_users(users, hash_alg=hash_alg)
    for err in result.errors:
        print('Failed to import user:', err.reason)
except auth.AuthError as error:
    print('Error importing users:', error)

Go

users := []*auth.UserToImport{
	(&auth.UserToImport{}).
		UID("some-uid").
		Email("user@example.com").
		PasswordHash([]byte("password-hash")).
		PasswordSalt([]byte("salt")),
}
h := hash.Bcrypt{}
result, err := client.ImportUsers(ctx, users, auth.WithHash(h))
if err != nil {
	log.Fatalln("Error importing users", err)
}
for _, e := range result.Errors {
	log.Println("Failed to import user", e.Reason)
}

导入密码经过 Firebase SCRYPT 哈希处理的用户

如果是从其他现有 Firebase 项目迁移用户,您将需要导入用 Firebase 修订版 SCRYPT 哈希算法进行哈希处理的密码。为此,您需要确定原始项目的一些内部参数。

Firebase 会为每个 Firebase 项目生成独一无二的密码哈希参数。要查看这些参数,请转至 Firebase 控制台中的用户标签,然后从用户表格列表右上角的下拉列表中选择密码哈希参数

为此算法构建哈希选项所需的参数包括:

  • key:通常以 base64 编码形式提供的签名者密钥。
  • saltSeparator:通常以 base64 编码形式提供的盐分隔符(可选)。
  • rounds:对密码进行哈希处理的轮数。
  • memoryCost:此算法所需的内存开销。

Node.js

admin.auth().importUsers([{
  uid: 'some-uid',
  email: 'user@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('base64-password-hash', 'base64'),
  // Must be provided in a byte buffer.
  passwordSalt: Buffer.from('base64-salt', 'base64')
}], {
  hash: {
    algorithm: 'SCRYPT',
    // All the parameters below can be obtained from the Firebase Console's users section.
    // Must be provided in a byte buffer.
    key: Buffer.from('base64-secret', 'base64'),
    saltSeparator: Buffer.from('base64SaltSeparator', 'base64'),
    rounds: 8,
    memoryCost: 14
  }
}).then(function(results) {
  results.errors.forEach(function(indexedError) {
    console.log('Error importing user ' + indexedError.index);
  });
}).catch(function(error) {
  console.log('Error importing users:', error);
});

Java

try {
  List<ImportUserRecord> users = Collections.singletonList(ImportUserRecord.builder()
      .setUid("some-uid")
      .setEmail("user@example.com")
      .setPasswordHash("password-hash".getBytes())
      .setPasswordSalt("salt".getBytes())
      .build());
  UserImportOptions options = UserImportOptions.withHash(
      Scrypt.builder()
          // All the parameters below can be obtained from the Firebase Console's "Users"
          // section. Base64 encoded parameters must be decoded into raw bytes.
          .setKey(BaseEncoding.base64().decode("base64-secret"))
          .setSaltSeparator(BaseEncoding.base64().decode("base64-salt-separator"))
          .setRounds(8)
          .setMemoryCost(14)
          .build());
  UserImportResult result = FirebaseAuth.getInstance().importUsers(users, options);
  for (ErrorInfo indexedError : result.getErrors()) {
    System.out.println("Failed to import user: " + indexedError.getReason());
  }
} catch (FirebaseAuthException e) {
  System.out.println("Error importing users: " + e.getMessage());
}

Python

users = [
    auth.ImportUserRecord(
        uid='some-uid',
        email='user@example.com',
        password_hash=b'password_hash',
        password_salt=b'salt'
    ),
]

# All the parameters below can be obtained from the Firebase Console's "Users"
# section. Base64 encoded parameters must be decoded into raw bytes.
hash_alg = auth.UserImportHash.scrypt(
    key=base64.b64decode('base64_secret'),
    salt_separator=base64.b64decode('base64_salt_separator'),
    rounds=8,
    memory_cost=14
)
try:
    result = auth.import_users(users, hash_alg=hash_alg)
    for err in result.errors:
        print('Failed to import user:', err.reason)
except auth.AuthError as error:
    print('Error importing users:', error)

Go

users := []*auth.UserToImport{
	(&auth.UserToImport{}).
		UID("some-uid").
		Email("user@example.com").
		PasswordHash([]byte("password-hash")).
		PasswordSalt([]byte("salt")),
}
b64decode := func(s string) []byte {
	b, err := base64.StdEncoding.DecodeString(s)
	if err != nil {
		log.Fatalln("Failed to decode string", err)
	}
	return b
}

// All the parameters below can be obtained from the Firebase Console's "Users"
// section. Base64 encoded parameters must be decoded into raw bytes.
h := hash.Scrypt{
	Key:           b64decode("base64-secret"),
	SaltSeparator: b64decode("base64-salt-separator"),
	Rounds:        8,
	MemoryCost:    14,
}
result, err := client.ImportUsers(ctx, users, auth.WithHash(h))
if err != nil {
	log.Fatalln("Error importing users", err)
}
for _, e := range result.Errors {
	log.Println("Failed to import user", e.Reason)
}

导入没有密码的用户

您可以导入没有密码的用户。对于没有密码的用户,可以将他们与使用 OAuth 提供方、自定义声明和电话号码等的用户合并在一起导入。

Node.js

admin.auth().importUsers([{
  uid: 'some-uid',
  displayName: 'John Doe',
  email: 'johndoe@gmail.com',
  photoURL: 'http://www.example.com/12345678/photo.png',
  emailVerified: true,
  phoneNumber: '+11234567890',
  // Set this user as admin.
  customClaims: {admin: true},
  // User with Google provider.
  providerData: [{
    uid: 'google-uid',
    email: 'johndoe@gmail.com',
    displayName: 'John Doe',
    photoURL: 'http://www.example.com/12345678/photo.png',
    providerId: 'google.com'
  }]
}]).then(function(results) {
  results.errors.forEach(function(indexedError) {
    console.log('Error importing user ' + indexedError.index);
  });
}).catch(function(error) {
  console.log('Error importing users:', error);
});

Java

try {
  List<ImportUserRecord> users = Collections.singletonList(ImportUserRecord.builder()
      .setUid("some-uid")
      .setDisplayName("John Doe")
      .setEmail("johndoe@gmail.com")
      .setPhotoUrl("http://www.example.com/12345678/photo.png")
      .setEmailVerified(true)
      .setPhoneNumber("+11234567890")
      .putCustomClaim("admin", true) // set this user as admin
      .addUserProvider(UserProvider.builder() // user with Google provider
          .setUid("google-uid")
          .setEmail("johndoe@gmail.com")
          .setDisplayName("John Doe")
          .setPhotoUrl("http://www.example.com/12345678/photo.png")
          .setProviderId("google.com")
          .build())
      .build());
  UserImportResult result = FirebaseAuth.getInstance().importUsers(users);
  for (ErrorInfo indexedError : result.getErrors()) {
    System.out.println("Failed to import user: " + indexedError.getReason());
  }
} catch (FirebaseAuthException e) {
  System.out.println("Error importing users: " + e.getMessage());
}

Python

users = [
    auth.ImportUserRecord(
        uid='some-uid',
        display_name='John Doe',
        email='johndoe@gmail.com',
        photo_url='http://www.example.com/12345678/photo.png',
        email_verified=True,
        phone_number='+11234567890',
        custom_claims={'admin': True}, # set this user as admin
        provider_data=[ # user with Google provider
            auth.UserProvider(
                uid='google-uid',
                email='johndoe@gmail.com',
                display_name='John Doe',
                photo_url='http://www.example.com/12345678/photo.png',
                provider_id='google.com'
            )
        ],
    ),
]
try:
    result = auth.import_users(users)
    for err in result.errors:
        print('Failed to import user:', err.reason)
except auth.AuthError as error:
    print('Error importing users:', error)

Go

users := []*auth.UserToImport{
	(&auth.UserToImport{}).
		UID("some-uid").
		DisplayName("John Doe").
		Email("johndoe@gmail.com").
		PhotoURL("http://www.example.com/12345678/photo.png").
		EmailVerified(true).
		PhoneNumber("+11234567890").
		CustomClaims(map[string]interface{}{"admin": true}). // set this user as admin
		ProviderData([]*auth.UserProvider{                   // user with Google provider
			{
				UID:         "google-uid",
				Email:       "johndoe@gmail.com",
				DisplayName: "John Doe",
				PhotoURL:    "http://www.example.com/12345678/photo.png",
				ProviderID:  "google.com",
			},
		}),
}
result, err := client.ImportUsers(ctx, users)
if err != nil {
	log.Fatalln("Error importing users", err)
}
for _, e := range result.Errors {
	log.Println("Failed to import user", e.Reason)
}

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面