管理用户

Firebase Admin SDK 为具有特权的管理员提供了一种 API 来管理 Firebase 用户。通过此管理员用户管理 API，您可以在安全的服务器环境中以编程方式完成以下任务：

• 创建新用户，且不受数量和速率限制。
• 按不同的条件（如 uid、电子邮件地址或电话号码）查找用户。
• 批量列出指定项目的所有用户。
• 访问用户元数据，包括帐号创建日期和上次登录日期。
• 删除用户（不需要获取用户当前使用的密码）。
• 更新用户属性（包括密码），且不需要以该用户身份登录。
• 验证电子邮件，而无需执行验证电子邮件的带外操作流程。
• 更改用户的电子邮件地址，而无需发送用于撤消更改的电子邮件地址链接。
• 使用电话号码创建新用户，而无需通过短信验证流程。
• 更改用户的电话号码，而无需通过短信验证流程。
• 在离线状态时将用户配置为停用状态，然后控制何时启用。
• 针对特定应用的用户管理系统构建自定义用户控制台。

开始前的准备工作

要使用由 Firebase Admin SDK 提供的用户管理 API，您必须有服务帐号。请参阅设置说明，详细了解如何初始化 Admin SDK。

检索用户数据

标识用户的主要方式是通过其 uid，这是属于用户的唯一标识符。Admin SDK 提供了一种方法，可以实现通过用户的 uid 提取用户的个人资料信息：

Node.js

admin.auth().getUser(uid)
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log('Successfully fetched user data:', userRecord.toJSON());
  })
  .catch(function(error) {
    console.log('Error fetching user data:', error);
  });

Java

UserRecord userRecord = FirebaseAuth.getInstance().getUser(uid);
// See the UserRecord reference doc for the contents of userRecord.
System.out.println("Successfully fetched user data: " + userRecord.getUid());

Python

from firebase_admin import auth

user = auth.get_user(uid)
print('Successfully fetched user data: {0}'.format(user.uid))

Go

// Get an auth client from the firebase.App
client, err := app.Auth(ctx)
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

u, err := client.GetUser(ctx, uid)
if err != nil {
	log.Fatalf("error getting user %s: %v\n", uid, err)
}
log.Printf("Successfully fetched user data: %v\n", u)
auth.go

C#

UserRecord userRecord = await FirebaseAuth.DefaultInstance.GetUserAsync(uid);
// See the UserRecord reference doc for the contents of userRecord.
Console.WriteLine($"Successfully fetched user data: {userRecord.Uid}");

此方法会返回一个与提供给该方法的 uid 所对应的用户的 UserRecord 对象。

如果提供的 uid 不属于现有用户，或者由于任何其他原因而无法提取用户，则上述方法会引发错误。有关错误代码的完整列表（包括说明和解决步骤），请参阅 Admin Auth API 错误。

在一些情况下，您可能有用户的电子邮件地址，但没有用户的 uid。Firebase Admin SDK 支持使用电子邮件地址查找用户信息：

Node.js

admin.auth().getUserByEmail(email)
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log('Successfully fetched user data:', userRecord.toJSON());
  })
  .catch(function(error) {
   console.log('Error fetching user data:', error);
  });

Java

UserRecord userRecord = FirebaseAuth.getInstance().getUserByEmail(email);
// See the UserRecord reference doc for the contents of userRecord.
System.out.println("Successfully fetched user data: " + userRecord.getEmail());

Python

from firebase_admin import auth

user = auth.get_user_by_email(email)
print('Successfully fetched user data: {0}'.format(user.uid))

Go

u, err := client.GetUserByEmail(ctx, email)
if err != nil {
	log.Fatalf("error getting user by email %s: %v\n", email, err)
}
log.Printf("Successfully fetched user data: %v\n", u)
auth.go

C#

UserRecord userRecord = await FirebaseAuth.DefaultInstance.GetUserByEmailAsync(email);
// See the UserRecord reference doc for the contents of userRecord.
Console.WriteLine($"Successfully fetched user data: {userRecord.Uid}");

此方法会返回一个与提供的电子邮件地址所对应的用户的 UserRecord 对象。

