在多租户环境中对用户进行身份验证

本文档介绍如何在多租户 Identity Platform 环境中对用户进行身份验证。

准备工作

请确保您已为项目启用了多租户并配置了租户。如需了解具体方法，请参阅多租户使用入门。

您还需要将 Client SDK 添加到您的应用中：

  1. 前往 Google Cloud 控制台中的 Identity Platform 页面。
    转到 Identity Platform 用户页面

  2. 点击右上角的应用设置详情。

  3. 将代码复制到您的 Web 应用中。例如：

Web 版本 9

import { initializeApp } from "firebase/app";

const firebaseConfig = {
  apiKey: "...",
  // By default, authDomain is '[YOUR_APP].firebaseapp.com'.
  // You may replace it with a custom domain.
  authDomain: '[YOUR_CUSTOM_DOMAIN]'
};
const firebaseApp = initializeApp(firebaseConfig);
auth_init_custom_domain.js

Web 版本 8

firebase.initializeApp({
  apiKey: '...',
  // By default, authDomain is '[YOUR_APP].firebaseapp.com'.
  // You may replace it with a custom domain.
  authDomain: '[YOUR_CUSTOM_DOMAIN]'
});
index.js

使用租户登录

要登录到租户，需要将租户 ID 传递给 auth 对象。请注意，重新加载页面时不会保留 tenantId。

Web 版本 9

import { getAuth } from "firebase/auth";
const auth = getAuth();
const tenantId = "TENANT_ID1";
auth.tenantId = tenantId;
multitenant_set_tenant.js

Web 版本 8

const tenantId = "TENANT_ID1";
firebase.auth().tenantId = tenantId;
multi-tenancy.js

此 auth 实例以后发出的任何登录请求都将包含该租户 ID（在以上示例中为 TENANT_ID1），除非您更改或重置租户 ID。

您可以使用单个或多个 auth 实例处理多个租户。

如需使用单个 auth 实例，则每当您要在租户之间切换时，修改 tenantId 属性即可。要还原为项目级 IdP，请将 tenantId 设置为 null：

Web 版本 9

// One Auth instance
// Switch to tenant1
auth.tenantId = "TENANT_ID1";
// Switch to tenant2
auth.tenantId = "TENANT_ID2";
// Switch back to project level IdPs
auth.tenantId = null;
multitenant_switch_tenant.js

Web 版本 8

// One Auth instance
// Switch to tenant1
firebase.auth().tenantId = "TENANT_ID1";
// Switch to tenant2
firebase.auth().tenantId = "TENANT_ID2";
// Switch back to project level IdPs
firebase.auth().tenantId = null;
multi-tenancy.js

如需使用多个实例，请为每个租户创建一个新的 auth 实例并为其分配不同的 ID：

Web 版本 9

// Multiple Auth instances
import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";
const firebaseApp1 = initializeApp(firebaseConfig1, 'app1_for_tenantId1');
const firebaseApp2 = initializeApp(firebaseConfig2, 'app2_for_tenantId2');

const auth1 = getAuth(firebaseApp1);
const auth2 = getAuth(firebaseApp2);

auth1.tenantId = "TENANT_ID1";
auth2.tenantId = "TENANT_ID2";
multitenant_switch_tenant_multiinstance.js

Web 版本 8

// Multiple Auth instances
firebase.initializeApp(config, 'app1_for_tenantId1');
firebase.initializeApp(config, 'app2_for_tenantId2');

const auth1 = firebase.app('app1').auth();
const auth2 = firebase.app('app2').auth();

auth1.tenantId = "TENANT_ID1";
auth2.tenantId = "TENANT_ID2";
multi-tenancy.js

通过租户登录后，系统将返回租户用户并将 user.tenantId 设置为该租户。请注意，如果您以后在 auth 实例上切换 tenantId，currentUser 属性不会发生变化；它仍将指向与之前的租户相同的用户。

Web 版本 9

import { signInWithEmailAndPassword, onAuthStateChanged } from "firebase/auth";
// Switch to TENANT_ID1
auth.tenantId = 'TENANT_ID1';

