Edisi Cloud Firestore Enterprise dengan kompatibilitas MongoDB kini tersedia! Pelajari lebih lanjut.

Melakukan autentikasi dan terhubung ke database

Hanya berlaku untuk edisi Cloud Firestore Enterprise.

Persyaratan koneksi:

Syarat berikut diperlukan untuk klien Cloud Firestore dengan kompatibilitas MongoDB:

Driver harus terhubung dalam mode load balanced. Hal ini mencegah driver mencoba memahami topologi server persis yang terhubung dengannya.
Driver harus terhubung dengan SSL yang diaktifkan.
Driver harus menonaktifkan operasi tulis yang dapat dicoba lagi. Cloud Firestore dengan kompatibilitas MongoDB tidak mendukung operasi tulis yang dapat dicoba lagi. Anda tidak perlu menonaktifkan operasi baca yang dapat dicoba lagi karena operasi ini didukung.

Mengambil string koneksi

String koneksi database bergantung pada UID database, lokasi database, dan mekanisme autentikasi. Petunjuk berikut menjelaskan cara string koneksi dibentuk.

String koneksi yang tepat bergantung pada mekanisme autentikasi, tetapi string koneksi dasar menggunakan format berikut:

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

Anda dapat memperoleh string koneksi dasar dengan salah satu cara berikut:

Firebase console

Di Firebase console, buka halaman Database Firestore.

Buka Database Firestore
Klik database yang ingin Anda autentikasi.
Di panel Explorer, klik Lihat selengkapnya.
Pilih Hubungkan menggunakan alat MongoDB.
Salin string koneksi.

gcloud

Gunakan gcloud firestore database describe untuk mengambil UID dan informasi lokasi:

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

Ganti DATABASE_ID dengan ID database.

Output mencakup lokasi dan UID database. Gunakan informasi ini untuk membuat string koneksi dasar.

Gunakan string koneksi dasar dan salah satu metode berikut untuk mengautentikasi dan menghubungkan ke database Anda:

Nama pengguna dan sandi (SCRAM)
Compute Engine akun layanan
Cloud Run akun layanan
Library Google Auth

Menghubungkan dengan Nama pengguna dan sandi (SCRAM)

Ikuti langkah-langkah berikut untuk membuat kredensial pengguna untuk database Anda dan menghubungkan ke database Anda.

Sebelum memulai

Untuk mendapatkan izin yang diperlukan guna membuat pengguna, minta administrator untuk memberi Anda peran IAM userCredsAdmin (roles/datastore.userCredsAdmin) di database Anda. Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Membuat pengguna dan menghubungkan ke database

Untuk membuat pengguna bagi database Cloud Firestore dengan kompatibilitas MongoDB, gunakan salah satu metode berikut:

Konsol Google Cloud

Di Konsol Google Cloud, buka halaman Databases.

Buka Databases
Pilih database dari daftar database.
Di menu navigasi, klik Auth.
Klik Add user.
Masukkan Nama pengguna.
Pilih peran untuk pengguna baru.
Klik Tambahkan.
Sandi pengguna baru akan ditampilkan di dialog konfirmasi.

Perhatian: Sandi hanya ditampilkan satu kali dan tidak dapat diambil kembali. Simpan sandi ini untuk penggunaan mendatang.

gcloud CLI

Untuk mengautentikasi dengan SCRAM, Anda harus membuat kredensial pengguna terlebih dahulu. Gunakan perintah gcloud alpha firestore user-creds:
```
gcloud alpha firestore user-creds create USERNAME --database=DATABASE_ID
```
Ganti kode berikut:
- USERNAME: nama pengguna yang akan dibuat.
- DATABASE_ID: ID database.
Output perintah ini mencakup sandi pengguna.

Perhatian: Sandi hanya ditampilkan satu kali dan tidak dapat diambil kembali. Simpan sandi ini untuk penggunaan berikutnya.

Outputnya akan terlihat seperti berikut:
```
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
```
Secara default, kredensial pengguna baru ini tidak memiliki izin apa pun. Untuk akses baca dan tulis ke database, tambahkan peran roles/datastore.user untuk database tertentu ini:
```
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"'
```
Ganti kode berikut:
- PROJECT_NAME: nama project Anda.
- PROJECT_NUMBER: nomor project.
- DATABASE_ID: ID database.
- USERNAME: nama pengguna yang Anda buat sebelumnya.
- CONDITION_TITLE: judul untuk kondisi ini. Kondisi ini membatasi akses hanya ke database ini.

Java

Bagian ini memberikan contoh kode untuk membuat kredensial pengguna dan mengonfigurasi kebijakan IAM menggunakan library klien administratif Java. Contoh ini menggunakan library Klien Admin Firestore untuk membuat nama pengguna dan sandi, serta library Google Cloud Resource Manager untuk mengonfigurasi IAM.