如果提供的电子邮件地址不属于现有用户，或者由于任何其他原因无法提取用户，则 Admin SDK 会引发错误。如需查看错误代码的完整列表（包括说明和解决步骤），请参阅 Admin Authentication API 错误。

警告：按电子邮件地址查找时，您只能搜索主（顶级）电子邮件地址，而不能搜索提供方专有的电子邮件地址。例如，如果一位用户的电子邮件为 [e-mail]，其关联的 Facebook 帐号拥有另一个电子邮件 ([e-mail])，那么调用 getUserByEmail("[e-mail]") 不会返回任何结果，而调用 getUserByEmail("[e-mail]") 则会找到相应的用户。如果默认设置为“每个电子邮件地址一个帐号”，则首次登录时使用的电子邮件地址将会作为顶级电子邮件地址，除非对其进行了修改。如果设置为“每个电子邮件地址多个帐号”，且没有手动进行更新，则仅会在使用密码创建用户时设置主电子邮件地址。

在其他情况下，您可能有用户的电话号码，但没有用户的 uid。Firebase Admin SDK 支持使用电话号码查找用户信息：

Node.js

admin.auth().getUserByPhoneNumber(phoneNumber)
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log('Successfully fetched user data:', userRecord.toJSON());
  })
  .catch(function(error) {
    console.log('Error fetching user data:', error);
  });

Java

UserRecord userRecord = FirebaseAuth.getInstance().getUserByPhoneNumber(phoneNumber);
// See the UserRecord reference doc for the contents of userRecord.
System.out.println("Successfully fetched user data: " + userRecord.getPhoneNumber());

Python

from firebase_admin import auth

user = auth.get_user_by_phone_number(phone)
print('Successfully fetched user data: {0}'.format(user.uid))

Go

u, err := client.GetUserByPhoneNumber(ctx, phone)
if err != nil {
	log.Fatalf("error getting user by phone %s: %v\n", phone, err)
}
log.Printf("Successfully fetched user data: %v\n", u)
auth.go

C#

UserRecord userRecord = await FirebaseAuth.DefaultInstance.GetUserByPhoneNumberAsync(phoneNumber);
// See the UserRecord reference doc for the contents of userRecord.
Console.WriteLine($"Successfully fetched user data: {userRecord.Uid}");

此方法会返回一个与提供的电话号码相对应的用户的 UserRecord 对象。

如果提供的电话号码不属于现有用户，或者由于任何其他原因无法获取用户，则 Admin SDK 会引发错误。如需查看错误代码的完整列表（包括说明和解决步骤），请参阅 Admin Authentication API 错误。

创建用户

Admin SDK 提供了一种方法，让您能够创建新的 Firebase 身份验证用户。此方法接受包含个人资料信息的对象，这些信息会添加到新创建的用户帐号中：

Node.js

admin.auth().createUser({
  email: '[e-mail]',
  emailVerified: false,
  phoneNumber: '[phone]',
  password: 'secretPassword',
  displayName: 'John Doe',
  photoURL: 'http://www.example.com/12345678/photo.png',
  disabled: false
})
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log('Successfully created new user:', userRecord.uid);
  })
  .catch(function(error) {
    console.log('Error creating new user:', error);
  });

Java

CreateRequest request = new CreateRequest()
    .setEmail("[e-mail]")
    .setEmailVerified(false)
    .setPassword("secretPassword")
    .setPhoneNumber("[phone]")
    .setDisplayName("John Doe")
    .setPhotoUrl("http://www.example.com/12345678/photo.png")
    .setDisabled(false);

UserRecord userRecord = FirebaseAuth.getInstance().createUser(request);
System.out.println("Successfully created new user: " + userRecord.getUid());

Python

user = auth.create_user(
    email='[e-mail]',
    email_verified=False,
    phone_number='[phone]',
    password='secretPassword',
    display_name='John Doe',
    photo_url='http://www.example.com/12345678/photo.png',
    disabled=False)
print('Sucessfully created new user: {0}'.format(user.uid))

Go

params := (&auth.UserToCreate{}).
	Email("[e-mail]").
	EmailVerified(false).
	PhoneNumber("[phone]").
	Password("secretPassword").
	DisplayName("John Doe").
	PhotoURL("http://www.example.com/12345678/photo.png").
	Disabled(false)
