以编程方式管理 Identity Platform 租户

本文档介绍如何使用 Identity Platform Admin SDK 以编程方式管理租户及其用户。您可以以管理员身份执行的某些活动包括：

用户管理：创建、更新、删除和列出特定租户的用户。
身份验证：识别应用的用户以限制他们对您自己服务器上资源的访问权限。
导入用户：从外部身份验证系统或其他 Identity Platform 项目或租户迁移用户。
使用自定义声明控制访问权限：为特定租户指定用户账号的自定义特性并实施各种访问权限控制策略，例如基于角色的访问权限控制。
用户会话管理：撤消用户对特定租户的刷新令牌。
电子邮件操作链接：为特定租户的用户生成用于密码重置、电子邮件链接登录和电子邮件验证的自定义电子邮件链接。
租户管理：为特定 Identity Platform 项目创建、列出、获取、更新、删除租户。
管理租户上的 OIDC 和 SAML 提供商：以编程方式管理指定租户上的 OIDC 和 SAML 配置。

准备工作

安装 Admin SDK for Node.js、Java、Python、Go 或 C#。
为您的 Google Cloud 项目启用多租户。

支持的功能

下表列出了多租户环境中每个 SDK 支持的功能：

功能	Node.js	Java	Python	Go	C#
自定义令牌创建
验证 ID 令牌
管理用户
使用自定义声明控制访问权限
撤消刷新令牌
导入用户
生成电子邮件操作链接
多重身份验证
管理 SAML/OIDC 提供方配置
会话 Cookie 管理

下表显示了您可以在特定于租户的上下文中使用 Admin SDK 和 Google Cloud 控制台配置的登录方法：

特征	Google Cloud 控制台	Admin SDK
电子邮件
OIDC
SAML
社交
手机
多重身份验证
匿名

租户管理

借助 Admin SDK，您可以在安全的服务器环境中以编程方式管理租户，而无需使用 Google Cloud 控制台。这包括创建、列出、获取、修改或删除租户的权限。

每个租户都包含各自的身份提供商、设置和用户组。您可以使用 admin.auth().tenantManager() 从父项目实例进行租户配置管理操作 (CRUD)。

租户配置提供有关租户的信息，例如其显示名、租户标识符和电子邮件身份验证配置。

租户的所有其他设置（例如列入白名单的网域和经过身份验证的重定向 URI）都继承自父项目。这些集群必须使用 Google Cloud 控制台进行管理。

对于特定于租户的用户管理、配置 OIDC/SAML 提供商和电子邮件链接生成等操作，您将需要目标租户的 TenantAwareAuth 实例（由唯一的 tenantId 标识）。

Node.js

const tenantManager = admin.auth().tenantManager();
const tenantAuth = tenantManager.authForTenant(tenantId);

Python

from firebase_admin import tenant_mgt

tenant_client = tenant_mgt.auth_for_tenant(tenant_id)index.py

Java

FirebaseAuth auth = FirebaseAuth.getInstance();
TenantManager tenantManager = auth.getTenantManager();
TenantAwareFirebaseAuth tenantAuth = tenantManager.getAuthForTenant(tenantId);FirebaseAuthSnippets.java

对用户管理 API，OIDC/SAML 提供商管理 API 和电子邮件链接生成 API 的所有调用都将在此租户的范围内（使用其 TenantAwareAuth 实例）。

获取现有租户

Admin SDK 提供 getTenant() 方法，该方法根据 tenantId（租户的唯一标识符）提取有关租户的信息。

Node.js

admin.auth().tenantManager().getTenant(tenantId)
  .then((tenant) => {
    console.log(tenant.toJSON());
  })
  .catch((error) => {
    // Handle error.
  });

Python

tenant = tenant_mgt.get_tenant(tenant_id)

print('Retreieved tenant:', tenant.tenant_id)index.py

Java

Tenant tenant = FirebaseAuth.getInstance().getTenantManager().getTenant(tenantId);
System.out.println("Retrieved tenant: " + tenant.getTenantId());FirebaseAuthSnippets.java

此方法会返回一个与 tenantId 对应的 Tenant 对象。如果提供的 tenantId 不属于现有租户，则返回的 Promise 会拒绝并显示 auth/tenant-not-found 错误。

请注意不要将 Tenant 实例与 TenantAwareAuth 对象混淆。authInstance.tenantManager().authForTenant() 返回一个扩展 BaseAuth 的 TenantAwareAuth 实例。Auth 类也会扩展 BaseAuth。BaseAuth 提供用于管理用户以及在不同上下文中配置 OIDC/SAML 提供商的 API。对于 Auth，上下文处于父项目级层。对于 TenantAwareAuth，上下文处于租户级层（租户由租户 ID 确定）。getTenant() 方法将生成基本租户信息（如租户 ID、显示名和电子邮件提供商设置），但要对该租户调用 API，您需要使用 authForTenant(tenantFromGetTenant.tenantId)。

创建租户

使用 createTenant() 方法创建新的租户配置：

Node.js

admin.auth().tenantManager().createTenant({
  displayName: 'myTenant1',
  emailSignInConfig: {
    enabled: true,
    passwordRequired: false, // Email link sign-in enabled.
  },
  // TODO: Remove if you don't want to enable multi-factor authentication.
  multiFactorConfig: {
    state: 'ENABLED',
    factorIds: ['phone']
  },
  // TODO: Remove if you don't want to register test phone numbers for use
  // with multi-factor authentication.
  testPhoneNumbers: {
    '+16505551234': '145678',
    '+16505550000': '123456'
  },
})
.then((createdTenant) => {
  console.log(createdTenant.toJSON());
})
.catch((error) => {
  // Handle error.
});

