احراز هویت و اتصال به پایگاه داده

فقط مربوط به Cloud Firestore Enterprise edition.

الزامات اتصال

موارد زیر برای Cloud Firestore با مشتریان سازگاری MongoDB مورد نیاز است:

  • رانندگان باید در حالت load balanced متصل شوند. این مانع از تلاش درایورها برای درک توپولوژی سرور دقیقی می شود که به آن متصل می شوند.
  • درایورها باید با SSL فعال وصل شوند.
  • درایورها باید نوشتن های قابل امتحان مجدد را غیرفعال کنند. Cloud Firestore با سازگاری MongoDB از نوشتن های قابل امتحان مجدد پشتیبانی نمی کند. نیازی نیست خواندن های قابل امتحان مجدد را غیرفعال کنید زیرا پشتیبانی می شوند.

رشته اتصال را بازیابی کنید

رشته اتصال پایگاه داده به UID پایگاه داده، محل پایگاه داده و مکانیزم احراز هویت بستگی دارد. دستورالعمل های زیر نحوه تشکیل رشته اتصال را توضیح می دهد.

رشته اتصال دقیق به مکانیزم احراز هویت بستگی دارد، اما رشته اتصال پایه از فرمت زیر استفاده می کند:

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

می توانید رشته اتصال پایه را به یکی از روش های زیر بدست آورید:

کنسول Firebase
  1. در کنسول Firebase ، به صفحه Firestore Database بروید.

    به پایگاه داده Firestore بروید

  2. روی پایگاه داده ای که می خواهید احراز هویت کنید کلیک کنید.
  3. در پانل Explorer ، روی View more کلیک کنید.
  4. Connect using MongoDB tools را انتخاب کنید.
  5. رشته اتصال را کپی کنید.
gcloud

gcloud firestore database describe برای بازیابی UID و اطلاعات مکان استفاده کنید:

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

DATABASE_ID با شناسه پایگاه داده جایگزین کنید.

خروجی شامل مکان و UID پایگاه داده است. از این اطلاعات برای ساخت رشته اتصال پایه استفاده کنید.

از رشته اتصال پایه و یکی از روش های زیر برای احراز هویت و اتصال به پایگاه داده خود استفاده کنید:

اتصال با نام کاربری و رمز عبور (SCRAM)

این مراحل را دنبال کنید تا یک اعتبار کاربری برای پایگاه داده خود ایجاد کنید و به پایگاه داده خود متصل شوید.

قبل از شروع

برای دریافت مجوزهایی که برای ایجاد کاربر نیاز دارید، از سرپرست خود بخواهید نقش userCredsAdmin ( roles/datastore.userCredsAdmin ) IAM را در پایگاه داده شما به شما اعطا کند. برای اطلاعات بیشتر درباره اعطای نقش، به مدیریت دسترسی به پروژه‌ها، پوشه‌ها و سازمان‌ها مراجعه کنید.

همچنین ممکن است بتوانید مجوزهای لازم را از طریق نقش های سفارشی یا سایر نقش های از پیش تعریف شده دریافت کنید.

یک کاربر ایجاد کنید و به پایگاه داده متصل شوید

برای ایجاد یک کاربر برای Cloud Firestore خود با پایگاه داده سازگاری MongoDB، از یکی از روش های زیر استفاده کنید:

کنسول Google Cloud
  1. در کنسول Google Cloud، به صفحه پایگاه داده بروید.

    به پایگاه داده ها بروید

  2. یک پایگاه داده را از لیست پایگاه های داده انتخاب کنید.
  3. در منوی پیمایش، روی تأیید کلیک کنید.
  4. روی افزودن کاربر کلیک کنید.
  5. یک نام کاربری وارد کنید.
  6. نقشی را برای کاربر جدید انتخاب کنید.
  7. روی افزودن کلیک کنید.

    رمز عبور کاربر جدید در گفتگوی تایید نمایش داده می شود.

gcloud CLI
  1. برای احراز هویت با SCRAM، ابتدا باید یک اعتبار کاربری ایجاد کنید. از دستور gcloud firestore user-creds استفاده کنید:
    gcloud firestore user-creds create USERNAME --database=DATABASE_ID
    موارد زیر را جایگزین کنید:
    • USERNAME : نام کاربری برای ایجاد.
    • DATABASE_ID : شناسه پایگاه داده.

    خروجی این دستور شامل رمز عبور کاربر است.

    خروجی شبیه موارد زیر است:

    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. به طور پیش فرض، این اعتبار کاربری جدید هیچ مجوزی ندارد. برای دسترسی خواندن و نوشتن به پایگاه داده، نقش roles/datastore.user را برای این پایگاه داده خاص اضافه کنید:

    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"'
    موارد زیر را جایگزین کنید:
