Authentifizieren und Verbindung zu einer Datenbank herstellen

Verbindungsanforderungen

Für Firestore mit MongoDB-kompatible Clients sind folgende Voraussetzungen erforderlich:

• Fahrer müssen sich im load balanced-Modus verbinden. Dadurch wird verhindert, dass die Treiber versuchen, die genaue Servertopologie zu ermitteln, mit der sie eine Verbindung herstellen.
• Treiber müssen mit aktivierter SSL-Verschlüsselung verbunden werden.
• Treiber müssen wiederholbare Schreibvorgänge deaktivieren. Firestore mit MongoDB-Kompatibilität unterstützt derzeit keine wiederholbaren Schreibvorgänge.

Verbindungsstring abrufen

Der Datenbankverbindungsstring hängt von der UID der Datenbank, dem Speicherort der Datenbank und dem Authentifizierungsmechanismus ab. In der folgenden Anleitung wird beschrieben, wie der Verbindungsstring gebildet wird.

Der genaue Verbindungsstring hängt vom Authentifizierungsmechanismus ab. Der Basisverbindungsstring hat jedoch das folgende Format:

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

Sie haben folgende Möglichkeiten, den Basisverbindungsstring abzurufen:

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

Verwenden Sie den Basisverbindungsstring und eine der folgenden Methoden, um sich zu authentifizieren und eine Verbindung zu Ihrer Datenbank herzustellen:

• Nutzername und Passwort (SCRAM)
• Compute Engine-Dienstkonto
• Google Auth Library

Mit Nutzername und Passwort (SCRAM) verbinden

Führen Sie die folgenden Schritte aus, um Anmeldedaten für Ihre Datenbank zu erstellen und eine Verbindung zur Datenbank herzustellen.

Hinweise

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle userCredsAdmin (roles/datastore.userCredsAdmin) für Ihre Datenbank zuzuweisen, damit Sie die Berechtigungen erhalten, die Sie zum Erstellen eines Nutzers benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Nutzer erstellen und Verbindung zu einer Datenbank herstellen

Verwenden Sie eine der folgenden Methoden, um einen Nutzer für Ihre Firestore-Datenbank mit MongoDB-Kompatibilität zu erstellen:

Verwenden Sie den folgenden Verbindungsstring, um mit SCRAM eine Verbindung zu Ihrer Datenbank herzustellen:

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

Ersetzen Sie Folgendes:

• USERNAME: der Nutzername.
• PASSWORD: Das Passwort, das Sie für diesen Nutzer generiert haben.
• UID: Die UID der Datenbank.
• LOCATION: der Speicherort der Datenbank.
• DATABASE_ID: die Datenbank-ID.

Verbindung zur Google-Authentifizierungsbibliothek herstellen

Im folgenden Codebeispiel wird ein OIDC-Callback-Handler registriert, der dieGoogle Cloud Standard-OAuth-Bibliothek verwendet.

Mit dieser Bibliothek können Sie verschiedene Arten der Authentifizierung verwenden (Standardanmeldedaten für Anwendungen, Identitätsföderation von Arbeitslasten).

Dazu müssen Sie die Auth-Bibliothek als Abhängigkeit hinzufügen:

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

Das folgende Codebeispiel zeigt, wie Sie eine Verbindung herstellen:

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));
}

Ersetzen Sie Folgendes:

• DATABASE_UID: Name Ihres Projekts
• LOCATION: der Speicherort Ihrer Datenbank.
• DATABASE_ID: Die Datenbank-ID.

Verbindung von einer Compute Engine-VM herstellen

Sie können sich mit einem Compute Engine-Dienstkonto authentifizieren und eine Verbindung zu Ihrer Datenbank herstellen. Erstellen Sie dazu eine IAM-Richtlinie für das Google Cloud Projekt, das Ihre Datenbank enthält.

Hinweise

Vom Nutzer verwaltetes Dienstkonto für Ihre VM konfigurieren:

• Informationen zum Konfigurieren von Dienstkonten während der VM-Erstellung finden Sie unter VM erstellen, die ein nutzerverwaltetes Dienstkonto verwendet.
• Informationen zum Konfigurieren eines Dienstkontos auf einer vorhandenen VM finden Sie unter Angehängtes Dienstkonto ändern.

Notieren Sie sich die E‑Mail-Adresse Ihres Dienstkontos.

Anmeldedaten konfigurieren

Führen Sie den folgenden Befehl aus, um dem Dienstkonto die Rolle roles/datastore.user für Lese- und Schreibzugriff auf Firestore zuzuweisen:

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

Ersetzen Sie Folgendes:

• PROJECT_NAME: Name Ihres Projekts
• SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des von Ihnen erstellten Dienstkontos.

Verbindungsstring erstellen

Verwenden Sie das folgende Format, um den Verbindungsstring zu erstellen:

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

Ersetzen Sie Folgendes:

• DATABASE_UID: Name Ihres Projekts
• LOCATION: der Speicherort Ihrer Datenbank.
• DATABASE_ID: Die Datenbank-ID.

Weitere Informationen zum Abrufen der UID und des Standorts finden Sie unter Verbindungsstring abrufen.

Mit einem temporären Zugriffstoken verbinden

Sie können ein temporäres Google Cloud Zugriffstoken verwenden, um Diagnosetools wie mongosh auszuführen. Sie können gcloud auth print-access-token verwenden, um sich mit einem kurzfristigen Zugriffstoken zu authentifizieren. Dieses Token ist eine Stunde lang gültig.

Verwenden Sie beispielsweise den folgenden Befehl, um mit mongosh eine Verbindung zu Ihrer Datenbank herzustellen:

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'

Ersetzen Sie Folgendes:

• DATABASE_UID: die UID der Datenbank
• LOCATION: der Speicherort der Datenbank
• DATABASE_ID: eine Datenbank-ID