Cómo autenticarse y conectarse a una base de datos

Solo es relevante para la edición Enterprise de Cloud Firestore.

Requisitos de conexión

Se requieren los siguientes elementos para los clientes de Cloud Firestore con compatibilidad con MongoDB:

• Los conductores deben conectarse en modo load balanced. Esto evita que los controladores intenten 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. Actualmente, Cloud Firestore con compatibilidad con MongoDB no admite escrituras reintentables.

Recupera la cadena de conexión

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

Nota: Una base de datos tiene un ID y un UID. El ID de la base de datos es el nombre del recurso que estableces cuando creas una base de datos. El UID es un UUID4 generado por el sistema para la base de datos.

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 base de una de las siguientes maneras:

Consola de Firebase

1. En la consola Firebase, ve a la página Base de datos de Firestore:

   Ir a la base de datos de Firestore

2. Haz clic en la base de datos que deseas autenticar.
3. En el panel Explorador, haz clic en Ver más.
4. Selecciona Conectarse con las herramientas de MongoDB.
5. Copia la cadena de conexión.

gcloud

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

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

Reemplaza DATABASE_ID por el ID de la base de datos.

El resultado incluye la ubicación y el UID de la base de datos. Usa esta información para construir la cadena de conexión base.

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

• Nombre de usuario y contraseña (SCRAM)
• Compute Engine cuenta de servicio
• Biblioteca de autenticación de Google

Conéctate 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 comenzar

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

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Crea un usuario y conéctate a una base de datos

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

Consola de Google Cloud

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

   Ir a Bases de datos

2. Selecciona una base de datos de la lista.
3. En el menú de navegación, haz clic en Auth.
4. Haz clic en Agregar usuario.
5. Ingresa un Nombre de usuario.
6. Selecciona un rol para el usuario nuevo.
7. Haz clic en Agregar.

   La contraseña del usuario nuevo se mostrará en el diálogo de confirmación.

   Precaución: La contraseña se muestra una sola vez y no se puede recuperar. Almacena esta contraseña para usarla más adelante.

gcloud CLI

1. Para autenticarte con SCRAM, primero debes crear una credencial de usuario. Usa el comando gcloud alpha firestore user-creds:

   gcloud alpha firestore user-creds create USERNAME --database=DATABASE_ID

   Reemplaza lo siguiente:
   • USERNAME: Es el nombre de usuario que se creará.
   • DATABASE_ID: Es el ID de la base de datos.

   El resultado de este comando incluye la contraseña del usuario.

   Precaución: La contraseña se muestra una sola vez y no se puede recuperar. Almacena esta contraseña para usarla más adelante.

   El resultado se ve de la manera 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

2. De forma predeterminada, esta nueva credencial de usuario no tiene permisos. Para obtener acceso de lectura y escritura a la base de datos, agrega el rol roles/datastore.user para 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"'

   Reemplaza lo siguiente:
   • PROJECT_NAME: nombre del proyecto.
   • PROJECT_NUMBER: El número del proyecto.
   • DATABASE_ID: Es el ID de la base de datos.
   • USERNAME: Es el nombre de usuario que creaste anteriormente.
   • CONDITION_TITLE: Es un título para esta condición. Esta condición restringe el acceso solo a esta base de datos.

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

mongodb://USERNAME:[e-mail]:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false

Reemplaza lo siguiente:

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

Conéctate con la biblioteca de Google Auth

En la siguiente muestra de código, se registra un controlador de devolución de llamada de OIDC que usa la biblioteca OAuth estándar Google Cloud.

Esta biblioteca te permite usar varios tipos diferentes de autenticación (credenciales predeterminadas de la aplicación, federación de Workload Identity).

Esto requiere agregar la biblioteca de autenticación como una 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);
}

Reemplaza lo siguiente:

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

Conéctate desde una VM de Compute Engine

Puedes autenticarte y conectarte a tu base de datos con una cuenta de servicio de Compute Engine. Para ello, crea una política de IAM para el proyecto Google Cloud que contiene tu base de datos.

Antes de comenzar

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

• Para configurar la cuenta de servicio durante la creación de la VM, consulta Crea una VM que use una cuenta de servicio administrada por el usuario.
• Para configurar una cuenta de servicio en una VM existente, consulta Cambia la cuenta de servicio conectada.

Toma nota del correo electrónico de tu cuenta de servicio.

Configura las credenciales

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

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

Reemplaza lo siguiente:

• PROJECT_NAME: nombre del proyecto.
• SERVICE_ACCOUNT_EMAIL: La dirección de correo electrónico de la cuenta de servicio que creaste.

Cómo construir la cadena de conexión

Usa el siguiente formato para crear el string 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

Reemplaza lo siguiente:

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

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

Conéctate con un token de acceso temporal

Puedes usar un token de acceso Google Cloud temporal para ejecutar herramientas de diagnóstico, como mongosh. Puedes usar gcloud auth print-access-token para autenticarte con un token de acceso a corto plazo. 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'

Reemplaza lo siguiente:

• DATABASE_UID: Es el UID de la base de datos.
• LOCATION: La ubicación de la base de datos
• DATABASE_ID: Es un ID de base de datos.