进行身份验证并连接到数据库

本页介绍了如何进行身份验证并连接到具有 MongoDB 兼容性的 Firestore 数据库。

连接要求

具有 MongoDB 兼容性的 Firestore 客户端需要满足以下要求：

  • 驱动程序必须以 load balanced 模式连接。这样可以防止驱动程序尝试了解它们要连接到的确切服务器拓扑。
  • 驾驶员必须启用 SSL 才能连接。
  • 驱动程序必须停用可重试写入。与 MongoDB 兼容的 Firestore 目前不支持可重试写入。

检索连接字符串

数据库连接字符串取决于数据库的 UID、数据库的位置和身份验证机制。以下说明介绍了如何构成连接字符串。

确切的连接字符串取决于身份验证机制，但基本连接字符串采用以下格式：

mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false

您可以通过以下任一方式获取基本连接字符串：

控制台

  1. 在 Google Cloud 控制台中，前往数据库页面。

    前往“数据库”

  2. 在数据库列表中，点击相关数据库的数据库 ID。
  3. Explorer 面板会显示基本连接字符串。复制并使用此连接字符串连接到数据库。
gcloud

使用 gcloud firestore database describe 检索 UID 和位置信息：

gcloud firestore databases describe \
--database=DATABASE_ID \
--format='yaml(locationId, uid)'

将 DATABASE_ID 替换为相应的数据库 ID。

输出中包含数据库的位置和 UID。使用这些信息构建基本连接字符串。

使用基本连接字符串和以下方法之一进行身份验证并连接到数据库：

使用用户名和密码 (SCRAM) 进行连接

请按照以下步骤为数据库创建用户凭据并连接到数据库。

准备工作

如需获得创建用户所需的权限，请让您的管理员为您授予数据库的 userCredsAdmin (roles/datastore.userCredsAdmin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建用户并连接到数据库

如需为具有 MongoDB 兼容性的 Firestore 数据库创建用户，请使用以下方法之一：

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，前往数据库页面。

    前往“数据库”

  2. 从数据库列表中选择一个数据库。
  3. 在导航菜单中，点击身份验证。
  4. 点击 Add User（添加用户）。
  5. 输入用户名。
  6. 为新用户选择一个角色。
  7. 点击添加。

    新用户的密码将显示在确认对话框中。

gcloud CLI
  1. 如需使用 SCRAM 进行身份验证，您必须先创建用户凭据。使用 gcloud alpha firestore user-creds 命令： 
    gcloud alpha firestore user-creds create USERNAME --database=DATABASE_ID
     替换以下内容：
    • USERNAME：要创建的用户名。
    • DATABASE_ID：数据库 ID。

    此命令的输出内容包括用户的密码。

    输出类似以下内容：

    name: projects/PROJECT_NAME/databases/DATABASE_ID/userCreds/USERNAME
resourceIdentity:
  principal: principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USERNAME
securePassword: PASSWORD

  2. 默认情况下，此新用户凭据没有任何权限。如需对数据库拥有读写权限，请为此特定数据库添加 roles/datastore.user 角色：

    gcloud projects add-iam-policy-binding PROJECT_NAME \
--member='principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USERNAME' \
--role=roles/datastore.user \
--condition='expression=resource.name == "projects/PROJECT_NAME/databases/DATABASE_ID",title="CONDITION_TITLE"'
     替换以下内容：

使用以下连接字符串通过 SCRAM 连接到数据库：

mongodb://USERNAME:PASSWORD@UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false

替换以下内容：

  • USERNAME：用户名。
  • PASSWORD：您为此用户生成的密码。
  • UID：数据库的 UID。
  • LOCATION：数据库的位置。
  • DATABASE_ID：数据库 ID。

连接到 Google Auth 库

以下代码示例使用Google Cloud 标准 OAuth 库注册 OIDC 回调处理程序。

借助此库，您可以使用多种不同类型的身份验证（应用默认凭据、工作负载身份联合）。

这需要将身份验证库添加为依赖项：

// Maven
<dependency>
  <groupId>com.google.auth</groupId>
  <artifactId>google-auth-library-oauth2-http</artifactId>
  <version>1.19.0</version>
</dependency>

// Gradle
implementation 'com.google.auth:google-auth-library-oauth2-http:1.19.0'

以下代码示例演示了如何连接：

val db = MongoClients.create(
    connectIgnite(
      "DATABASE_UID",
      "LOCATION"
    ).build()
  ).getDatabase("DATABASE_ID")


/**
 * Creates a connection to a Firestore with MongoDB Compatibility database.
 * @param databaseUid The uid of the database to connect to as a string. For example: f116f93a-519c-208a-9a72-3ef6c9a1f081
 * @param locationId The location of the database to connect to, for example: nam5, us-central1, us-east4 etc...
 * @param environment Whether to try and fetch an auth credential from the GCE VM metadata service or whether to call gcloud.
 */
private static MongoClientSettings.Builder connectIgnite(
  String databaseUid: String
  String locationId:String
): MongoClientSettings.Builder {
  MongoCredential credential =
    MongoCredential.createOidcCredential(null)
      .withMechanismProperty(
        MongoCredential.OIDC_CALLBACK_KEY,
        new MongoCredential.OidcCallback() {
          @Override
          MongoCredential.OidcCallbackResult onRequest(
MongoCredential.OidcCallbackContext context) {
     // Customize this credential builder for additional credential types.
     GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
            return new MongoCredential.OidcCallbackResult(
         credentials.getAccessToken().getTokenValue(),
         Duration.between(Instant.now(),
credentials.getAccessToken().getExpirationTime().toInstant()));
          }
        },
      );
  return MongoClientSettings.builder()
    .hosts(listOf(ServerAddress(
        "$databaseUid.$locationId.firestore.goog", 443)))
    .credential(credential)
    .applyToClusterSettings(builder ->
         builder.mode(ClusterConnectionMode.LOAD_BALANCED))
    ).applyToSslSettings(ssl -> ssl.enabled(true));
}

