Authentifizierung und Verbindung zu einer Datenbank

Nur für die Cloud Firestore Enterprise-Edition relevant.

Verbindungsanforderungen

Für Cloud Firestore mit MongoDB-Kompatibilitätsclients 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. Cloud 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.

Hinweis :Eine Datenbank hat sowohl eine Datenbank-ID als auch eine UID. Die Datenbank-ID ist der Ressourcenname, den Sie beim Erstellen einer Datenbank festlegen. Die UID ist eine vom System generierte UUID4 für die Datenbank.

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:

Firebase Console

1. Rufen Sie in der Firebase-Konsole die Seite Firestore-Datenbank auf.

   Zur Firestore-Datenbank

2. Klicken Sie auf die Datenbank, die Sie authentifizieren möchten.
3. Klicken Sie im Bereich Explorer auf  Mehr ansehen.
4. Wählen Sie Verbindung mit MongoDB-Tools herstellen aus.
5. Kopieren Sie die Verbindungszeichenfolge.

gcloud

Verwenden Sie gcloud firestore database describe, um die UID und Standortinformationen abzurufen:

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

Ersetzen Sie DATABASE_ID durch die Datenbank-ID.

Die Ausgabe enthält den Speicherort und die UID der Datenbank. Anhand dieser Informationen können Sie den Basisverbindungsstring erstellen.

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.

Hinweis

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 Cloud Firestore-Datenbank mit MongoDB-Kompatibilität zu erstellen:

Google Cloud Console

1. Rufen Sie in der Google Cloud Console die Seite Datenbanken auf.

   Zur Seite „Datenbanken“

2. Wählen Sie eine Datenbank aus der Liste der Datenbanken aus.
3. Klicken Sie im Navigationsmenü auf Auth.
4. Klicken Sie auf Nutzer hinzufügen.
5. Geben Sie einen Nutzernamen ein.
6. Wählen Sie eine Rolle für den neuen Nutzer aus.
7. Klicken Sie auf Hinzufügen.

   Das Passwort des neuen Nutzers wird im Bestätigungsdialogfeld angezeigt.

   Achtung:Das Passwort wird nur einmal angezeigt und kann nicht wiederhergestellt werden. Speichern Sie dieses Passwort zur späteren Verwendung.

gcloud CLI

1. Für die Authentifizierung mit SCRAM müssen Sie zuerst Anmeldedaten für einen Nutzer erstellen. Führen Sie den Befehl gcloud alpha firestore user-creds aus:

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

   Ersetzen Sie Folgendes:
   • USERNAME: Der Nutzername, der erstellt werden soll.
   • DATABASE_ID: die Datenbank-ID.

   Die Ausgabe dieses Befehls enthält das Passwort des Nutzers.

   Achtung:Das Passwort wird nur einmal angezeigt und kann nicht wiederhergestellt werden. Speichern Sie dieses Passwort zur späteren Verwendung.

   Die Ausgabe sollte so aussehen:

   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. Standardmäßig hat diese neue Nutzeranmeldedaten keine Berechtigungen. Fügen Sie für Lese- und Schreibzugriff auf die Datenbank die Rolle roles/datastore.user für diese bestimmte Datenbank hinzu:

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

   Ersetzen Sie Folgendes:
   • PROJECT_NAME: Name Ihres Projekts
   • PROJECT_NUMBER: die Projektnummer.
   • DATABASE_ID: die Datenbank-ID.
   • USERNAME: Der Nutzername, den Sie zuvor erstellt haben.
   • CONDITION_TITLE: Ein Titel für diese Bedingung. Diese Bedingung beschränkt den Zugriff auf diese Datenbank.

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

mongodb://USERNAME:[e-mail]: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 mit der Google Cloud Standard-OAuth-Bibliothek registriert.

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)).retryWrites(false);
}

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.

Hinweis

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 Schreibvorgänge für Cloud 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