Python

tenant = tenant_mgt.create_tenant(
    display_name='myTenant1',
    enable_email_link_sign_in=True,
    allow_password_sign_up=True)

print('Created tenant:', tenant.tenant_id)index.py

Java

Tenant.CreateRequest request = new Tenant.CreateRequest()
    .setDisplayName("myTenant1")
    .setEmailLinkSignInEnabled(true)
    .setPasswordSignInAllowed(true);
Tenant tenant = FirebaseAuth.getInstance().getTenantManager().createTenant(request);
System.out.println("Created tenant: " + tenant.getTenantId());FirebaseAuthSnippets.java

您可以提供这些属性的任意组合：

属性	类型	说明
`displayName`	string	租户显示名。必须为 4-20 个字符，由字母、数字和连字符组成，且必须以字母开头。
`emailSignInConfig`	{ enable: boolean, passwordRequired: boolean }	电子邮件登录提供商配置。包括是否启用了电子邮件提供商，以及电子邮件登录是否要求密码。如果不要求，则可以使用密码登录或使用电子邮件链接登录。
`multiFactorConfig`	{ state: 'DISABLED' \| 'ENABLED', factorIds: string[] }	是否为租户启用了多重身份验证，以及可使用哪些因素类型。目前，唯一支持的因素 ID 是 `phone`。
`testPhoneNumbers`	{ string: string }	为测试目的而注册的手机号码及其关联的多重身份验证代码的地图。最多可包含 10 个条目。如要移除所有测试手机号码，请将此字段设置为 `null`。

该方法会为新创建的租户返回一个 Tenant 对象。

更新租户

使用 updateTenant() 方法修改现有租户的数据。您需要指定 tenantId 以及要为该租户更新的属性。

Node.js

admin.auth().tenantManager().updateTenant(tenantId, {
  displayName: 'updatedName',
  emailSignInConfig: {
    enabled: false, // Disable email provider.
  },
  // Enable multi-factor authentication.
  multiFactorConfig: {
    state: 'ENABLED',
    factorIds: ['phone']
  },
  // Register phone numbers for testing.
  testPhoneNumbers: {
    '+16505551234': '145678',
    '+16505550000': '123456'
  },
})
.then((updatedTenant) => {
  console.log(updatedTenant.toJSON());
})
.catch((error) => {
  // Handle error.
});

Python

tenant = tenant_mgt.update_tenant(
    tenant_id,
    display_name='updatedName',
    allow_password_sign_up=False) # Disable email provider

print('Updated tenant:', tenant.tenant_id)index.py

Java

Tenant.UpdateRequest request = new Tenant.UpdateRequest(tenantId)
    .setDisplayName("updatedName")
    .setPasswordSignInAllowed(false);
Tenant tenant = FirebaseAuth.getInstance().getTenantManager().updateTenant(request);
System.out.println("Updated tenant: " + tenant.getTenantId());FirebaseAuthSnippets.java

updateTenant() 接受与 createTenant() 相同的属性。所有属性均为可选属性。如果没有为属性指定值，则不会修改现有值。

完成后，该方法会返回更新后的 Tenant 对象。如果提供的 tenantId 不属于现有租户，则返回的 Promise 会拒绝并显示 auth/tenant-not-found 错误。

删除租户

您可以使用租户的 tenantId 来删除租户：

Node.js

admin.auth().tenantManager().deleteTenant(tenantId)
  .then(() => {
    // Tenant deleted.
  })
  .catch((error) => {
    // Handle error.
  });

Python

tenant_mgt.delete_tenant(tenant_id)index.py

Java

FirebaseAuth.getInstance().getTenantManager().deleteTenant(tenantId);FirebaseAuthSnippets.java

删除操作成功完成时，该方法会返回一个空的结果。如果提供的 tenantId 不属于现有租户，则返回的 Promise 会拒绝并显示 auth/tenant-not-found 错误。

列出租户

使用 listTenants() 方法列出现有租户：

Node.js

function listAllTenants(nextPageToken) {
  return admin.auth().tenantManager().listTenants(100, nextPageToken)
    .then((result) => {
      result.tenants.forEach((tenant) => {
        console.log(tenant.toJSON());
      });
      if (result.pageToken) {
        return listAllTenants(result.pageToken);
      }
    });
}

listAllTenants();

Python

for tenant in tenant_mgt.list_tenants().iterate_all():
    print('Retrieved tenant:', tenant.tenant_id)index.py

Java

ListTenantsPage page = FirebaseAuth.getInstance().getTenantManager().listTenants(null);
for (Tenant tenant : page.iterateAll()) {
  System.out.println("Retrieved tenant: " + tenant.getTenantId());
}FirebaseAuthSnippets.java

每批结果都包含租户列表和用于列出下一批租户的下一页令牌。列出所有租户后，不会返回 pageToken。

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

以编程方式管理 SAML 和 OIDC 提供商

Admin SDK 提供了用于在安全的服务器环境中以编程方式管理安全断言标记语言 (SAML) 2.0 和 OpenID Connect (OIDC) 提供商配置的 API。

通过 Admin SDK，您可以为特定租户管理这些提供商。这类似于管理项目级层 OIDC 和 SAML 提供商。