// Sign in with tenant
signInWithEmailAndPassword(auth, email, password)
  .then((userCredential) => {
    // User is signed in.
    const user = userCredential.user;
    // user.tenantId is set to 'TENANT_ID1'.
    // Switch to 'TENANT_ID2'.
    auth.tenantId = 'TENANT_ID2';
    // auth.currentUser still points to the user.
    // auth.currentUser.tenantId is 'TENANT_ID1'.
  });

// You could also get the current user from Auth state observer.
onAuthStateChanged(auth, (user) => {
  if (user) {
    // User is signed in.
    // user.tenantId is set to 'TENANT_ID1'.
  } else {
    // No user is signed in.
  }
});
multitenant_signin_password_demo.js

Web 版本 8

// Switch to TENANT_ID1
firebase.auth().tenantId = 'TENANT_ID1';

// Sign in with tenant
firebase.auth().signInWithEmailAndPassword(email, password)
  .then((result) => {
    const user = result.user;
    // user.tenantId is set to 'TENANT_ID1'.
    // Switch to 'TENANT_ID2'.
    firebase.auth().tenantId = 'TENANT_ID2';
    // firebase.auth().currentUser still point to the user.
    // firebase.auth().currentUser.tenantId is 'TENANT_ID1'.
  });

// You could also get the current user from Auth state observer.
firebase.auth().onAuthStateChanged((user) => {
  if (user) {
    // User is signed in.
    // user.tenantId is set to 'TENANT_ID1'.
  } else {
    // No user is signed in.
  }
});
multi-tenancy.js

电子邮件/密码账号

以下示例展示了如何注册新用户：

Web 版本 9

import { createUserWithEmailAndPassword } from "firebase/auth";
auth.tenantId = 'TENANT_ID';

createUserWithEmailAndPassword(auth, email, password)
  .then((userCredential) => {
    // User is signed in.
    // userCredential.user.tenantId is 'TENANT_ID'.
  }).catch((error) => {
    // Handle / display error.
    // ...
  });
multitenant_signup_password.js

Web 版本 8

firebase.auth().tenantId = 'TENANT_ID';

firebase.auth().createUserWithEmailAndPassword(email, password)
  .then((result) => {
    // result.user.tenantId is 'TENANT_ID'.
  }).catch((error) => {
    // Handle error.
  });
multi-tenancy.js

让现有用户登录：

Web 版本 9

import { signInWithEmailAndPassword } from "firebase/auth";
auth.tenantId = 'TENANT_ID';

signInWithEmailAndPassword(auth, email, password)
  .then((userCredential) => {
    // User is signed in.
    // userCredential.user.tenantId is 'TENANT_ID'.
  }).catch((error) => {
    // Handle / display error.
    // ...
  });
multitenant_signin_password.js

Web 版本 8

firebase.auth().tenantId = 'TENANT_ID';

firebase.auth().signInWithEmailAndPassword(email, password)
  .then((result) => {
    // result.user.tenantId is 'TENANT_ID'.
  }).catch((error) => {
    // Handle error.
  });
multi-tenancy.js

SAML

如需通过 SAML 提供商登录，请使用 Google Cloud 控制台中的提供商 ID 实例化 SAMLAuthProvider 实例：

Web 版本 9

import { SAMLAuthProvider } from "firebase/auth";

const provider = new SAMLAuthProvider("saml.myProvider");
auth_saml_provider_create.js

Web 版本 8

const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');
saml.js

然后，您可以使用弹出式窗口或重定向流程登录 SAML 提供商。

  • 弹出式窗口

    Web 版本 9

    import { signInWithPopup } from "firebase/auth";
// Switch to TENANT_ID1.
auth.tenantId = 'TENANT_ID1';

// Sign-in with popup.
signInWithPopup(auth, provider)
  .then((userCredential) => {
    // User is signed in.
    const user = userCredential.user;
    // user.tenantId is set to 'TENANT_ID1'.
    // Provider data available from the result.user.getIdToken()
    // or from result.user.providerData
  })
  .catch((error) => {
    // Handle / display error.
    // ...
  });
    multitenant_signin_saml_popup.js

    Web 版本 8

    // Switch to TENANT_ID1.