u, err := client.CreateUser(ctx, params)
if err != nil {
	log.Fatalf("error creating user: %v\n", err)
}
log.Printf("Successfully created user: %v\n", u)
auth.go

C#

UserRecordArgs args = new UserRecordArgs()
{
    Email = "[e-mail]",
    EmailVerified = false,
    PhoneNumber = "[phone]",
    Password = "secretPassword",
    DisplayName = "John Doe",
    PhotoUrl = "http://www.example.com/12345678/photo.png",
    Disabled = false,
};
UserRecord userRecord = await FirebaseAuth.DefaultInstance.CreateUserAsync(args);
// See the UserRecord reference doc for the contents of userRecord.
Console.WriteLine($"Successfully created new user: {userRecord.Uid}");

默认情况下，Firebase 身份验证会为新用户生成一个随机 uid。如果您想自行为新用户指定 uid，则可以将其添加到要传递给用户创建方法的参数中：

Node.js

admin.auth().createUser({
  uid: 'some-uid',
  email: '[e-mail]',
  phoneNumber: '[phone]'
})
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log('Successfully created new user:', userRecord.uid);
  })
  .catch(function(error) {
    console.log('Error creating new user:', error);
  });

Java

CreateRequest request = new CreateRequest()
    .setUid("some-uid")
    .setEmail("[e-mail]")
    .setPhoneNumber("[phone]");

UserRecord userRecord = FirebaseAuth.getInstance().createUser(request);
System.out.println("Successfully created new user: " + userRecord.getUid());

Python

user = auth.create_user(
    uid='some-uid', email='[e-mail]', phone_number='[phone]')
print('Sucessfully created new user: {0}'.format(user.uid))

Go

params := (&auth.UserToCreate{}).
	UID(uid).
	Email("[e-mail]").
	PhoneNumber("[phone]")
u, err := client.CreateUser(ctx, params)
if err != nil {
	log.Fatalf("error creating user: %v\n", err)
}
log.Printf("Successfully created user: %v\n", u)
auth.go

C#

UserRecordArgs args = new UserRecordArgs()
{
    Uid = "some-uid",
    Email = "[e-mail]",
    PhoneNumber = "[phone]",
};
UserRecord userRecord = await FirebaseAuth.DefaultInstance.CreateUserAsync(args);
// See the UserRecord reference doc for the contents of userRecord.
Console.WriteLine($"Successfully created new user: {userRecord.Uid}");

可以提供以下属性的任何组合：

表 1. 创建用户操作支持的属性

属性	类型	说明
uid	字符串	分配给新创建的用户的 uid。必须是包含 1 到 128 个字符的字符串（含 1 和 128）。如果没有提供，系统会自动生成一个随机 uid。
email	字符串	用户的主电子邮件。必须是有效的电子邮件地址。
emailVerified	布尔值	用户的主电子邮件是否通过验证。如果没有提供值，则默认为 false。
phoneNumber	字符串	用户的主要电话号码。必须是符合 E.164 规范的有效的电话号码。
password	字符串	用户的原始、未经哈希处理的密码。必须至少包含 6 个字符。
displayName	字符串	用户的显示名。
photoURL	字符串	用户的照片网址。
disabled	布尔值	用户是否被停用。true 表示已停用；false 表示已启用。如果没有提供相关值，默认为 false。

注意：以上所有属性均是可选的。如果没有为特定属性指定值，且上面的表格中未指到它有默认值，则该属性的值为空。

用户创建方法为新创建的用户返回 UserRecord 对象。

如果所提供的 uid、电子邮件地址或电话号码已被现有用户使用，或者由于任何其他原因无法创建用户，则上述方法将失败并报错。有关错误代码的完整列表（包括说明和解决步骤），请参阅 Admin Authentication API 错误。

更新用户

Firebase Admin SDK 可用于修改现有用户的数据。您需要指定 uid 以及要为该用户更新的属性：

Node.js

admin.auth().updateUser(uid, {
  email: '[e-mail]',
  phoneNumber: '[phone]',
  emailVerified: true,
  password: 'newPassword',
  displayName: 'Jane Doe',
  photoURL: 'http://www.example.com/12345678/photo.png',
  disabled: true
})
  .then(function(userRecord) {
    // See the UserRecord reference doc for the contents of userRecord.
    console.log('Successfully updated user', userRecord.toJSON());
  })
  .catch(function(error) {
    console.log('Error updating user:', error);
  });