جاوا

این بخش یک مثال کد برای ایجاد اعتبار کاربری و پیکربندی خط مشی IAM با استفاده از کتابخانه های مشتری مدیریت جاوا ارائه می دهد. نمونه از کتابخانه Firestore Admin Client برای ایجاد نام کاربری و رمز عبور و از کتابخانه Google Cloud Resource Manager برای پیکربندی IAM استفاده می کند.

برای ساخت های Maven، می توانید از مختصات زیر استفاده کنید:

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

ارائه اعتبار کاربری و یک خط مشی 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);
    }
  }
}
پایتون

این بخش یک مثال کد برای ایجاد اعتبار کاربری و پیکربندی خط مشی IAM با استفاده از کتابخانه های مشتری مدیریت پایتون ارائه می دهد. نمونه از کتابخانه کتابخانه سرویس گیرنده Google Cloud Firestore API برای ایجاد نام کاربری و رمز عبور و از کتابخانه سرویس گیرنده Google Cloud Iam API و کتابخانه سرویس گیرنده Google Cloud Resource API برای پیکربندی IAM استفاده می کند.

کتابخانه های پایتون مورد نیاز را می توان با ابزار pip نصب کرد:

pip install google-cloud-iam
pip install google-cloud-firestore
pip install google-cloud-resource-manager

ارائه اعتبار کاربری و یک خط مشی IAM:

from google.cloud import resourcemanager_v3
from google.cloud.firestore_admin_v1 import FirestoreAdminClient
from google.cloud.firestore_admin_v1 import types
from google.iam.v1 import iam_policy_pb2
from google.iam.v1 import policy_pb2
from google.type import expr_pb2


def create_user_creds(project_id: str, database_id: str, user_name: str):
  """Provision new user credentials using the FirestoreAdminClient."""
  client = FirestoreAdminClient()
  request = types.CreateUserCredsRequest(
      parent=f'projects/{project_id}/databases/{database_id}',
      user_creds_id=user_name,
  )
  response = client.create_user_creds(request)
  return response


def update_iam_policy_for_user_creds(
    project_id: str, database_id: str, user_name: str, user_creds
):
  """Update the IAM policy using the Resource Manager ProjectsClient."""
  client = resourcemanager_v3.ProjectsClient()
  request = iam_policy_pb2.GetIamPolicyRequest()
  request.resource = f'projects/{project_id}'
  request.options.requested_policy_version = 3

  # Get the current IAM policy
  current_policy = client.get_iam_policy(request)

  # Construct an updated IAM policy with an additional binding
  # for the user credentials.
  updated_policy = policy_pb2.Policy()
  binding = policy_pb2.Binding()
  iam_condition = expr_pb2.Expr()

  iam_condition.title = f'Conditional IAM binding for {user_name}'
  iam_condition.expression = (
      f'resource.name == "projects/{project_id}/databases/{database_id}"'
  )

  binding.role = 'roles/datastore.user'
  binding.condition.CopyFrom(iam_condition)
  binding.members.append(user_creds.resource_identity.principal)
  updated_policy.bindings.append(binding)

  # Update the policy
  updated_policy.MergeFrom(current_policy)
  set_policy_request = iam_policy_pb2.SetIamPolicyRequest()
  set_policy_request.resource = f'projects/{project_id}'
  set_policy_request.policy.CopyFrom(updated_policy)

  final_policy = client.set_iam_policy(set_policy_request)
  print(f'Policy updated successfully {final_policy}')


def provision_firestore_user_creds_and_iam(
    project_id: str, database_id: str, user_name: str
):
  """Provision user credentials and configure an IAM policy."""
  user_creds = create_user_creds(project_id, database_id, user_name)

  # Note the password returned in the UserCreds proto - it cannot be
  # retrieved again after the initial call to the create_user_creds API.
  print(f'Created credentials for username: {user_name}')
  print(f'IAM principal: {user_creds.resource_identity.principal}')
  print(f'Password: [{user_creds.secure_password}]')

  # Provision an IAM binding for the principal associated with
  # these user credentials.
  update_iam_policy_for_user_creds(
      project_id, database_id, user_name, user_creds
  )

  # Emit the password again
  print(
      f'Successfully configured IAM policy for database: {database_id},'
      f' username: {user_name}'
  )
  print(f'Please make a note of the password: [{user_creds.secure_password}]')