要为租户管理提供商，请先创建一个 TenantAwareAuth 实例：

Node.js

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Python

tenant_client = tenant_mgt.auth_for_tenant('TENANT-ID')index.py

Java

TenantAwareFirebaseAuth tenantAuth = FirebaseAuth.getInstance().getTenantManager()
    .getAuthForTenant("TENANT-ID");FirebaseAuthSnippets.java

然后，您可以执行常见操作，例如为租户创建、修改或删除提供商。

创建提供商

以下代码展示了如何为租户创建 SAML 提供商：

Node.js

const newConfig = {
  displayName: 'SAML provider name',
  enabled: true,
  providerId: 'saml.myProvider',
  idpEntityId: 'IDP_ENTITY_ID',
  ssoURL: 'https://example.com/saml/sso/1234/',
  x509Certificates: [
    '-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----',
    '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----'
  ],
  rpEntityId: 'RP_ENTITY_ID',
  // Using the default callback URL.
  callbackURL: 'https://project-id.firebaseapp.com/__/auth/handler'
};

tenantAuth.createProviderConfig(newConfig).then(() => {
  // Successful creation.
}).catch((error) => {
  // Handle error.
});

Python

saml = tenant_client.create_saml_provider_config(
    display_name='SAML provider name',
    enabled=True,
    provider_id='saml.myProvider',
    idp_entity_id='IDP_ENTITY_ID',
    sso_url='https://example.com/saml/sso/1234/',
    x509_certificates=[
        '-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----',
        '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
    ],
    rp_entity_id='P_ENTITY_ID',
    callback_url='https://project-id.firebaseapp.com/__/auth/handler')

print('Created new SAML provider:', saml.provider_id)index.py

Java

SamlProviderConfig.CreateRequest request = new SamlProviderConfig.CreateRequest()
    .setDisplayName("SAML provider name")
    .setEnabled(true)
    .setProviderId("saml.myProvider")
    .setIdpEntityId("IDP_ENTITY_ID")
    .setSsoUrl("https://example.com/saml/sso/1234/")
    .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----")
    .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----")
    .setRpEntityId("RP_ENTITY_ID")
    .setCallbackUrl("https://project-id.firebaseapp.com/__/auth/handler");
SamlProviderConfig saml = tenantAuth.createSamlProviderConfig(request);
System.out.println("Created new SAML provider: " + saml.getProviderId());FirebaseAuthSnippets.java

修改提供商

以下代码展示了如何修改提供商：

Node.js

const updatedConfig = {
  x509Certificates: [
    '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
    '-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----',
  ],
};
tenantAuth.updateProviderConfig('saml.myProvider', updatedConfig).then(() => {
  // Successful update.
}).catch((error) => {
  // Handle error.
});

Python

saml = tenant_client.update_saml_provider_config(
    'saml.myProvider',
    x509_certificates=[
        '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
        '-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----',
    ])

print('Updated SAML provider:', saml.provider_id)index.py

Java

SamlProviderConfig.UpdateRequest request =
    new SamlProviderConfig.UpdateRequest("saml.myProvider")
      .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----")
      .addX509Certificate("-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----");
SamlProviderConfig saml = tenantAuth.updateSamlProviderConfig(request);
System.out.println("Updated SAML provider: " + saml.getProviderId());FirebaseAuthSnippets.java

获取提供商

以下代码展示了如何使用提供商 ID 检索特定租户的提供商配置：

Node.js

tenantAuth.getProviderConfig('saml.myProvider').then((config) => {
  // Get display name and whether it is enabled.
  console.log(config.displayName, config.enabled);
}).catch((error) => {
  // Handle error. Common error is that config is not found.
});

Python

saml = tennat_client.get_saml_provider_config('saml.myProvider')
print(saml.display_name, saml.enabled)index.py

Java

SamlProviderConfig saml = tenantAuth.getSamlProviderConfig("saml.myProvider");

// Get display name and whether it is enabled.
System.out.println(saml.getDisplayName() + " " + saml.isEnabled());FirebaseAuthSnippets.java

列出提供商

以下代码展示了如何列出给定租户的提供商配置：

Node.js

// Returns 10 SAML provider configs starting from the specified nextPageToken offset.
tenantAuth.listProviderConfigs({type: 'saml', maxResults: 10, pageToken: 'nextPageToken'}).then((results) => {
  results.providerConfigs.forEach((config) => {
    console.log(config.providerId);
  });
  // To list the next 10:
  // return tenantAuth.listProviderConfigs(
  //     {type: 'saml', maxResults: 10, pageToken: results.pageToken});
}).catch((error) => {
  // Handle error.
});

Python

for saml in tenant_client.list_saml_provider_configs('nextPageToken').iterate_all():
    print(saml.provider_id)index.py

Java

ListProviderConfigsPage<SamlProviderConfig> page = tenantAuth.listSamlProviderConfigs(
    "nextPageToken");
for (SamlProviderConfig saml : page.iterateAll()) {
  System.out.println(saml.getProviderId());
}FirebaseAuthSnippets.java

删除提供商

以下代码展示了如何删除提供商：

Node.js

tenantAuth.deleteProviderConfig('saml.myProvider').then(() => {
  // Successful deletion.
}).catch((error) => {
  // Handle error.
});

Python

tenant_client.delete_saml_provider_config('saml.myProvider')index.py

Java

tenantAuth.deleteSamlProviderConfig("saml.myProvider");FirebaseAuthSnippets.java

