Uwierzytelnianie i łączenie się z bazą danych

Dotyczy tylko wersji Cloud Firestore Enterprise.

Wymagania dotyczące połączenia

Wymagania dotyczące klientów Cloud Firestore w trybie zgodności z MongoDB:

• Kierowcy muszą łączyć się w trybie load balanced. Zapobiega to próbom zrozumienia przez sterowniki dokładnej topologii serwera, z którym się łączą.
• Sterowniki muszą łączyć się z włączonym protokołem SSL.
• Sterowniki muszą wyłączyć zapisy, które można ponawiać. Cloud Firestore w trybie zgodności z MongoDB nie obsługuje obecnie zapisów z możliwością ponowienia.

Pobieranie ciągu znaków połączenia

Ciąg połączenia z bazą danych zależy od identyfikatora UID bazy danych, jej lokalizacji i mechanizmu uwierzytelniania. Poniższe instrukcje opisują sposób tworzenia ciągu połączenia.

Uwaga: baza danych ma identyfikator i UID. Identyfikator bazy danych to nazwa zasobu ustawiona podczas tworzenia bazy danych. UID to wygenerowany przez system identyfikator UUID4 bazy danych.

Dokładny ciąg znaków połączenia zależy od mechanizmu uwierzytelniania, ale podstawowy ciąg znaków połączenia ma następujący format:

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

Podstawowy ciąg połączenia możesz uzyskać na jeden z tych sposobów:

Firebase konsola

1. W konsoli Firebase otwórz stronę Baza danych Firestore.

   Otwórz bazę danych Firestore

2. Kliknij bazę danych, którą chcesz uwierzytelnić.
3. W panelu Eksplorator kliknij  Wyświetl więcej.
4. Kliknij Połącz za pomocą narzędzi MongoDB.
5. Skopiuj ciąg połączenia.

gcloud

Aby pobrać identyfikator UID i informacje o lokalizacji, użyj metody gcloud firestore database describe:

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

Zastąp DATABASE_ID identyfikatorem bazy danych.

Dane wyjściowe zawierają lokalizację i identyfikator UID bazy danych. Użyj tych informacji, aby utworzyć podstawowy ciąg znaków połączenia.

Aby uwierzytelnić się i połączyć z bazą danych, użyj podstawowego ciągu znaków połączenia i jednej z tych metod:

• Nazwa użytkownika i hasło (SCRAM)
• Compute Engine konto usługi
• Biblioteka uwierzytelniania Google

Łączenie z użyciem nazwy użytkownika i hasła (SCRAM)

Aby utworzyć dane logowania użytkownika do bazy danych i połączyć się z bazą danych, wykonaj te czynności.

Zanim zaczniesz

Aby uzyskać uprawnienia potrzebne do utworzenia użytkownika, poproś administratora o przypisanie Ci w bazie danych roli uprawnień userCredsAdmin (roles/datastore.userCredsAdmin). Więcej informacji o przyznawaniu ról znajdziesz w artykule Zarządzanie dostępem do projektów, folderów i organizacji.

Wymagane uprawnienia możesz też uzyskać, używając ról niestandardowych lub innych wstępnie zdefiniowanych ról.

Tworzenie użytkownika i łączenie się z bazą danych

Aby utworzyć użytkownika bazy danych Cloud Firestore w trybie zgodności z MongoDB, użyj jednej z tych metod:

Google Cloud Console

1. W konsoli Google Cloud otwórz stronę Bazy danych.

   Otwórz Bazy danych

2. Wybierz bazę danych z listy baz danych.
3. W menu nawigacyjnym kliknij Uwierzytelnianie.
4. Kliknij Dodaj użytkownika.
5. Wpisz nazwę użytkownika.
6. Wybierz rolę nowego użytkownika.
7. Kliknij Dodaj.

   Hasło nowego użytkownika pojawi się w oknie potwierdzenia.

   Uwaga: hasło jest wyświetlane tylko raz i nie można go odzyskać. Zapisz to hasło do wykorzystania w przyszłości.

gcloud CLI

