Esta página se ha traducido con Cloud Translation API.

Autenticarse y conectarse a una base de datos

Requisitos de conexión

Los clientes de Firestore con compatibilidad con MongoDB deben cumplir los siguientes requisitos:

Los conductores deben conectarse en modo load balanced. De esta forma, los controladores no intentarán comprender la topología exacta del servidor al que se conectan.
Los controladores deben conectarse con SSL habilitado.
Los controladores deben inhabilitar las escrituras reintentables. Firestore con compatibilidad con MongoDB no admite escrituras reintentables. No es necesario inhabilitar las lecturas reintentables, ya que se admiten.

Recuperar la cadena de conexión

La cadena de conexión de la base de datos depende del UID de la base de datos, de la ubicación de la base de datos y del mecanismo de autenticación. En las siguientes instrucciones se describe cómo se forma la cadena de conexión.

La cadena de conexión exacta depende del mecanismo de autenticación, pero la cadena de conexión base usa el siguiente formato:

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

Puedes obtener la cadena de conexión de la base de datos de una de las siguientes formas:

Consola

En la Google Cloud consola, ve a la página Bases de datos.

Ir a Bases de datos
En la lista de bases de datos, haga clic en el ID de la base de datos pertinente.
En el panel Explorador se muestra la cadena de conexión de la base. Copia y usa esta cadena de conexión para conectarte a tu base de datos.

gcloud

Usa gcloud firestore database describe para obtener el UID y la información de ubicación:

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

Sustituye DATABASE_ID por el ID de la base de datos.

La salida incluye la ubicación y el UID de la base de datos. Usa esta información para crear la cadena de conexión base.

Usa la cadena de conexión base y uno de los siguientes métodos para autenticarte y conectarte a tu base de datos:

Nombre de usuario y contraseña (SCRAM)
Cuenta de servicio de Compute Engine
Cuenta de servicio de Cloud Run
Biblioteca de autenticación de Google

Conectarse con nombre de usuario y contraseña (SCRAM)

Sigue estos pasos para crear una credencial de usuario para tu base de datos y conectarte a ella.

Antes de empezar

Para obtener los permisos que necesitas para crear un usuario, pide a tu administrador que te conceda el rol de IAM userCredsAdmin (roles/datastore.userCredsAdmin) en tu base de datos. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Crear un usuario y conectarse a una base de datos

Para crear un usuario para tu base de datos de Firestore con compatibilidad con MongoDB, usa uno de los siguientes métodos:

Google Cloud consola

En la Google Cloud consola, ve a la página Bases de datos.

Ir a Bases de datos
Selecciona una base de datos de la lista.
En el menú de navegación, haz clic en Autenticación.
Haz clic en Add User (Añadir usuario).
Escribe un nombre de usuario.
Selecciona un rol para el nuevo usuario.
Haz clic en Añadir.
La contraseña del nuevo usuario se mostrará en el cuadro de diálogo de confirmación.

Precaución: La contraseña se muestra una vez y no se puede recuperar. Guarda esta contraseña para usarla en el futuro.

CLI de gcloud

Para autenticarte con SCRAM, primero debes crear una credencial de usuario. Usa el comando gcloud firestore user-creds:
```
gcloud firestore user-creds create USERNAME --database=DATABASE_ID
```
Sustituye lo siguiente:
- USERNAME: el nombre de usuario que se va a crear.
- DATABASE_ID: el ID de la base de datos.
La salida de este comando incluye la contraseña del usuario.

Precaución: La contraseña se muestra una vez y no se puede recuperar. Guarda esta contraseña para usarla en el futuro.

La salida es similar a la siguiente:
```
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
```
De forma predeterminada, esta nueva credencial de usuario no tiene ningún permiso. Para obtener acceso de lectura y escritura a la base de datos, añade el rol roles/datastore.user a esta base de datos específica:
```
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"'
```
Sustituye lo siguiente:
- PROJECT_NAME: el nombre de tu proyecto.
- PROJECT_NUMBER: el número de proyecto.
- DATABASE_ID: el ID de la base de datos.
- USERNAME: el nombre de usuario que creaste anteriormente.
- CONDITION_TITLE: un título para esta condición. Esta condición restringe el acceso solo a esta base de datos.