OIDC 提供商的管理方式与项目级层 OIDC 提供商类似，但前者可以通过相应的 TenantAwareAuth 实例（而非 Auth 项目级层实例）进行管理。

如需了解详情，请参阅以编程方式管理 SAML 和 OIDC 提供商。

管理特定于租户的用户

您可以使用 Admin SDK 创建、检索、更新、删除和列出特定租户的所有用户。

首先，您需要相应租户的 TenantAwareAuth 实例：

Node.js

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Python

tenant_client = tenant_mgt.auth_for_tenant('TENANT-ID')index.py

Java

TenantAwareFirebaseAuth tenantAuth = FirebaseAuth.getInstance().getTenantManager()
    .getAuthForTenant("TENANT-ID");FirebaseAuthSnippets.java

获取用户

您可以使用 uid 标识符检索特定于租户的用户：

Node.js

tenantAuth.getUser(uid)
  .then((userRecord) => {
    // See the UserRecord reference documentation to learn more.
    console.log('Successfully fetched user data:', userRecord.toJSON());
    // Tenant ID will be reflected in userRecord.tenantId.
  })
  .catch((error) => {
    console.log('Error fetching user data:', error);
  });

Python

	# Get an auth.Client from tenant_mgt.auth_for_tenant()
    user = tenant_client.get_user(uid)
    print('Successfully fetched user data:', user.uid)index.py

Java

// Get an auth client from the firebase.App
UserRecord user = tenantAuth.getUser(uid);
System.out.println("Successfully fetched user data: " + user.getDisplayName());FirebaseAuthSnippets.java

您还可以根据用户的电子邮件地址识别用户：

Node.js

tenantAuth.getUserByEmail(email)
  .then((userRecord) => {
    // See the UserRecord reference documentation to learn more.
    console.log('Successfully fetched user data:', userRecord.toJSON());
    // Tenant ID will be reflected in userRecord.tenantId.
  })
  .catch((error) => {
    console.log('Error fetching user data:', error);
  });

Python

user = tenant_client.get_user_by_email(email)
print('Successfully fetched user data:', user.uid)index.py

Java

// Get an auth client from the firebase.App
UserRecord user = tenantAuth.getUserByEmail(email);
System.out.println("Successfully fetched user data: " + user.getDisplayName());FirebaseAuthSnippets.java

创建用户

使用 createUser() 方法为特定租户创建新用户。创建新用户时，可以选择提供 uid；如果未指定，则 Identity Platform 将预配一个唯一 ID。

Node.js

tenantAuth.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((userRecord) => {
  // See the UserRecord reference documentation to learn more.
  console.log('Successfully created new user:', userRecord.uid);
  // Tenant ID will be reflected in userRecord.tenantId.
})
.catch((error) => {
  console.log('Error creating new user:', error);
});

Python

user = tenant_client.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:', user.uid)index.py

Java

UserRecord.CreateRequest request = new UserRecord.CreateRequest()
    .setEmail("user@example.com")
    .setEmailVerified(false)
    .setPhoneNumber("+15555550100")
    .setPassword("secretPassword")
    .setDisplayName("John Doe")
    .setPhotoUrl("http://www.example.com/12345678/photo.png")
    .setDisabled(false);
UserRecord user = tenantAuth.createUser(request);
System.out.println("Successfully created user: " + user.getDisplayName());FirebaseAuthSnippets.java

修改用户

如需修改现有用户，您可以在 updateUser() 方法中指定用户的 uid：

Node.js

tenantAuth.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((userRecord) => {
  // See the UserRecord reference documentation to learn more.
  console.log('Successfully updated user', userRecord.toJSON());
})
.catch((error) => {
  console.log('Error updating user:', error);
});

Python

user = tenant_client.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:', user.uid)index.py

Java

UserRecord.UpdateRequest request = new UserRecord.UpdateRequest(uid)
    .setEmail("user@example.com")
    .setEmailVerified(true)
    .setPhoneNumber("+15555550100")
    .setPassword("newPassword")
    .setDisplayName("John Doe")
    .setPhotoUrl("http://www.example.com/12345678/photo.png")
    .setDisabled(true);
UserRecord user = tenantAuth.updateUser(request);
System.out.println("Successfully updated user: " + user.getDisplayName());FirebaseAuthSnippets.java

删除用户

以下示例展示了如何根据用户的 uid 删除用户：

Node.js

tenantAuth.deleteUser(uid)
  .then(() => {
    console.log('Successfully deleted user');
  })
  .catch((error) => {
    console.log('Error deleting user:', error);
  });

Python

tenant_client.delete_user(uid)
print('Successfully deleted user')index.py

Java

tenantAuth.deleteUser(uid);

System.out.println("Successfully deleted user: " + uid);FirebaseAuthSnippets.java

列出用户

如需批量检索特定租户的完整用户列表，请使用 listUsers() 方法。每个批次都包含一系列用户记录，如果还有其他用户，则还包含下一页令牌。

Node.js

function listAllUsers(nextPageToken) {
  // List batch of users, 1000 at a time.
  tenantAuth.listUsers(1000, nextPageToken)
    .then((listUsersResult) => {
      listUsersResult.users.forEach((userRecord) => {
        console.log('user', userRecord.toJSON());
        // Tenant ID will be reflected in userRecord.tenantId.
      });
      if (listUsersResult.pageToken) {
        // List next batch of users.
        listAllUsers(listUsersResult.pageToken);
      }
    })
    .catch((error) => {
      console.log('Error listing users:', error);
    });
}
// Start listing users from the beginning, 1000 at a time.
listAllUsers();