firebase.auth().tenantId = 'TENANT_ID1';

// Sign-in with popup.
firebase.auth().signInWithPopup(provider)
  .then((result) => {
    // User is signed in.
    // tenant ID is available in result.user.tenantId.
    // Identity provider data is available in result.additionalUserInfo.profile.
  })
  .catch((error) => {
    // Handle error.
  });
    multi-tenancy.js

  • 重定向

    Web 版本 9

    import { signInWithRedirect, getRedirectResult } from "firebase/auth";
// Switch to TENANT_ID1.
auth.tenantId = 'TENANT_ID1';

// Sign-in with redirect.
signInWithRedirect(auth, provider);

// After the user completes sign-in and returns to the app, you can get
// the sign-in result by calling getRedirectResult. However, if they sign out
// and sign in again with an IdP, no tenant is used.
getRedirectResult(auth)
  .then((result) => {
    // User is signed in.
    // The tenant ID available in result.user.tenantId.
    // Provider data available from the result.user.getIdToken()
    // or from result.user.providerData
  })
  .catch((error) => {
    // Handle / display error.
    // ...
  });
    multitenant_signin_saml_redirect.js

    Web 版本 8

    // Switch to TENANT_ID1.
firebase.auth().tenantId = 'TENANT_ID1';

// Sign-in with redirect.
firebase.auth().signInWithRedirect(provider);

// After the user completes sign-in and returns to the app, you can get
// the sign-in result by calling getRedirectResult. However, if they sign out
// and sign in again with an IdP, no tenant is used.
firebase.auth().getRedirectResult()
  .then((result) => {
    // User is signed in.
    // The tenant ID available in result.user.tenantId.
    // Identity provider data is available in result.additionalUserInfo.profile.
  })
  .catch((error) => {
    // Handle error.
  });
    multi-tenancy.js

在这两种情况下，请务必在 auth 实例上设置正确的租户 ID。

要启动身份验证流程，请向用户显示一个要求其提供电子邮件地址的界面，然后调用 sendSignInLinkToEmail 向用户发送身份验证链接。在发送电子邮件之前，请务必在 auth 实例上设置正确的租户 ID。

Web 版本 9

import { sendSignInLinkToEmail } from "firebase/auth";
// Switch to TENANT_ID1
auth.tenantId = 'TENANT_ID1';

sendSignInLinkToEmail(auth, email, actionCodeSettings)
  .then(() => {
    // The link was successfully sent. Inform the user.
    // Save the email locally so you don't need to ask the user for it again
    // if they open the link on the same device.
    window.localStorage.setItem('emailForSignIn', email);
  })
  .catch((error) => {
    // Handle / display error.
    // ...
  });
multitenant_send_emaillink.js

Web 版本 8

// Switch to TENANT_ID1
firebase.auth().tenantId = 'TENANT_ID1';

firebase.auth().sendSignInLinkToEmail(email, actionCodeSettings)
  .then(() => {
    // The link was successfully sent. Inform the user.
    // Save the email locally so you don't need to ask the user for it again
    // if they open the link on the same device.
    window.localStorage.setItem('emailForSignIn', email);
  })
  .catch((error) => {
    // Some error occurred, you can inspect the code: error.code
  });
multi-tenancy.js

要在着陆页上完成登录，请首先解析电子邮件链接中的租户 ID，然后在 auth 实例上设置租户 ID。然后，使用用户的电子邮件和包含一次性验证码的实际电子邮件链接调用 signInWithEmailLink。

Web 版本 9

import { isSignInWithEmailLink, parseActionCodeURL, signInWithEmailLink } from "firebase/auth";
if (isSignInWithEmailLink(auth, window.location.href)) {
  const actionCodeUrl = parseActionCodeURL(window.location.href);
  if (actionCodeUrl.tenantId) {
    auth.tenantId = actionCodeUrl.tenantId;
  }
  let email = window.localStorage.getItem('emailForSignIn');
  if (!email) {
    // User opened the link on a different device. To prevent session fixation
    // attacks, ask the user to provide the associated email again. For example:
    email = window.prompt('Please provide your email for confirmation');
  }
  // The client SDK will parse the code from the link for you.
  signInWithEmailLink(auth, email, window.location.href)
    .then((result) => {
      // User is signed in.
      // tenant ID available in result.user.tenantId.
      // Clear email from storage.
      window.localStorage.removeItem('emailForSignIn');
    });
}
multitenant_signin_emaillink.js