Java

En esta sección se proporciona un ejemplo de código para crear credenciales de usuario y configurar la política de gestión de identidades y accesos mediante bibliotecas de cliente administrativas de Java. En el ejemplo se usa la biblioteca Firestore Admin Client para crear un nombre de usuario y una contraseña, y la biblioteca Google Cloud Resource Manager para configurar la gestión de identidades y accesos.

En las compilaciones de Maven, puedes usar las siguientes coordenadas:

com.google.cloud:google-cloud-firestore-admin:3.33.1
com.google.cloud:google-cloud-resourcemanager:1.76.0

Proporciona credenciales de usuario y una política de gestión de identidades y accesos:

import com.google.cloud.firestore.v1.FirestoreAdminClient;
import com.google.cloud.resourcemanager.v3.ProjectName;
import com.google.cloud.resourcemanager.v3.ProjectsClient;
import com.google.firestore.admin.v1.CreateUserCredsRequest;
import com.google.firestore.admin.v1.GetUserCredsRequest;
import com.google.firestore.admin.v1.UserCreds;
import com.google.iam.v1.Binding;
import com.google.iam.v1.GetIamPolicyRequest;
import com.google.iam.v1.GetPolicyOptions;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import com.google.protobuf.FieldMask;
import com.google.type.Expr;

public class FirestoreUserCredsExample {
  /**
   * Provision user credentials and configure an IAM policy to allow SCRAM authentication into the
   * specified Firestore with Mongo Compatibility database.
   */
  private static void provisionFirestoreUserCredsAndIAM(
      String projectId, String databaseId, String userName) throws Exception {
    UserCreds userCreds = createUserCreds(projectId, databaseId, userName);

    // Note the password returned in the UserCreds proto - it cannot be retrieved again
    // after the initial call to the createUserCreds API.
    System.out.printf(
        "Created credentials for username: %s:\nIAM principal: %s\nPassword: [%s]\n",
        userName, userCreds.getResourceIdentity().getPrincipal(), userCreds.getSecurePassword());

    // Provision an IAM binding for the principal associated with these user credentials.
    updateIamPolicyForUserCreds(projectId, databaseId, userName, userCreds);

    // Emit the password again.
    System.out.printf(
        "Successfully configured IAM policy for database: %s, username: %s\n",
        databaseId, userName);
    System.out.printf("Please make a note of the password: [%s]\n", userCreds.getSecurePassword());
  }

  /** Provision new user credentials using the FirestoreAdminClient. */
  private static UserCreds createUserCreds(String projectId, String databaseId, String userName)
      throws Exception {
    FirestoreAdminClient firestoreAdminClient = FirestoreAdminClient.create();
    return firestoreAdminClient.createUserCreds(
        CreateUserCredsRequest.newBuilder()
            .setParent(String.format("projects/%s/databases/%s", projectId, databaseId))
            .setUserCredsId(userName)
            .build());
  }

  /** Update the IAM policy using the Resource Manager ProjectsClient. */
  private static void updateIamPolicyForUserCreds(
      String projectId, String databaseId, String userName, UserCreds userCreds) throws Exception {
    try (ProjectsClient projectsClient = ProjectsClient.create()) {
      ProjectName projectName = ProjectName.of(projectId);

      // Get the current IAM policy.
      Policy currentPolicy =
          projectsClient.getIamPolicy(
              GetIamPolicyRequest.newBuilder()
                  .setResource(projectName.toString())
                  .setOptions(GetPolicyOptions.newBuilder().setRequestedPolicyVersion(3).build())
                  .build());

      String role = "roles/datastore.user";
      String title = String.format("Conditional IAM binding for %s", userName);
      String expression =
          String.format("resource.name == \"projects/%s/databases/%s\"", projectId, databaseId);

      // Construct an updated IAM policy with an additional binding for the user credentials.
      Policy.Builder policyBuilder = currentPolicy.toBuilder();
      Binding newBinding =
          Binding.newBuilder()
              .setRole(role)
              .setCondition(Expr.newBuilder().setTitle(title).setExpression(expression).build())
              .addMembers(userCreds.getResourceIdentity().getPrincipal())
              .build();
      policyBuilder.addBindings(newBinding);

      // Update the policy
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(projectName.toString())
              .setPolicy(policyBuilder.build())
              .setUpdateMask(FieldMask.newBuilder().addPaths("bindings").addPaths("etag").build())
              .build();
      System.out.println(request);

      Policy updatedPolicy = projectsClient.setIamPolicy(request);
      System.out.println("Policy updated successfully: " + updatedPolicy);
    }
  }
}