Python

	# Note, behind the scenes, the iterator will retrive 1000 users at a time through the API
    for user in tenant_client.list_users().iterate_all():
        print('User: ' + user.uid)

	# Iterating by pages of 1000 users at a time.
    page = tenant_client.list_users()
    while page:
        for user in page.users:
            print('User: ' + user.uid)
        # Get next batch of users.
        page = page.get_next_page()index.py

Java

// Note, behind the scenes, the ListUsersPage retrieves 1000 Users at a time
// through the API
ListUsersPage  page = tenantAuth.listUsers(null);
for (ExportedUserRecord user : page.iterateAll()) {
  System.out.println("User: " + user.getUid());
}

// Iterating by pages 100 users at a time.
page = tenantAuth.listUsers(null, 100);
while (page != null) {
  for (ExportedUserRecord user : page.getValues()) {
    System.out.println("User: " + user.getUid());
  }

  page = page.getNextPage();
}FirebaseAuthSnippets.java

如需了解详情，请参阅有关管理用户的 Admin SDK 文档。

导入用户

您可以使用 Admin SDK 以更高权限将用户批量导入特定租户。这样做有很多好处，例如可以从另一个 Identity Platform 产品、另一个租户或使用不同哈希算法的外部身份验证系统迁移用户。此外，您还可以直接批量导入使用联合提供商（例如 SAML 和 OIDC）和自定义声明的用户。

首先，获取相应租户的 TenantAwareAuth 实例：

Node.js

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Python

tenant_client = tenant_mgt.auth_for_tenant('TENANT-ID')index.py

Java

TenantAwareFirebaseAuth tenantAuth = FirebaseAuth.getInstance().getTenantManager()
    .getAuthForTenant("TENANT-ID");FirebaseAuthSnippets.java

您可以使用特定的哈希算法一次导入最多 1000 个用户。

Node.js

tenantAuth.importUsers([{
  uid: 'uid1',
  email: 'user1@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('password-hash-1'),
  // Must be provided in a byte buffer.
  passwordSalt: Buffer.from('salt1')
},
{
  uid: 'uid2',
  email: 'user2@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('password-hash-2'),
  // Must be provided in a byte buffer.
  passwordSalt: Buffer.from('salt2')

}], {
  hash: {
    algorithm: 'HMAC_SHA256',
    // Must be provided in a byte buffer.
    key: Buffer.from('secret')
  }
})
.then((results) => {
  results.errors.forEach(function(indexedError) {
  console.log('Error importing user ' + indexedError.index);
  });
})
.catch((error) => {
  console.log('Error importing users:', error);
});

Python

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'
    ),
]

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

Java

List<ImportUserRecord> users = new ArrayList<>();
users.add(ImportUserRecord.builder()
    .setUid("uid1")
    .setEmail("user1@example.com")
    .setPasswordHash("password-hash-1".getBytes())
    .setPasswordSalt("salt1".getBytes())
    .build());
users.add(ImportUserRecord.builder()
    .setUid("uid2")
    .setEmail("user2@example.com")
    .setPasswordHash("password-hash-2".getBytes())
    .setPasswordSalt("salt2".getBytes())
    .build());
UserImportHash hmacSha256 = HmacSha256.builder()
    .setKey("secret".getBytes())
    .build();
UserImportResult result = tenantAuth.importUsers(users, UserImportOptions.withHash(hmacSha256));

for (ErrorInfo error : result.getErrors()) {
  System.out.println("Failed to import user: " + error.getReason());
}FirebaseAuthSnippets.java

所有导入用户的 tenantId 都将被设置为 tenantAuth.tenantId。

您也可以将没有密码的用户导入特定租户。可以使用联合提供商和自定义声明导入这些用户。

Node、js

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

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 SAML provider
            auth.UserProvider(
                uid='saml-uid',
                email='johndoe@gmail.com',
                display_name='John Doe',
                photo_url='http://www.example.com/12345678/photo.png',
                provider_id='saml.acme'
            )
        ],
    ),
]
try:
    result = tenant_client.import_users(users)
    for err in result.errors:
        print('Failed to import user:', err.reason)
except exceptions.FirebaseError as error:
    print('Error importing users:', error)index.py

Java

List<ImportUserRecord> users = new ArrayList<>();
users.add(ImportUserRecord.builder()
    .setUid("some-uid")
    .setDisplayName("John Doe")
    .setEmail("johndoe@acme.com")
    .setPhotoUrl("https://www.example.com/12345678/photo.png")
    .setEmailVerified(true)
    .setPhoneNumber("+11234567890")
    // Set this user as admin.
    .putCustomClaim("admin", true)
    // User with SAML provider.
    .addUserProvider(UserProvider.builder()
        .setUid("saml-uid")
        .setEmail("johndoe@acme.com")
        .setDisplayName("John Doe")
        .setPhotoUrl("https://www.example.com/12345678/photo.png")
        .setProviderId("saml.acme")
        .build())
    .build());

UserImportResult result = tenantAuth.importUsers(users);

for (ErrorInfo error : result.getErrors()) {
  System.out.println("Failed to import user: " + error.getReason());
}FirebaseAuthSnippets.java

如需了解详情，请参阅 Admin SDK 文档中的导入用户。

