אימות וחיבור למסד נתונים

רלוונטי רק למהדורת Cloud Firestore Enterprise.

דרישות החיבור

כדי להשתמש בלקוחות עם תאימות ל-MongoDB ב-Cloud Firestore, צריך:

• הנהגים צריכים להתחבר במצב load balanced. כך נמנעים ממצב שבו מנהלי ההתקנים מנסים להבין את הטופולוגיה המדויקת של השרת שאליו הם מתחברים.
• מנהלי ההתקנים חייבים להתחבר עם SSL מופעל.
• מנהלי ההתקנים צריכים להשבית כתיבות שאפשר לנסות שוב. בשלב הזה, ב-Cloud Firestore עם תאימות ל-MongoDB אין תמיכה בכתיבות שאפשר לנסות לבצע שוב.

אחזור מחרוזת החיבור

מחרוזת החיבור למסד הנתונים תלויה ב-UID של מסד הנתונים, במיקום של מסד הנתונים ובמנגנון האימות. בהוראות הבאות מוסבר איך מחברים את מחרוזת החיבור.

הערה: למסד נתונים יש גם מזהה מסד נתונים וגם UID. מזהה מסד הנתונים הוא שם המשאב שהגדרתם כשאתם יוצרים מסד נתונים. ה-UID הוא מזהה ייחודי אוניברסלי (UUID) מסוג 4 שנוצר על ידי המערכת עבור מסד הנתונים.

מחרוזת החיבור המדויקת תלויה במנגנון האימות, אבל מחרוזת החיבור הבסיסית היא בפורמט הבא:

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

אפשר לקבל את מחרוזת החיבור הבסיסית באחת מהדרכים הבאות:

מסוף Firebase

1. במסוף Firebase, עוברים לדף Firestore Database.

   מעבר אל Firestore Database

2. לוחצים על מסד הנתונים שרוצים לאמת.
3. בחלונית Explorer, לוחצים על View more.
4. בוחרים באפשרות Connect using MongoDB tools (התחברות באמצעות כלים של MongoDB).
5. מעתיקים את מחרוזת החיבור.

gcloud

כדי לאחזר את מזהה המשתמש ופרטי המיקום, משתמשים ב-gcloud firestore database describe:

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

מחליפים את DATABASE_ID במזהה מסד הנתונים.

הפלט כולל את המיקום ואת ה-UID של מסד הנתונים. השתמשו במידע הזה כדי ליצור את מחרוזת החיבור הבסיסית.

משתמשים במחרוזת הבסיסית של החיבור ובאחת מהשיטות הבאות כדי לבצע אימות ולהתחבר למסד הנתונים:

• שם משתמש וסיסמה (SCRAM)
• Compute Engine חשבון שירות
• Google Auth Library

התחברות באמצעות שם משתמש וסיסמה (SCRAM)

כדי ליצור פרטי כניסה למשתמש במסד הנתונים ולהתחבר למסד הנתונים, פועלים לפי השלבים הבאים.

לפני שמתחילים

כדי לקבל את ההרשאות שנדרשות ליצירת משתמש, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד userCredsAdmin (roles/datastore.userCredsAdmin) במסד הנתונים. מידע נוסף על הקצאת תפקידים מופיע במאמר ניהול הגישה לפרויקטים, לתיקיות ולארגונים.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

יצירת משתמש וחיבור למסד נתונים

כדי ליצור משתמש במסד נתונים של Cloud Firestore עם תאימות ל-MongoDB, משתמשים באחת מהשיטות הבאות:

מסוף Google Cloud

1. נכנסים לדף Databases במסוף Google Cloud.

   כניסה לדף Databases

2. בוחרים מסד נתונים מתוך רשימת מסדי הנתונים.
3. בתפריט הניווט, לוחצים על Auth (אימות).
4. לוחצים על הוספת משתמש.
5. מזינים שם משתמש.
6. בוחרים תפקיד למשתמש החדש.
7. לוחצים על הוספה.

   הסיסמה של המשתמש החדש תוצג בתיבת הדו-שיח לאישור.

   זהירות: הסיסמה מוצגת פעם אחת ואי אפשר לאחזר אותה. אחסון הסיסמה לשימוש עתידי.

gcloud CLI

1. כדי לבצע אימות באמצעות SCRAM, קודם צריך ליצור פרטי כניסה של משתמש. משתמשים בפקודה gcloud alpha firestore user-creds:

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

   מחליפים את מה שכתוב בשדות הבאים:
   • ‫PROJECT_NAME: שם הפרויקט.
   • ‫PROJECT_NUMBER: מספר הפרויקט.
   • ‫DATABASE_ID: מזהה מסד הנתונים.
   • ‫USERNAME: שם המשתמש שיצרתם קודם.
   • CONDITION_TITLE: שם לתנאי הזה. התנאי הזה מגביל את הגישה רק למסד הנתונים הזה.

משתמשים במחרוזת החיבור הבאה כדי להתחבר למסד הנתונים באמצעות SCRAM:

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫USERNAME: שם המשתמש.
• ‫PASSWORD: הסיסמה שיצרתם עבור המשתמש הזה.
• ‫UID: ה-UID של מסד הנתונים.
• ‫LOCATION: המיקום של מסד הנתונים.
• ‫DATABASE_ID: מזהה מסד הנתונים.

חיבור לספריית האימות של Google

בדוגמת הקוד הבאה רשום handler של קריאה חוזרת (callback) של OIDC שמשתמש בGoogle Cloud ספריית OAuth רגילה.

הספרייה הזו מאפשרת להשתמש במספר סוגים שונים של אימות (Application Default Credentials, איחוד שירותי אימות הזהות של עומסי עבודה).

לשם כך צריך להוסיף את ספריית האימות כתלות:

// 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 מזהה מסד הנתונים.

התחברות מ-VM של Compute Engine

אתם יכולים לבצע אימות ולהתחבר למסד הנתונים באמצעות חשבון שירות של Compute Engine. כדי לעשות את זה, צריך ליצור מדיניות IAM לפרויקט Google Cloud שמכיל את מסד הנתונים.

לפני שמתחילים

מגדירים חשבון שירות שמנוהל על ידי משתמש עבור המכונה הווירטואלית:

• כדי להגדיר חשבון שירות במהלך יצירת מכונה וירטואלית, אפשר לעיין במאמר יצירת מכונה וירטואלית שמשתמשת בחשבון שירות שמנוהל על ידי משתמש.
• כדי להגדיר חשבון שירות במכונה וירטואלית קיימת, ראו שינוי חשבון השירות המצורף.

רושמים את כתובת האימייל של חשבון השירות.

הגדרת פרטי כניסה

כדי לתת לחשבון השירות את התפקיד 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 והמיקום זמין במאמר אחזור מחרוזת החיבור.

התחברות באמצעות אסימון גישה זמני

אפשר להשתמש באסימון גישה זמני Google Cloud כדי להריץ כלי אבחון כמו mongosh. אפשר להשתמש ב-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: מזהה מסד נתונים