Python

En esta sección se proporciona un ejemplo de código para crear credenciales de usuario y configurar la política de gestión de identidades y accesos mediante bibliotecas de cliente administrativas de Python. En el ejemplo se usa la biblioteca de cliente de la API Google Cloud Firestore para crear un nombre de usuario y una contraseña, así como la biblioteca de cliente de la API Google Cloud Iam y la biblioteca de cliente de la API Google Cloud Resource Manager para configurar IAM.

Las bibliotecas de Python necesarias se pueden instalar con la herramienta pip:

pip install google-cloud-iam
pip install google-cloud-firestore
pip install google-cloud-resource-manager

Proporciona credenciales de usuario y una política de gestión de identidades y accesos:

from google.cloud import resourcemanager_v3
from google.cloud.firestore_admin_v1 import FirestoreAdminClient
from google.cloud.firestore_admin_v1 import types
from google.iam.v1 import iam_policy_pb2
from google.iam.v1 import policy_pb2
from google.type import expr_pb2


def create_user_creds(project_id: str, database_id: str, user_name: str):
  """Provision new user credentials using the FirestoreAdminClient."""
  client = FirestoreAdminClient()
  request = types.CreateUserCredsRequest(
      parent=f'projects/{project_id}/databases/{database_id}',
      user_creds_id=user_name,
  )
  response = client.create_user_creds(request)
  return response


def update_iam_policy_for_user_creds(
    project_id: str, database_id: str, user_name: str, user_creds
):
  """Update the IAM policy using the Resource Manager ProjectsClient."""
  client = resourcemanager_v3.ProjectsClient()
  request = iam_policy_pb2.GetIamPolicyRequest()
  request.resource = f'projects/{project_id}'
  request.options.requested_policy_version = 3

  # Get the current IAM policy
  current_policy = client.get_iam_policy(request)

  # Construct an updated IAM policy with an additional binding
  # for the user credentials.
  updated_policy = policy_pb2.Policy()
  binding = policy_pb2.Binding()
  iam_condition = expr_pb2.Expr()

  iam_condition.title = f'Conditional IAM binding for {user_name}'
  iam_condition.expression = (
      f'resource.name == "projects/{project_id}/databases/{database_id}"'
  )

  binding.role = 'roles/datastore.user'
  binding.condition.CopyFrom(iam_condition)
  binding.members.append(user_creds.resource_identity.principal)
  updated_policy.bindings.append(binding)

  # Update the policy
  updated_policy.MergeFrom(current_policy)
  set_policy_request = iam_policy_pb2.SetIamPolicyRequest()
  set_policy_request.resource = f'projects/{project_id}'
  set_policy_request.policy.CopyFrom(updated_policy)

  final_policy = client.set_iam_policy(set_policy_request)
  print(f'Policy updated successfully {final_policy}')


def provision_firestore_user_creds_and_iam(
    project_id: str, database_id: str, user_name: str
):
  """Provision user credentials and configure an IAM policy."""
  user_creds = create_user_creds(project_id, database_id, user_name)

  # Note the password returned in the UserCreds proto - it cannot be
  # retrieved again after the initial call to the create_user_creds API.
  print(f'Created credentials for username: {user_name}')
  print(f'IAM principal: {user_creds.resource_identity.principal}')
  print(f'Password: [{user_creds.secure_password}]')

  # Provision an IAM binding for the principal associated with
  # these user credentials.
  update_iam_policy_for_user_creds(
      project_id, database_id, user_name, user_creds
  )

  # Emit the password again
  print(
      f'Successfully configured IAM policy for database: {database_id},'
      f' username: {user_name}'
  )
  print(f'Please make a note of the password: [{user_creds.secure_password}]')

Usa la siguiente cadena de conexión para conectarte a tu base de datos con SCRAM:

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