身份验证

当 Identity Platform 客户端应用与自定义后端服务器通信时，需要在该服务器上识别当前登录的用户。要安全完成此操作，在成功登录后，使用安全的服务器连接发送用户的 ID 令牌。然后，服务器可以验证 ID 令牌的完整性和真实性。

Admin SDK 内置了为特定租户验证和解码 ID 令牌的方法。

用户从客户端成功登录特定租户后，使用 Client SDK 检索用户的 ID 令牌：

auth.tenantId = 'TENANT-ID';
auth.signInWithEmailAndPassword('user@example.com', 'password')
  .then((userCredential) => {
    return userCredential.user.getIdToken();
  })
  .then((idToken) => {
    // Send the ID token to server for verification. ID token should be scoped to TENANT-ID.
  });

在服务器上创建 TenantAwareAuth 实例：

Node.js

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Python

tenant_client = tenant_mgt.auth_for_tenant('TENANT-ID')index.py

Java

TenantAwareFirebaseAuth tenantAuth = FirebaseAuth.getInstance().getTenantManager()
    .getAuthForTenant("TENANT-ID");FirebaseAuthSnippets.java

然后，您可以为该特定租户验证 ID 令牌：

Node.js

// idToken comes from the client app
tenantAuth.verifyIdToken(idToken)
  .then((decodedToken) => {
    let uid = decodedToken.uid;
    // This should be set to TENANT-ID. Otherwise auth/mismatching-tenant-id error thrown.
    console.log(decodedToken.firebase.tenant);
    // ...
  }).catch((error) => {
    // Handle error
  });

服务器端资源可由多个具有不同访问权限级别的租户访问。由于在这种情况下可能提前不知道租户 ID，因此可以首先在项目级别验证 ID 令牌。

admin.auth().verifyIdToken(idToken)
  .then((decodedToken) => {
    if (decodedToken.firebase.tenant === 'TENANT-ID1') {
      // Allow appropriate level of access for TENANT-ID1.
    } else if (decodedToken.firebase.tenant === 'TENANT-ID2') {
      // Allow appropriate level of access for TENANT-ID2.
    } else {
      // Block access for all other tenants.
      throw new Error('Access not allowed.');
    }
  }).catch((error) => {
    // Handle error
  });

Python

	# id_token comes from the client app
    try:
        decoded_token = tenant_client.verify_id_token(id_token)

        # This should be set to TENANT-ID. Otherwise TenantIdMismatchError error raised.
        print('Verified ID token from tenant:', decoded_token['firebase']['tenant'])
    except tenant_mgt.TenantIdMismatchError:
        # Token revoked, inform the user to reauthenticate or signOut().
        passindex.py

Java

try {
  // idToken comes from the client app
  FirebaseToken token = tenantAuth.verifyIdToken(idToken);
  // TenantId on the FirebaseToken should be set to TENANT-ID.
  // Otherwise "tenant-id-mismatch" error thrown.
  System.out.println("Verified ID token from tenant: " + token.getTenantId());
} catch (FirebaseAuthException e) {
  System.out.println("error verifying ID token: " + e.getMessage());
}FirebaseAuthSnippets.java

如需了解详情，请参阅关于验证 ID 令牌的 Admin SDK 文档。

管理用户会话

Identity Platform 会话属于长期会话。每当用户登录时，系统都会在 Identity Platform 服务器上验证用户的凭据，然后交换短期 ID 令牌和长期刷新令牌。一个 ID 令牌持续一小时。刷新令牌永不过期，除非用户被停用、删除或发生重大账号更改（例如电子邮件或密码更新）。

在某些情况下，可能需要出于安全原因撤消用户的刷新令牌，例如，用户报告设备丢失或被盗、发现应用中的普遍性漏洞或大量有效令牌泄露。Admin SDK 提供了一个 API，用于撤消特定租户的特定用户的所有已颁发的刷新令牌。

首先，您需要一个 TenantAwareAuth 实例：

Node.js

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Python

tenant_client = tenant_mgt.auth_for_tenant('TENANT-ID')index.py

Java

TenantAwareFirebaseAuth tenantAuth = FirebaseAuth.getInstance().getTenantManager()
    .getAuthForTenant("TENANT-ID");FirebaseAuthSnippets.java

然后，您可以通过指定该用户的 uid 来撤消刷新令牌：

Node.js

// Revoke all refresh tokens for a specified user in a specified tenant for whatever reason.
// Retrieve the timestamp of the revocation, in seconds since the epoch.
tenantAuth.revokeRefreshTokens(uid)
  .then(() => {
    return tenantAuth.getUser(uid);
  })
  .then((userRecord) => {
    return new Date(userRecord.tokensValidAfterTime).getTime() / 1000;
  })
  .then((timestamp) => {
    console.log('Tokens revoked at: ', timestamp);
  });

Python

	# Revoke all refresh tokens for a specified user in a specified tenant for whatever reason.
	# Retrieve the timestamp of the revocation, in seconds since the epoch.
    tenant_client.revoke_refresh_tokens(uid)

    user = tenant_client.get_user(uid)
    # Convert to seconds as the auth_time in the token claims is in seconds.
    revocation_second = user.tokens_valid_after_timestamp / 1000
    print('Tokens revoked at: {0}'.format(revocation_second))index.py

Java

// Revoke all refresh tokens for a specified user in a specified tenant for whatever reason.
// Retrieve the timestamp of the revocation, in seconds since the epoch.
tenantAuth.revokeRefreshTokens(uid);