Java

UpdateRequest request = new UpdateRequest(uid)
    .setEmail("[e-mail]")
    .setPhoneNumber("[phone]")
    .setEmailVerified(true)
    .setPassword("newPassword")
    .setDisplayName("Jane Doe")
    .setPhotoUrl("http://www.example.com/12345678/photo.png")
    .setDisabled(true);

UserRecord userRecord = FirebaseAuth.getInstance().updateUser(request);
System.out.println("Successfully updated user: " + userRecord.getUid());

Python

user = auth.update_user(
    uid,
    email='[e-mail]',
    phone_number='[phone]',
    email_verified=True,
    password='newPassword',
    display_name='John Doe',
    photo_url='http://www.example.com/12345678/photo.png',
    disabled=True)
print('Sucessfully updated user: {0}'.format(user.uid))

Go

params := (&auth.UserToUpdate{}).
	Email("[e-mail]").
	EmailVerified(true).
	PhoneNumber("[phone]").
	Password("newPassword").
	DisplayName("John Doe").
	PhotoURL("http://www.example.com/12345678/photo.png").
	Disabled(true)
u, err := client.UpdateUser(ctx, uid, params)
if err != nil {
	log.Fatalf("error updating user: %v\n", err)
}
log.Printf("Successfully updated user: %v\n", u)
auth.go

C#

UserRecordArgs args = new UserRecordArgs()
{
    Uid = uid,
    Email = "[e-mail]",
    PhoneNumber = "[phone]",
    EmailVerified = true,
    Password = "newPassword",
    DisplayName = "Jane Doe",
    PhotoUrl = "http://www.example.com/12345678/photo.png",
    Disabled = true,
};
UserRecord userRecord = await FirebaseAuth.DefaultInstance.UpdateUserAsync(args);
// See the UserRecord reference doc for the contents of userRecord.
Console.WriteLine($"Successfully updated user: {userRecord.Uid}");

可以提供以下属性的任何组合：

表 2. 更新用户操作支持的属性

属性	类型	说明
email	字符串	用户新的主电子邮件。必须是有效的电子邮件地址。
emailVerified	布尔值	用户的主电子邮件是否通过验证。如果没有提供值，则默认为 false。
phoneNumber	字符串	用户新的主要电话号码。必须是符合 E.164 规范的有效的电话号码。设置为 null 可清除用户的现有电话号码。
password	字符串	用户的新密码（原始且未经哈希处理）。必须至少包含 6 个字符。
displayName	字符串 | null	用户的新显示名。设置为 null 可清除用户的现有显示名。
photoURL	字符串 | null	用户的新照片网址。设置为 null 可清除用户的现有照片网址。如果不设置为 null，则必须提供一个有效的网址。
disabled	布尔值	用户是否被停用。true 表示已停用；false 表示已启用。

注意：以上所有属性均是可选的。如果没有为特定属性指定值，则该属性现有的值保持不变。

更新操作成功完成时，更新用户方法会返回更新后的 UserRecord 对象。

如果提供的 uid 与现有用户不符，所提供的电子邮件地址或电话号码已被现有用户使用，或者由于任何其他原因无法更新用户，则上述方法将失败并报错。有关错误代码的完整列表（包括说明和解决步骤），请参阅 Admin Authentication API 错误。

删除用户

Firebase Admin SDK 允许通过用户 uid 删除现有用户：

Node.js

admin.auth().deleteUser(uid)
  .then(function() {
    console.log('Successfully deleted user');
  })
  .catch(function(error) {
    console.log('Error deleting user:', error);
  });

Java

FirebaseAuth.getInstance().deleteUser(uid);
System.out.println("Successfully deleted user.");

Python

auth.delete_user(uid)
print('Successfully deleted user')

Go

err := client.DeleteUser(ctx, uid)
if err != nil {
	log.Fatalf("error deleting user: %v\n", err)
}
log.Printf("Successfully deleted user: %s\n", uid)
auth.go

C#

await FirebaseAuth.DefaultInstance.DeleteUserAsync(uid);
Console.WriteLine("Successfully deleted user.");