Haz los cambios siguientes:

USERNAME: el nombre de usuario.
PASSWORD: la contraseña que has generado para este usuario.
UID: el UID de la base de datos.
LOCATION: la ubicación de la base de datos.
DATABASE_ID: el ID de la base de datos.

Conectarse con la biblioteca de autenticación de Google

En el siguiente ejemplo de código se registra un controlador de retrollamada de OIDC que usa laGoogle Cloud biblioteca OAuth estándar.

Esta biblioteca te permite usar varios tipos de autenticación (credenciales predeterminadas de la aplicación y federación de identidades de cargas de trabajo).

Para ello, debes añadir la biblioteca de autenticación como dependencia:

// 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'

En el siguiente ejemplo de código se muestra cómo conectarse:

val db = MongoClients.create(
    clientSettings(
      "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 Determines whether to try and fetch an authentication credential from the
 * Compute Engine VM metadata service or whether to call gcloud.
 */
private static MongoClientSettings.Builder clientSettings(
  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)).retryWrites(false);
}

Haz los cambios siguientes:

DATABASE_UID: el nombre de tu proyecto.
LOCATION: la ubicación de tu base de datos.
DATABASE_ID el ID de la base de datos.

Conectarse desde un Google Cloud entorno de computación

En esta sección se describe cómo conectarse a Firestore con compatibilidad con MongoDB desde un entorno de computación, como Compute Engine o un servicio o un trabajo de Cloud Run. Google Cloud

Conectarse desde una VM de Compute Engine

Puedes autenticarte y conectarte a tu base de datos mediante una cuenta de servicio de Compute Engine. Para ello, crea una política de gestión de identidades y accesos para el proyecto que contiene tu base de datos. Google Cloud

Antes de empezar

Configura una cuenta de servicio gestionada por el usuario para tu VM:

Para configurar una cuenta de servicio durante la creación de una máquina virtual, consulta Crear una máquina virtual que use una cuenta de servicio gestionada por el usuario.
Para configurar una cuenta de servicio en una máquina virtual que ya tienes, consulta Cambiar la cuenta de servicio vinculada.

Sigue las instrucciones de las secciones Configurar credenciales para completar la configuración de la política de IAM de tu cuenta de servicio de Compute Engine.

Conectarse desde Cloud Run

Puedes autenticarte y conectarte a tu base de datos mediante una cuenta de servicio de Cloud Run. Para ello, crea una política de gestión de identidades y accesos para el proyecto que contiene tu base de datos. Google Cloud

Antes de empezar

Para configurar la cuenta de servicio de Cloud Run, consulta Configurar la identidad de servicio.
Para determinar la cuenta de servicio que ya está asociada a tu servicio de Cloud Run, consulta gcloud run services describe.

Sigue las instrucciones de la sección Configurar credenciales para completar la configuración de la política de gestión de identidades y accesos de tu cuenta de servicio de Cloud Run.

Configurar credenciales

Para conceder a la cuenta de servicio el rol roles/datastore.user para leer y escribir en Firestore, ejecuta el siguiente comando:

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

Haz los cambios siguientes:

PROJECT_NAME: el nombre de tu proyecto.
SERVICE_ACCOUNT_EMAIL: la dirección de correo de la cuenta de servicio que has creado.

Construir la cadena de conexión

Usa el siguiente formato para crear la cadena de conexión:

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

Haz los cambios siguientes:

DATABASE_UID: el nombre de tu proyecto.
LOCATION: la ubicación de tu base de datos.
DATABASE_ID el ID de la base de datos.

Para obtener más información sobre cómo recuperar el UID y la ubicación, consulta Recuperar la cadena de conexión.

Conectarse con un token de acceso temporal

Puedes usar un token de acceso temporal Google Cloud para ejecutar herramientas de diagnóstico, como mongosh. Puedes usar gcloud auth print-access-token para autenticarte con un token de acceso de corta duración. Este token es válido durante una hora.

Por ejemplo, usa el siguiente comando para conectarte a tu base de datos con 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'

Haz los cambios siguientes:

DATABASE_UID: el UID de la base de datos
LOCATION: la ubicación de la base de datos
DATABASE_ID: un ID de base de datos