1. Aby uwierzytelnić się za pomocą SCRAM, musisz najpierw utworzyć dane logowania użytkownika. Użyj polecenia gcloud alpha firestore user-creds:

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

   Zastąp te elementy:
   • USERNAME: nazwa użytkownika do utworzenia.
   • DATABASE_ID: identyfikator bazy danych.

   Wynik tego polecenia zawiera hasło użytkownika.

   Uwaga: hasło jest wyświetlane tylko raz i nie można go odzyskać. Zapisz to hasło do wykorzystania w przyszłości.

   Dane wyjściowe są podobne do tych:

   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. Domyślnie nowe dane logowania użytkownika nie mają żadnych uprawnień. Aby przyznać uprawnienia do odczytu i zapisu w bazie danych, dodaj rolę roles/datastore.user dla tej konkretnej bazy danych:

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

   Zastąp te elementy:
   • PROJECT_NAME: nazwa projektu.
   • PROJECT_NUMBER: numer projektu.
   • DATABASE_ID: identyfikator bazy danych.
   • USERNAME: utworzona wcześniej nazwa użytkownika.
   • CONDITION_TITLE: tytuł tego warunku. Ten warunek ogranicza dostęp tylko do tej bazy danych.

Aby połączyć się z bazą danych za pomocą SCRAM, użyj tego ciągu znaków połączenia:

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

Zastąp następujące elementy:

• USERNAME: nazwa użytkownika.
• PASSWORD: hasło wygenerowane dla tego użytkownika.
• UID: identyfikator UID bazy danych.
• LOCATION: lokalizacja bazy danych.
• DATABASE_ID: identyfikator bazy danych.

Łączenie się z klientem Google Auth Library

Poniższy przykładowy kod rejestruje procedurę obsługi wywołania zwrotnego OIDC, która korzysta ze Google Cloud standardowej biblioteki OAuth.

Ta biblioteka umożliwia korzystanie z różnych typów uwierzytelniania (domyślne dane logowania aplikacji, federacja tożsamości pracowników).

Wymaga to dodania biblioteki uwierzytelniania jako zależności:

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

Poniższy przykładowy kod pokazuje, jak nawiązać połączenie:

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

Zastąp następujące elementy:

• DATABASE_UID: nazwa projektu.
• LOCATION: lokalizacja bazy danych.
• DATABASE_ID identyfikator bazy danych.

Łączenie się z maszyny wirtualnej Compute Engine

Możesz uwierzytelnić się i połączyć z bazą danych za pomocą Compute Engine konta usługi. Aby to zrobić, utwórz zasady IAM dla projektu Google Cloud, który zawiera Twoją bazę danych.

Zanim zaczniesz

Skonfiguruj konto usługi zarządzane przez użytkownika na potrzeby maszyny wirtualnej:

• Aby skonfigurować konto usługi podczas tworzenia maszyny wirtualnej, zapoznaj się z artykułem Tworzenie maszyny wirtualnej, która korzysta z konta usługi zarządzanego przez użytkownika.
• Aby skonfigurować konto usługi na istniejącej maszynie wirtualnej, zapoznaj się z artykułem Zmiana dołączonego konta usługi.

Zanotuj adres e-mail konta usługi.

Konfigurowanie danych logowania

Aby przyznać kontu usługi rolę roles/datastore.user umożliwiającą odczyt i zapis w Cloud Firestore, uruchom to polecenie:

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

Zastąp następujące elementy:

• PROJECT_NAME: nazwa projektu.
• SERVICE_ACCOUNT_EMAIL: adres e-mail utworzonego przez Ciebie konta usługi.

Tworzenie ciągu znaków połączenia

Aby utworzyć ciąg znaków połączenia, użyj tego formatu:

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

Zastąp następujące elementy:

• DATABASE_UID: nazwa projektu.
• LOCATION: lokalizacja bazy danych.
• DATABASE_ID identyfikator bazy danych.

Więcej informacji o pobieraniu identyfikatora UID i lokalizacji znajdziesz w artykule Pobieranie ciągu połączenia.

Łączenie za pomocą tymczasowego tokena dostępu

Możesz użyć tymczasowego Google Cloudtokena dostępu, aby uruchomić narzędzia diagnostyczne, takie jak mongosh. Możesz użyć gcloud auth print-access-token, aby uwierzytelnić się za pomocą krótkoterminowego tokena dostępu. Ten token jest ważny przez godzinę.

Aby na przykład połączyć się z bazą danych za pomocą mongosh, użyj tego polecenia:

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'

Zastąp następujące elementy:

• DATABASE_UID: identyfikator UID bazy danych.
• LOCATION: lokalizacja bazy danych
• DATABASE_ID: identyfikator bazy danych