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

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

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

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

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

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

לפי המוסכמה, הקהל הוא כתובת ה-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. מוודאים שהבקשה מורשית ורואים את התגובה הצפויה של השירות.