הגדרת קהלים בהתאמה אישית לשירותים

בדף הזה מוסבר איך להשתמש בקהלים בהתאמה אישית לצורך הרשאה.

לקוחות שקוראים לשירות Cloud Run שמוגן על ידי ניהול זהויות והרשאות גישה (IAM) צריכים לספק אסימון מזהה תקין שכולל הצהרת קהל (aud) שתואמת לכתובת ה-URL של שירות הקבלה *.run.app. לקוחות שלא יודעים מה כתובת ה-URL הזו יכולים להשתמש בערך של קהל בהתאמה אישית.

הסבר על קהלים בהתאמה אישית

ב-Cloud Run יש תפקיד Invoker ‏ (roles/run.invoker) שתומך בבקרת גישה באמצעות IAM. בבקרת הגישה של IAM נעשה שימוש באסימונים מזהים בחתימת Google, שמגיעים כאסימוני JWT (‏JSON Web Tokens). התוכן של האסימונים האלה תואם לתקן OIDC.

שדה קהל מקודד באסימון כדי לציין את היעד המיועד שיכול להשתמש באסימון. כך מצמצמים את הסיכון להתקפת שידור חוזר (replay), שבה טוקן שיועד לשימוש בשירות אחד משודר מחדש נגד שירות אחר.

לפי המוסכמה, הקהל הוא כתובת ה-URL המלאה של שירות היעד. כברירת מחדל ב-Cloud Run, זוהי כתובת ה-URL שנוצרה על ידי Google לשירות שמסתיים ב-run.app.

עם זאת, שירות Cloud Run יכול להיות מאחורי כתובת URL שונה מכתובת ה-URL שנוצרת כברירת מחדל, למשל בתרחישים הבאים:

• כשמשתמשים בדומיין בהתאמה אישית כדי לגשת לשירות שבו הלקוח לא מודע לכתובת ה-URL שנוצרה על ידי Google.
• כשפורסים כמה שירותים מאחורי מאזן עומסים, הלקוח לא יכול לדעת לאיזה שירות אזורי הבקשה תגיע. כתובות URL של שירותים שנוצרו על ידי Google הן ספציפיות לאזור, גם אם שם השירות זהה.

בתרחישים האלה, צריך להגדיר שירות שיקבל ערכים של קהלים מותאמים אישית, שיאפשרו ללקוח להגדיר טירגוטים נוספים. כתובת ה-URL שנוצרה על ידי Google תמיד תישאר ערך קהל מקובל.

הגדרה ועדכון של קהלים בהתאמה אישית

הגדרת קהלים בהתאמה אישית ב-Cloud Run מתבצעת ברמת השירות, והיא חלה על כל הגרסאות של השירות, בדומה לחברות בהרשאות של IAM.

אפשר להגדיר כמה קהלים בהתאמה אישית, כל עוד קידוד ה-JSON של הקהלים כרשימת מחרוזות לא חורג מ-32,768 תווים.

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

gcloud

כדי להגדיר קהלים בהתאמה אישית בשירות, אפשר להשתמש בפקודה הבאה:

gcloud run services update SERVICE --add-custom-audiences=AUDIENCE

החלפה

• ‫SERVICE בשם של שירות Cloud Run
• ‫AUDIENCE עם מחרוזת לקהל המותאם אישית שרוצים לתמוך בו, לדוגמה, myservice או https://myservice.example.com

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

gcloud run services update SERVICE --clear-custom-audiences

YAML

1. אם אתם יוצרים שירות חדש, דלגו על השלב הזה. אם אתם מעדכנים שירות קיים, אתם צריכים להוריד את הגדרות ה-YAML שלו:

   gcloud run services describe SERVICE --format export > service.yaml

2. מגדירים את ההערה run.googleapis.com/custom-audiences במטא-נתונים של השירות (לא במטא-נתונים template):

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
     annotations:
       run.googleapis.com/custom-audiences: '["AUDIENCE"]'
   spec:
     template:
       ...

   החלפה

   • ‫SERVICE בשם של שירות Cloud Run
   • ‫AUDIENCE עם מחרוזת לקהל המותאם אישית שרוצים לתמוך בו, לדוגמה, myservice או https://myservice.example.com

   שימו לב שהערך של המאפיין הוא מערך JSON של מחרוזות שמוקף במירכאות, ולכן צריך להשתמש גם במירכאות כפולות וגם במירכאות בודדות.

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

   gcloud run services replace service.yaml

Terraform

כדי ללמוד איך להחיל הגדרות ב-Terraform או להסיר אותן, ראו פקודות בסיסיות ב-Terraform.

מוסיפים את השורות הבאות למשאב google_cloud_run_v2_service בתצורת Terraform:

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  location = "REGION"

  custom_audiences = ["AUDIENCE"]
  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }
}

מחליפים את:

• ‫SERVICE מחליפים בשם של שירות Cloud Run.
• ‫REGION עם האזור Google Cloud . לדוגמה: europe-west1.
• ‫AUDIENCE עם מחרוזת לקהל בהתאמה אישית שרוצים לתמוך בו, לדוגמה, myservice.

אימות של קהלים בהתאמה אישית

1. קבלת אסימון מזהה לחשבון שירות שיש לו הרשאת IAM להפעלת השירות. שימו לב לשימוש בקהל בהתאמה אישית AUDIENCE.

   export TOKEN=$(gcloud auth print-identity-token --impersonate-service-account SERVICE_ACCOUNT_EMAIL --audiences='AUDIENCE')

   מחליפים את:

   • ‫SERVICE_ACCOUNT_EMAIL מחליפים בכתובת האימייל של חשבון השירות. הוא מסתיים ב-.iam.gserviceaccount.com.
   • ‫AUDIENCE עם הערך של הקהל בהתאמה אישית שהגדרתם בשירות.

2. קוראים לנקודת הקצה של השירות עם אסימון המזהה הזה

   curl -H "Authorization: Bearer ${TOKEN}" ENDPOINT

   מחליפים את ENDPOINT בנקודת הקצה שאליה מגיעים כשניגשים לשירות, לדוגמה, הדומיין המותאם אישית או כתובת ה-URL .run.app.

3. מוודאים שהבקשה מורשית ורואים את התגובה הצפויה של השירות.