替换以下内容：

  • DATABASE_UID：您的项目的名称。
  • LOCATION：数据库的位置。
  • DATABASE_ID 数据库 ID。

从 Compute Engine 虚拟机连接

您可以使用 Compute Engine 服务账号进行身份验证并连接到数据库。为此，请为包含数据库的 Google Cloud 项目创建 IAM 政策。

准备工作

为您的虚拟机配置用户管理的服务账号：

记下您的服务账号电子邮件地址。

配置凭据

如需向服务账号授予对 Firestore 执行读写操作的 roles/datastore.user 角色，请运行以下命令：

gcloud projects add-iam-policy-binding PROJECT_NAME --member="SERVICE_ACCOUNT_EMAIL" --role=roles/datastore.user

替换以下内容：

  • PROJECT_NAME：您的项目的名称。
  • SERVICE_ACCOUNT_EMAIL：您创建的服务账号的电子邮件地址。

构造连接字符串

请使用以下格式构建连接字符串：

mongodb://DATABASE_UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false&authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:FIRESTORE

替换以下内容：

  • DATABASE_UID：您的项目的名称。
  • LOCATION：数据库的位置。
  • DATABASE_ID 数据库 ID。

如需详细了解如何检索 UID 和位置信息，请参阅检索连接字符串。

使用临时访问令牌连接

您可以使用临时 Google Cloud 访问令牌运行 mongosh 等诊断工具。您可以使用 gcloud auth print-access-token 通过短期访问令牌进行身份验证。此令牌的有效期为 1 小时。

例如，使用以下命令通过 mongosh 连接到数据库：

mongosh --tls \
      --username access_token --password $(gcloud auth print-access-token) \
      'mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=PLAIN&authSource=$external&retryWrites=false'

替换以下内容：

  • DATABASE_UID：数据库的 UID
  • LOCATION：数据库位置
  • DATABASE_ID：数据库 ID