// accessing the user's TokenValidAfter
UserRecord user = tenantAuth.getUser(uid);

long timestamp = user.getTokensValidAfterTimestamp() / 1000;
System.out.println("the refresh tokens were revoked at: " + timestamp + " (UTC seconds)");FirebaseAuthSnippets.java

刷新令牌被撤消后，将无法为此用户颁发新的 ID 令牌，直到此用户重新进行身份验证。但是，现有 ID 令牌在其自然到期时间（一小时）之前将一直保持有效。

您可以通过指定可选的 checkRevoked 参数来验证未到期的有效 ID 令牌是否未被撤消；这会在验证令牌的完整性和真实性之后检查令牌是否被撤消。

Node.js

// Verify the ID token for a specific tenant while checking if the token is revoked by passing
// checkRevoked true.
let checkRevoked = true;
tenantAuth.verifyIdToken(idToken, checkRevoked)
  .then(payload => {
    // Token is valid.
  })
  .catch(error => {
    if (error.code == 'auth/id-token-revoked') {
      // Token has been revoked. Inform the user to re-authenticate or
      // signOut() the user.
    } else {
      // Token is invalid.
    }
  });

Python

	# Verify the ID token for a specific tenant while checking if the token is revoked.
    try:
        # Verify the ID token while checking if the token is revoked by
        # passing check_revoked=True.
        decoded_token = tenant_client.verify_id_token(id_token, check_revoked=True)
        # Token is valid and not revoked.
        uid = decoded_token['uid']
    except tenant_mgt.TenantIdMismatchError:
        # Token belongs to a different tenant.
        pass
    except auth.RevokedIdTokenError:
        # Token revoked, inform the user to reauthenticate or signOut().
        pass
    except auth.UserDisabledError:
        # Token belongs to a disabled user record.
        pass
    except auth.InvalidIdTokenError:
        # Token is invalid
        passindex.py

Java

// Verify the ID token for a specific tenant while checking if the token is revoked.
boolean checkRevoked = true;
try {
  FirebaseToken token = tenantAuth.verifyIdToken(idToken, checkRevoked);
  System.out.println("Verified ID token for: " + token.getUid());
} catch (FirebaseAuthException e) {
  if ("id-token-revoked".equals(e.getErrorCode())) {
    // Token is revoked. Inform the user to re-authenticate or signOut() the user.
  } else {
    // Token is invalid
  }
}FirebaseAuthSnippets.java

如需了解详情，请参阅有关管理会话的 Admin SDK 文档。

使用自定义声明控制访问权限

Admin SDK 支持为特定租户的用户账号指定自定义特性。通过这些特性，您可以实现不同的访问权限控制策略，例如基于角色的访问权限控制。这些特性可用于向用户授予不同的访问权限级别，这些访问权限级别通过应用的安全规则强制生效。

首先，获取相应租户的 TenantAwareAuth 实例：

Node.js

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Python

tenant_client = tenant_mgt.auth_for_tenant('TENANT-ID')index.py

Java

TenantAwareFirebaseAuth tenantAuth = FirebaseAuth.getInstance().getTenantManager()
    .getAuthForTenant("TENANT-ID");FirebaseAuthSnippets.java

由于自定义声明可能包含敏感数据，因此只能使用 Admin SDK 在特权服务器环境中进行设置。

Node.js

// Set admin privilege on the user corresponding to uid for a specific tenant.
tenantAuth.setCustomUserClaims(uid, {admin: true}).then(() => {
  // The new custom claims will propagate to the user's ID token the
  // next time a new one is issued.
});

Python

# Set admin privilege on the user corresponding to uid.
tenant_client.set_custom_user_claims(uid, {'admin': True})
# The new custom claims will propagate to the user's ID token the
# next time a new one is issued.index.py

Java

// Set admin privilege on the user corresponding to uid in a specific tenant.
Map<String, Object> claims = new HashMap<>();
claims.put("admin", true);
tenantAuth.setCustomUserClaims(uid, claims);
// The new custom claims will propagate to the user's ID token the
// next time a new one is issued.FirebaseAuthSnippets.java

用户下次登录现有会话或刷新其 ID 令牌时，新设置的自定义属性将显示在令牌载荷的顶级属性中。在前面的示例中，ID 令牌包含一个额外的声明：{admin: true}。

验证 ID 令牌并解码其载荷后，系统会检查其他自定义声明以实施访问权限控制。

Node.js

// Verify the ID token first.
tenantAuth.verifyIdToken(idToken).then((claims) => {
  if (claims.admin === true) {
    // Allow access to requested admin resource.
  }
});

Python

# Verify the ID token first.
claims = tenant_client.verify_id_token(id_token)
if claims['admin'] is True:
    # Allow access to requested admin resource.
    passindex.py

Java

// Verify the ID token first.
FirebaseToken token = tenantAuth.verifyIdToken(idToken);
if (Boolean.TRUE.equals(token.getClaims().get("admin"))) {
  //Allow access to requested admin resource.
}
// Verify the ID token first.
FirebaseToken decoded = tenantAuth.verifyIdToken(idToken);
if (Boolean.TRUE.equals(decoded.getClaims().get("admin"))) {
  // Allow access to requested admin resource.
}FirebaseAuthSnippets.java

特定租户的现有用户的自定义声明也作为用户记录中的属性显示。

Node.js