Web 版本 8

if (firebase.auth().isSignInWithEmailLink(window.location.href)) {
  const actionCodeUrl = firebase.auth.ActionCodeURL.parseLink(window.location.href);
  if (actionCodeUrl.tenantId) {
    firebase.auth().tenantId = actionCodeUrl.tenantId;
  }
  let email = window.localStorage.getItem('emailForSignIn');
  if (!email) {
    // User opened the link on a different device. To prevent session fixation
    // attacks, ask the user to provide the associated email again. For example:
    email = window.prompt('Please provide your email for confirmation');
  }
  firebase.auth().signInWithEmailLink(email, window.location.href)
    .then((result) => {
      // User is signed in.
      // tenant ID available in result.user.tenantId.
    });
}
multi-tenancy.js

创建自定义令牌

创建多租户感知自定义令牌与创建常规自定义令牌相同；只要在 auth 实例上设置了正确的租户 ID，顶级 tenant_id 声明就会被添加到生成的 JWT。如需详细了解如何创建和使用自定义令牌，请参阅创建自定义令牌。

以下示例展示了如何使用 Admin SDK 创建自定义令牌：

Web 版本 9

// Ensure you're using a tenant-aware auth instance
const tenantManager = admin.auth().tenantManager();
const tenantAuth = tenantManager.authForTenant('TENANT_ID1');

// Create a custom token in the usual manner
tenantAuth.createCustomToken(uid)
  .then((customToken) => {
    // Send token back to client
  })
  .catch((error) => {
    console.log('Error creating custom token:', error);
  });
multitenant_create_custom_token.js

Web 版本 8

// Ensure you're using a tenant-aware auth instance
const tenantManager = admin.auth().tenantManager();
const tenantAuth = tenantManager.authForTenant('TENANT_ID1');

// Create a custom token in the usual manner
tenantAuth.createCustomToken(uid)
  .then((customToken) => {
    // Send token back to client
  })
  .catch((error) => {
    console.log('Error creating custom token:', error);
  });
multi-tenancy.js

以下代码演示了如何使用自定义令牌登录：

Web 版本 9

import { signInWithCustomToken } from "firebase/auth";
auth.tenantId = 'TENANT_ID1';

signInWithCustomToken(auth, token)
  .catch((error) => {
    // Handle / display error.
    // ...
  });
multitenant_signin_custom_token.js

Web 版本 8

firebase.auth().tenantId = 'TENANT_ID1';

firebase.auth().signInWithCustomToken(token)
  .catch((error) => {
    // Handle Errors here.
    const errorCode = error.code;
    const errorMessage = error.message;
    // ...
  });
multi-tenancy.js

请注意，如果租户 ID 不匹配，signInWithCustomToken() 方法将失败。

关联多租户用户凭据

您可以将其他类型的凭据与现有的多租户用户关联。例如，如果用户之前已通过一个租户中的 SAML 提供商进行身份验证，您可以向用户的现有账号添加电子邮件/密码登录，以便他们可以使用任一方法登录租户。

Web 版本 9

import { signInWithPopup, EmailAuthProvider, linkWithCredential, SAMLAuthProvider, signInWithCredential } from "firebase/auth";
// Switch to TENANT_ID1
auth.tenantId = 'TENANT_ID1';

// Sign-in with popup
signInWithPopup(auth, provider)
  .then((userCredential) => {
    // Existing user with e.g. SAML provider.
    const prevUser = userCredential.user;
    const emailCredential =
      EmailAuthProvider.credential(email, password);
    return linkWithCredential(prevUser, emailCredential)
      .then((linkResult) => {
        // Sign in with the newly linked credential
        const linkCredential = SAMLAuthProvider.credentialFromResult(linkResult);
        return signInWithCredential(auth, linkCredential);
      })
      .then((signInResult) => {
        // Handle sign in of merged user
        // ...
      });
  })
  .catch((error) => {
    // Handle / display error.
    // ...
  });