Untuk build Maven, Anda dapat menggunakan koordinat berikut:

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

Sediakan kredensial pengguna dan kebijakan IAM:

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

Gunakan string koneksi berikut untuk menghubungkan ke database Anda dengan SCRAM:

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

Ganti kode berikut:

USERNAME: nama pengguna.
PASSWORD: sandi yang Anda buat untuk pengguna ini.
UID: UID database.
LOCATION: lokasi database.
DATABASE_ID: ID database.

Menghubungkan dengan Library Google Auth

Contoh kode berikut mendaftarkan handler callback OIDC menggunakan Google Cloud library OAuth standar.

Library ini memungkinkan Anda menggunakan sejumlah jenis autentikasi yang berbeda (Kredensial Default Aplikasi, Workload Identity Federation).

Hal ini memerlukan penambahan library auth sebagai dependensi:

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

Contoh kode berikut menunjukkan cara menghubungkan:

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

Ganti kode berikut:

DATABASE_UID: nama project Anda.
LOCATION: lokasi database Anda.
DATABASE_ID ID database.

Terhubung dari lingkungan komputasi Google Cloud

Bagian ini menjelaskan cara terhubung ke Cloud Firestore dengan kompatibilitas MongoDB dari lingkungan komputasi Google Cloud, seperti tugas atau layanan Cloud Run atau Compute Engine.

Menghubungkan dari VM Compute Engine

Anda dapat mengautentikasi dan menghubungkan ke database menggunakan akun layanan Compute Engine. Untuk melakukannya, buat kebijakan IAM untuk project Google Cloud yang mencakup database Anda.

Sebelum memulai

Mengonfigurasi akun layanan yang dikelola pengguna untuk VM Anda:

Untuk mengonfigurasi akun layanan selama pembuatan VM, lihat Membuat VM yang menggunakan akun layanan yang dikelola pengguna.
Untuk mengonfigurasi akun layanan di VM yang ada, lihat Mengubah akun layanan yang ditambahkan.

Lihat petunjuk di bagian Mengonfigurasi kredensial untuk menyelesaikan konfigurasi kebijakan IAM untuk akun layanan Compute Engine Anda.

Terhubung dari Cloud Run

Anda dapat mengautentikasi dan menghubungkan ke database menggunakan akun layanan Cloud Run. Untuk melakukannya, buat kebijakan IAM untuk project Google Cloud yang mencakup database Anda.

Sebelum memulai

Untuk mengonfigurasi akun layanan untuk Cloud Run, lihat Mengonfigurasi identitas layanan
Untuk menentukan akun layanan yang sudah dikaitkan dengan layanan Cloud Run Anda, lihat gcloud run services describe

Lihat petunjuk di bagian Mengonfigurasi kredensial untuk menyelesaikan konfigurasi kebijakan IAM untuk akun layanan Cloud Run Anda.

Mengonfigurasi kredensial

Untuk memberikan peran roles/datastore.user kepada akun layanan guna membaca dan menulis ke Cloud Firestore, jalankan perintah berikut:

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

Ganti kode berikut:

PROJECT_NAME: nama project Anda.
SERVICE_ACCOUNT_EMAIL: alamat email untuk akun layanan yang Anda buat.

Membangun string koneksi

Gunakan format berikut untuk membangun string koneksi:

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

Ganti kode berikut:

DATABASE_UID: nama project Anda.
LOCATION: lokasi database Anda.
DATABASE_ID: ID database.

Untuk mengetahui informasi selengkapnya tentang cara mengambil UID dan lokasi, lihat Mengambil string koneksi.

Menghubungkan dengan token akses sementara

Anda dapat menggunakan token akses Google Cloud sementara untuk menjalankan alat diagnostik seperti mongosh. Anda dapat menggunakan gcloud auth print-access-token untuk mengautentikasi dengan token akses jangka pendek. Token ini valid selama satu jam.

Misalnya, gunakan perintah berikut untuk menghubungkan ke database Anda menggunakan 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'

Ganti kode berikut:

DATABASE_UID: UID database
LOCATION: lokasi database
DATABASE_ID: ID database.

Melakukan autentikasi dan terhubung ke database Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Persyaratan koneksi:

Mengambil string koneksi

Firebase console

gcloud

Menghubungkan dengan Nama pengguna dan sandi (SCRAM)

Sebelum memulai

Membuat pengguna dan menghubungkan ke database

Konsol Google Cloud

gcloud CLI

Java

Menghubungkan dengan Library Google Auth

Terhubung dari lingkungan komputasi Google Cloud

Menghubungkan dari VM Compute Engine

Sebelum memulai

Terhubung dari Cloud Run

Sebelum memulai

Mengonfigurasi kredensial

Membangun string koneksi

Menghubungkan dengan token akses sementara

Melakukan autentikasi dan terhubung ke database