// Lookup the user associated with the specified uid.
tenantAuth.getUser(uid).then((userRecord) => {
  // The claims can be accessed on the user record.
  console.log(userRecord.customClaims.admin);
});

Python

	# Lookup the user associated with the specified uid.
    user = tenant_client.get_user(uid)

	# The claims can be accessed on the user record.
    print(user.custom_claims.get('admin'))index.py

Java

// Lookup the user associated with the specified uid in a specific tenant.
UserRecord user = tenantAuth.getUser(uid);
System.out.println(user.getCustomClaims().get("admin"));FirebaseAuthSnippets.java

如需了解详情，请参阅有关自定义声明的 Admin SDK 文档。

生成电子邮件操作链接

通过 Identity Platform Client SDK，您可以向特定租户的用户发送电子邮件，其中包含可用于密码重置、电子邮件地址验证和基于电子邮件的登录的链接。这些电子邮件由 Google 发送，可定制性有限。

通过 Admin SDK，您可以在特定租户的范围内以编程方式生成这些链接。

首先，获取相应租户的 TenantAwareAuth 实例：

Node.js

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Python

tenant_client = tenant_mgt.auth_for_tenant('TENANT-ID')index.py

Java

TenantAwareFirebaseAuth tenantAuth = FirebaseAuth.getInstance().getTenantManager()
    .getAuthForTenant("TENANT-ID");FirebaseAuthSnippets.java

以下示例展示了如何生成链接以为指定租户验证用户的电子邮件：

Node.js

const actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for
  // this URL must be whitelisted in the Cloud console.
  url: 'https://www.example.com/checkout?cartId=1234',
  // This must be true for email link sign-in.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12'
  },
  // FDL custom domain.
  dynamicLinkDomain: 'coolapp.page.link'
};

// Admin SDK API to generate the email verification link.
const userEmail = 'user@example.com';
tenantAuth.generateEmailVerificationLink(userEmail, actionCodeSettings)
  .then((link) => {
    // Construct email verification template, embed the link and send
    // using custom SMTP server.
    return sendCustomVerificationEmail(userEmail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Python

action_code_settings = auth.ActionCodeSettings(
    url='https://www.example.com/checkout?cartId=1234',
    handle_code_in_app=True,
    ios_bundle_id='com.example.ios',
    android_package_name='com.example.android',
    android_install_app=True,
    android_minimum_version='12',
    # FDL custom domain.
    dynamic_link_domain='coolapp.page.link',
)

email = 'user@example.com'
link = tenant_client.generate_email_verification_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)index.py

Java

ActionCodeSettings actionCodeSettings = ActionCodeSettings.builder()
    // URL you want to redirect back to. The domain (www.example.com) for
    // this URL must be whitelisted in the GCP Console.
    .setUrl("https://www.example.com/checkout?cartId=1234")
    // This must be true for email link sign-in.
    .setHandleCodeInApp(true)
    .setIosBundleId("com.example.ios")
    .setAndroidPackageName("com.example.android")
    .setAndroidInstallApp(true)
    .setAndroidMinimumVersion("12")
    // FDL custom domain.
    .setDynamicLinkDomain("coolapp.page.link")
    .build();

String link = tenantAuth.generateEmailVerificationLink(email, actionCodeSettings);

// Construct email verification template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link);FirebaseAuthSnippets.java

类似的机制可用于生成密码重置和基于电子邮件的登录链接。请注意，在租户上下文中生成电子邮件操作链接时，必须从链接中解析租户 ID 并在客户端 Auth 实例上设置租户 ID，然后才能应用代码。

const actionCodeUrl = firebase.auth.ActionCodeURL.parseLink(window.location.href);
// A one-time code, used to identify and verify a request.
const code = actionCodeUrl.code;
// The tenant ID being used to trigger the email action.
const tenantId = actionCodeUrl.tenantId;
auth.tenantId = tenantId;

// Apply the action code.
auth.applyActionCode(actionCode)
  .then(() => {
    // User's email is now verified.
  })
  .catch((error) => {
    // Handle error.
  });

如需了解详情，请参阅 Admin SDK 文档中的电子邮件操作链接。

错误消息

下表列出了您可能会遇到的常见错误消息。

错误代码	说明和解决步骤
`auth/billing-not-enabled`	此功能要求启用结算功能。
`auth/invalid-display-name`	DisplayName 字段必须是有效的字符串。
`auth/invalid-name`	提供的资源名称无效。
`auth/invalid-page-token`	页面令牌必须是有效的非空字符串。
`auth/invalid-project-id`	无效的父项目。父项目无法启用或未启用多租户。
`auth/invalid-tenant-id`	租户 ID 必须是有效的非空字符串。
`auth/mismatching-tenant-id`	用户租户 ID 与当前的 `TenantAwareAuth` 租户 ID 不匹配。
`auth/missing-display-name`	正在创建或修改的资源缺少有效的显示名称。
`auth/insufficient-permission`	用户没有足够的权限来访问所请求的资源或运行特定租户操作。
`auth/quota-exceeded`	已超出指定操作的项目配额。
`auth/tenant-not-found`	没有与所提供的标识符对应的租户。
`auth/unsupported-tenant-operation`	多租户上下文中不支持此操作。
`auth/invalid-testing-phone-number`	提供无效的测试手机号码或无效的测试代码。
`auth/test-phone-number-limit-exceeded`	测试手机号码和代码对的数量超出了所允许的上限。