multitenant_account_linking.js

Web 版本 8

// Switch to TENANT_ID1
firebase.auth().tenantId = 'TENANT_ID1';

// Sign-in with popup
firebase.auth().signInWithPopup(provider)
  .then((result) => {
    // Existing user with e.g. SAML provider.
    const user = result.user;
    const emailCredential =
      firebase.auth.EmailAuthProvider.credential(email, password);
    return user.linkWithCredential(emailCredential);
  })
  .then((linkResult) => {
    // The user can sign in with both SAML and email/password now.
  });
multi-tenancy.js

关联现有的多租户用户或重新验证其身份时，auth.tenantId 会被忽略；请使用 user.tenantId 指定要使用的租户。这也适用于其他用户管理 API，如 updateProfile 和 updatePassword。

处理“account-exists-with-different-credential”错误

如果您在 Google Cloud 控制台中启用了关联使用相同电子邮件地址的账号设置，当用户尝试使用一个提供商（例如 Google）中已存在的电子邮件登录另一个提供商（例如 SAML）时，系统会抛出错误 auth/account-exists-with-different-credential（以及 AuthCredential 对象）。

要通过所需的提供商完成登录，用户必须先登录现有提供商 (Google)，然后关联至之前的 AuthCredential (SAML)。

您可以使用弹出式窗口或重定向流程来处理此错误。

  • 弹出式通知

    Web 版本 9

    import { signInWithPopup, fetchSignInMethodsForEmail, linkWithCredential } from "firebase/auth";
// Step 1.
// User tries to sign in to the SAML provider in that tenant.
auth.tenantId = 'TENANT_ID';
signInWithPopup(auth, samlProvider)
  .catch((error) => {
    // An error happened.
    if (error.code === 'auth/account-exists-with-different-credential') {
      // Step 2.
      // User's email already exists.
      // The pending SAML credential.
      const pendingCred = error.credential;
      // The credential's tenantId if needed: error.tenantId
      // The provider account's email address.
      const email = error.customData.email;
      // Get sign-in methods for this email.
      fetchSignInMethodsForEmail(email, auth)
        .then((methods) => {
          // Step 3.
          // Ask the user to sign in with existing Google account.
          if (methods[0] == 'google.com') {
            signInWithPopup(auth, googleProvider)
              .then((result) => {
                // Step 4
                // Link the SAML AuthCredential to the existing user.
                linkWithCredential(result.user, pendingCred)
                  .then((linkResult) => {
                    // SAML account successfully linked to the existing
                    // user.
                    goToApp();
                  });
              });
          }
        });
    }
  });
    multitenant_account_exists_popup.js

    Web 版本 8

    // Step 1.
// User tries to sign in to the SAML provider in that tenant.
firebase.auth().tenantId = 'TENANT_ID';
firebase.auth().signInWithPopup(samlProvider)
  .catch((error) => {
    // An error happened.
    if (error.code === 'auth/account-exists-with-different-credential') {
      // Step 2.
      // User's email already exists.
      // The pending SAML credential.
      const pendingCred = error.credential;
      // The credential's tenantId if needed: error.tenantId
      // The provider account's email address.
      const email = error.email;
      // Get sign-in methods for this email.
      firebase.auth().fetchSignInMethodsForEmail(email)
        .then((methods) => {
          // Step 3.
          // Ask the user to sign in with existing Google account.
          if (methods[0] == 'google.com') {
            firebase.auth().signInWithPopup(googleProvider)
              .then((result) => {
                // Step 4
                // Link the SAML AuthCredential to the existing user.
                result.user.linkWithCredential(pendingCred)
                  .then((linkResult) => {
                    // SAML account successfully linked to the existing
                    // user.
                    goToApp();
                  });
              });
          }
        });
    }
  });
    multi-tenancy.js

  • 重定向

    使用 signInWithRedirect 时，在完成重定向流程时，将在 getRedirectResult 中引发 auth/account-exists-with-different-credential 错误。

    错误对象包含属性 error.tenantId。由于 auth 实例上的租户 ID 在重定向后不会保留，因此您需要在 auth 实例上设置错误对象中的租户 ID。

    以下示例展示了如何处理错误：

    Web 版本 9

    import { signInWithRedirect, getRedirectResult, fetchSignInMethodsForEmail, linkWithCredential } from "firebase/auth";