删除操作成功完成时，删除用户方法会返回一个空的结果。

如果提供的 uid 与现有用户不符，或者由于任何其他原因不能删除用户，则删除用户方法会引发错误。如需查看错误代码的完整列表（包括说明和解决步骤），请参阅 Admin Authentication API 错误。

列出所有用户

Firebase Admin SDK 支持批量检索完整的用户列表：

Node.js

function listAllUsers(nextPageToken) {
  // List batch of users, 1000 at a time.
  admin.auth().listUsers(1000, nextPageToken)
    .then(function(listUsersResult) {
      listUsersResult.users.forEach(function(userRecord) {
        console.log('user', userRecord.toJSON());
      });
      if (listUsersResult.pageToken) {
        // List next batch of users.
        listAllUsers(listUsersResult.pageToken);
      }
    })
    .catch(function(error) {
      console.log('Error listing users:', error);
    });
}
// Start listing users from the beginning, 1000 at a time.
listAllUsers();

Java

// Start listing users from the beginning, 1000 at a time.
ListUsersPage page = FirebaseAuth.getInstance().listUsers(null);
while (page != null) {
  for (ExportedUserRecord user : page.getValues()) {
    System.out.println("User: " + user.getUid());
  }
  page = page.getNextPage();
}

// Iterate through all users. This will still retrieve users in batches,
// buffering no more than 1000 users in memory at a time.
page = FirebaseAuth.getInstance().listUsers(null);
for (ExportedUserRecord user : page.iterateAll()) {
  System.out.println("User: " + user.getUid());
}

Python

# Start listing users from the beginning, 1000 at a time.
page = auth.list_users()
while page:
    for user in page.users:
        print('User: ' + user.uid)
    # Get next batch of users.
    page = page.get_next_page()

# Iterate through all users. This will still retrieve users in batches,
# buffering no more than 1000 users in memory at a time.
for user in auth.list_users().iterate_all():
    print('User: ' + user.uid)

Go

// Note, behind the scenes, the Users() iterator will retrive 1000 Users at a time through the API
iter := client.Users(ctx, "")
for {
	user, err := iter.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("error listing users: %s\n", err)
	}
	log.Printf("read user user: %v\n", user)
}

// Iterating by pages 100 users at a time.
// Note that using both the Next() function on an iterator and the NextPage()
// on a Pager wrapping that same iterator will result in an error.
pager := iterator.NewPager(client.Users(ctx, ""), 100, "")
for {
	var users []*auth.ExportedUserRecord
	nextPageToken, err := pager.NextPage(&users)
	if err != nil {
		log.Fatalf("paging error %v\n", err)
	}
	for _, u := range users {
		log.Printf("read user user: %v\n", u)
	}
	if nextPageToken == "" {
		break
	}
}
auth.go

C#

// Start listing users from the beginning, 1000 at a time.
var pagedEnumerable = FirebaseAuth.DefaultInstance.ListUsersAsync(null);
var responses = pagedEnumerable.AsRawResponses().GetEnumerator();
while (await responses.MoveNext())
{
    ExportedUserRecords response = responses.Current;
    foreach (ExportedUserRecord user in response.Users)
    {
        Console.WriteLine($"User: {user.Uid}");
    }
}

// Iterate through all users. This will still retrieve users in batches,
// buffering no more than 1000 users in memory at a time.
var enumerator = FirebaseAuth.DefaultInstance.ListUsersAsync(null).GetEnumerator();
while (await enumerator.MoveNext())
{
    ExportedUserRecord user = enumerator.Current;
    Console.WriteLine($"User: {user.Uid}");
}

每批结果都包含用户列表和用于列出下一批用户的下一页标记。如果已经列出所有用户，系统不会返回 pageToken。如果用户是密码用户，则此 API 还会返回由 Firebase 身份验证后端进行了哈希处理的 passwordSalt 和 passwordHash。

如果未指定 maxResults 字段，默认使用每批 1000 位用户。这也是可以一次性列出的最大用户数量。如果值超出该上限，系统就会抛出一个参数错误。如果未指定 pageToken，则操作将从头开始列出用户，并按 uid 排序。

如需查看错误代码的完整列表（包括说明和解决步骤），请参阅 Admin Authentication API 错误。