管理用户

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 错误。

在其他情况下，您可以使用用户的电话号码而不是其 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: 'user@example.com',
  emailVerified: false,
  phoneNumber: '+11234567890',
  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("user@example.com")
    .setEmailVerified(false)
    .setPassword("secretPassword")
    .setPhoneNumber("+11234567890")
    .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='user@example.com',
    email_verified=False,
    phone_number='+15555550100',
    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("user@example.com").
	EmailVerified(false).
	PhoneNumber("+15555550100").
	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 = "user@example.com",
    EmailVerified = false,
    PhoneNumber = "+11234567890",
    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: 'user@example.com',
  phoneNumber: '+11234567890'
})
  .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("user@example.com")
    .setPhoneNumber("+11234567890");

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

Python

user = auth.create_user(
    uid='some-uid', email='user@example.com', phone_number='+15555550100')
print('Sucessfully created new user: {0}'.format(user.uid))

Go

params := (&auth.UserToCreate{}).
	UID(uid).
	Email("user@example.com").
	PhoneNumber("+15555550100")
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 = "user@example.com",
    PhoneNumber = "+11234567890",
};
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 字符串 用户未经哈希处理的原始密码。必须至少包含六个字符。
displayName 字符串 用户的显示名。
photoURL 字符串 用户照片的网址。
disabled 布尔值 用户是否已被停用。true 表示已被停用；false 表示已被启用。如果未提供，则默认值为 false。

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

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

更新用户

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

Node.js

admin.auth().updateUser(uid, {
  email: 'modifiedUser@example.com',
  phoneNumber: '+11234567890',
  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("user@example.com")
    .setPhoneNumber("+11234567890")
    .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='user@example.com',
    phone_number='+15555550100',
    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("user@example.com").
	EmailVerified(true).
	PhoneNumber("+15555550100").
	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 = "modifiedUser@example.com",
    PhoneNumber = "+11234567890",
    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 可清除用户的现有照片网址。如果设置 non-，则必须提供一个有效的网址。
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。

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

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

所列用户的密码哈希值

如果用于生成请求 OAuth 访问令牌的用户/服务帐号拥有 firebaseauth.configs.getHashConfig 权限，则该 API 还会针对密码用户返回由 Firebase 身份验证后端进行了哈希处理的 passwordSalt 和 passwordHash。否则，将不会设置 passwordHash 和 passwordSalt。

由于密码哈希的敏感性，Firebase Admin SDK 服务帐号默认不具有 firebaseauth.configs.getHashConfig 权限。您无法直接向用户/服务帐号添加权限，但您可以通过创建自定义 IAM 角色实现这一目的。

要创建自定义 IAM 角色，请执行以下操作：

  1. 在 GCP Console 中转到 IAM 和管理面板中的角色页面。
  2. 从页面顶部的下拉列表中选择您的项目。
  3. 点击创建角色
  4. 点击添加权限
  5. 搜索 firebaseauth.configs.getHashConfig 权限并选中该复选框。
  6. 点击添加
  7. 点击创建，完成新角色的创建。

在 IAM 页面中将创建的自定义角色添加到用户/服务帐号：

  1. 在 IAM 和管理面板中，选择 IAM
  2. 从成员列表中选择要修改的服务或用户帐号。
  3. 点击添加其他角色
  4. 搜索之前创建的新自定义角色。
  5. 点击保存。