// Step 1.
// User tries to sign in to SAML provider.
auth.tenantId = 'TENANT_ID';
signInWithRedirect(auth, samlProvider);
var pendingCred;
// Redirect back from SAML IDP. auth.tenantId is null after redirecting.
getRedirectResult(auth).catch((error) => {
  if (error.code === 'auth/account-exists-with-different-credential') {
    // Step 2.
    // User's email already exists.
    const tenantId = error.tenantId;
    // The pending SAML credential.
    pendingCred = error.credential;
    // The provider account's email address.
    const email = error.customData.email;
    // Need to set the tenant ID again as the page was reloaded and the
    // previous setting was reset.
    auth.tenantId = tenantId;
    // Get sign-in methods for this email.
    fetchSignInMethodsForEmail(auth, email)
      .then((methods) => {
        // Step 3.
        // Ask the user to sign in with existing Google account.
        if (methods[0] == 'google.com') {
          signInWithRedirect(auth, googleProvider);
        }
      });
  }
});

// Redirect back from Google. auth.tenantId is null after redirecting.
getRedirectResult(auth).then((result) => {
  // Step 4
  // Link the SAML AuthCredential to the existing user.
  // result.user.tenantId is 'TENANT_ID'.
  linkWithCredential(result.user, pendingCred)
    .then((linkResult) => {
      // SAML account successfully linked to the existing
      // user.
      goToApp();
    });
});
    multitenant_account_exists_redirect.js

    Web 版本 8

    // Step 1.
// User tries to sign in to SAML provider.
firebase.auth().tenantId = 'TENANT_ID';
firebase.auth().signInWithRedirect(samlProvider);
var pendingCred;
// Redirect back from SAML IDP. auth.tenantId is null after redirecting.
firebase.auth().getRedirectResult().catch((error) => {
  if (error.code === 'auth/account-exists-with-different-credential') {
    // Step 2.
    // User's email already exists.
    const tenantId = error.tenantId;
    // The pending SAML credential.
    pendingCred = error.credential;
    // The provider account's email address.
    const email = error.email;
    // Need to set the tenant ID again as the page was reloaded and the
    // previous setting was reset.
    firebase.auth().tenantId = tenantId;
    // Get sign-in methods for this email.
    firebase.auth().fetchSignInMethodsForEmail(email)
      .then((methods) => {
        // Step 3.
        // Ask the user to sign in with existing Google account.
        if (methods[0] == 'google.com') {
          firebase.auth().signInWithRedirect(googleProvider);
        }
      });
  }
});

// Redirect back from Google. auth.tenantId is null after redirecting.
firebase.auth().getRedirectResult().then((result) => {
  // Step 4
  // Link the SAML AuthCredential to the existing user.
  // result.user.tenantId is 'TENANT_ID'.
  result.user.linkWithCredential(pendingCred)
    .then((linkResult) => {
      // SAML account successfully linked to the existing
      // user.
      goToApp();
    });
});
    multi-tenancy.js

停用最终用户账号创建和删除功能

在某些情况下，您希望管理员创建用户账号，而不是通过用户操作创建账号。在这些情况下，您可以通过我们的 REST API 停用用户操作：

curl --location --request PATCH 'https://identitytoolkit.googleapis.com/v2/projects/PROJECT_ID/tenants/TENANT_ID?updateMask=client' \
  --header 'Authorization: Bearer AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "client": {
        "permissions": {
            "disabled_user_signup": true,
            "disabled_user_deletion": true
        }
    }
}'

替换以下内容：

  • AUTH_TOKEN：身份验证令牌。
  • PROJECT_ID：项目 ID。
  • TENANT_ID：租户 ID。

后续步骤