از رشته اتصال زیر برای اتصال به پایگاه داده خود با SCRAM استفاده کنید:

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

موارد زیر را جایگزین کنید:

  • USERNAME : نام کاربری.
  • PASSWORD : رمز عبوری که برای این کاربر ایجاد کرده اید.
  • UID : UID پایگاه داده.
  • LOCATION : مکان پایگاه داده.
  • DATABASE_ID : شناسه پایگاه داده.

با کتابخانه Google Auth متصل شوید

نمونه کد زیر یک کنترل کننده تماس OIDC را با استفاده از کتابخانه استاندارد OAuth Google Cloud ثبت می کند.

این کتابخانه به شما امکان می دهد از انواع مختلف احراز هویت (Application Default Credentials، Workload Identity Federation) استفاده کنید.

این نیاز به افزودن کتابخانه اعتبار به عنوان یک وابستگی دارد:

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

نمونه کد زیر نحوه اتصال را نشان می دهد:

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

موارد زیر را جایگزین کنید:

  • DATABASE_UID : نام پروژه شما.
  • LOCATION : مکان پایگاه داده شما.
  • DATABASE_ID شناسه پایگاه داده.

از یک محیط محاسباتی Google Cloud متصل شوید

این بخش اتصال به Cloud Firestore با سازگاری MongoDB از یک محیط محاسباتی Google Cloud ، مانند Compute Engine یا یک سرویس یا کار Cloud Run را توضیح می‌دهد.

از یک Compute Engine وصل شوید

شما می توانید با استفاده از حساب خدمات Compute Engine ، احراز هویت و اتصال به پایگاه داده خود را انجام دهید. برای انجام این کار، یک خط مشی IAM برای پروژه Google Cloud ایجاد کنید که حاوی پایگاه داده شما است.

قبل از شروع

یک حساب سرویس مدیریت شده توسط کاربر برای VM خود پیکربندی کنید:

برای تکمیل پیکربندی خط مشی IAM برای حساب خدمات Compute Engine خود، دستورالعمل‌های بخش Configure credentials را ببینید.

از Cloud Run متصل شوید

می توانید با استفاده از حساب سرویس Cloud Run احراز هویت و اتصال به پایگاه داده خود را انجام دهید. برای انجام این کار، یک خط مشی IAM برای پروژه Google Cloud ایجاد کنید که حاوی پایگاه داده شما است.

قبل از شروع

برای تکمیل پیکربندی خط مشی IAM برای حساب سرویس Cloud Run خود، به دستورالعمل‌های بخش پیکربندی اعتبارنامه‌ها مراجعه کنید.

اعتبارنامه ها را پیکربندی کنید

برای اعطای نقش roles/datastore.user به حساب سرویس برای خواندن و نوشتن در Cloud Firestore ، دستور زیر را اجرا کنید:

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

موارد زیر را جایگزین کنید:

  • PROJECT_NAME : نام پروژه شما.
  • SERVICE_ACCOUNT_EMAIL : آدرس ایمیل حساب سرویسی که ایجاد کردید.

رشته اتصال را بسازید

برای ساخت رشته اتصال از فرمت زیر استفاده کنید:

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

موارد زیر را جایگزین کنید:

  • DATABASE_UID : نام پروژه شما.
  • LOCATION : مکان پایگاه داده شما.
  • DATABASE_ID شناسه پایگاه داده.

برای اطلاعات بیشتر در مورد بازیابی UID و مکان، به بازیابی رشته اتصال مراجعه کنید.

با یک نشانه دسترسی موقت متصل شوید

برای اجرای ابزارهای تشخیصی مانند mongosh می‌توانید از یک نشانه دسترسی موقت Google Cloud استفاده کنید. می‌توانید از gcloud auth print-access-token برای احراز هویت با یک نشانه دسترسی کوتاه‌مدت استفاده کنید. این توکن یک ساعت اعتبار دارد.

به عنوان مثال، از دستور زیر برای اتصال به پایگاه داده خود با 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'

موارد زیر را جایگزین کنید:

  • DATABASE_UID : UID پایگاه داده
  • LOCATION : مکان پایگاه داده
  • DATABASE_ID : شناسه پایگاه داده