אימות סוכני ה-AI

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

אימות ל-API Google Cloud , לסוכנים ולכלים אחרים

כשעומס העבודה של Cloud Run מוגדר עם סוג הזהות agent-identity, הוא מקבל זהות שמנוהלת על ידי המערכת בפורמט הבא:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

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

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

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

אימות ל- Google Cloud APIs

סוכנים יכולים להשתמש בזהות הסוכן שהוקצתה להם כדי לבצע אימות ל-Google Cloud APIs כמו Vertex AI,‏ Cloud Storage ומוצרים אחרים שלGoogle Cloud באמצעות אסימוני גישה שנשלפים משרת המטא-נתונים של Cloud Run.

  1. נותנים לחשבון המשתמש של הסוכן את תפקיד ה-IAM המתאים, למשל:

    • איך מעניקים גישה ל-Vertex AI:

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"

    • מתן גישה לממשקי Google Cloud API אחרים:

      נותנים את התפקיד הנדרש במשאב היעד לחשבון AGENT_PRINCIPAL, לדוגמה, roles/storage.objectViewer בקטגוריה של Cloud Storage. פרטים נוספים זמינים במאמר בנושא אימות באמצעות Application Default Credentials.

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫AGENT_PRINCIPAL: הזהות של הסוכן, לדוגמה, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME.

  2. בקוד אפליקציית הסוכן, משתמשים בספריות לקוח רגילות של Google Cloud. ספריות הלקוח משתמשות אוטומטית ב-Application Default Credentials ‏ (ADC) כדי לאחזר אסימוני גישה לטווח קצר משרת המטא-נתונים.

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

    curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"

אימות לסוכנים אחרים ב-Cloud Run

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

  1. מקצים לזהות של הסוכן המתקשר את התפקיד roles/run.invoker בשירות היעד ב-Cloud Run:

    gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

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

    • ‫TARGET_SERVICE_NAME: השם של שירות הסוכן של Cloud Run ביעד.
    • ‫CALLER_AGENT_PRINCIPAL: הזהות של הסוכן ששלח את הקריאה.
    • ‫REGION: האזור Google Cloud של שירות היעד.

אפשרויות לאימות טוקנים

‫Cloud Run תומך בשתי שיטות לאימות אסימוני זהות:

  • אסימונים לא קשורים: אסימוני זהות רגילים שקשורים לקהל, שנוצרים על ידי שרת המטא-נתונים. זהו מנגנון ברירת המחדל לאימות בין שירותים ולאימות בין סוכנים.
  • טוקנים קשורים: מספקים קשר קריפטוגרפי בין הטוקן לבין האישור של עומס העבודה באמצעות mTLS. כדי להשתמש בטוקנים קשורים, הלקוח ששולח את הבקשה מספק את שרשרת אישורי העלה שלו בבקשה.
שליפת טוקן של מזהה לא קשור
  1. מתוך מאגר הסוכנים של הקריאה, מאחזרים אסימון זהות עם כתובת ה-URL של שירות היעד בתור הקהל: 
    TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
     מחליפים את TARGET_SERVICE_URL בכתובת ה-URL של שירות היעד ב-Cloud Run, לדוגמה, https://target-agent-1234567890.us-central1.run.app.
  2. שולחים בקשות לשירות היעד עם הטוקן בכותרת Authorization: 
    curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
שליפת טוקן של מזהה מאוגד (mTLS)
  1. מתוך מאגר הסוכנים שקורא, קוראים את שרשרת אישורי העלה ושולחים בקשת POST לשרת המטא-נתונים כדי לבקש טוקן מאוגד: 
    CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")
  2. מתקשרים לנקודת הקצה של mTLS של שירות היעד, ומציגים את אישורי עומס העבודה במהלך לחיצת היד של TLS: 
    KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint
דוגמה ל-Python

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

import os
import requests
import google.auth
from google.auth.transport.requests import Request
from google.oauth2 import id_token

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

מחליפים את TARGET_SERVICE_MTLS_URL בכתובת ה-URL של mTLS של שירות היעד ב-Cloud Run, לדוגמה, https://target-agent-12345.us-central1.mtls.run.app.

אימות לשרתי MCP ב-Cloud Run

כדי להתחבר לשרת או לכלי MCP שמתארחים ב-Cloud Run, צריך להשתמש במזהה --functional-type=mcp-server כדי להפעיל רישום אוטומטי של שרת ה-MCP ב-Agent Registry.

אם רק סוכנים אחרים שפועלים ב-Cloud Run ניגשים לשרת ה-MCP, צריך להשתמש בבדיקת ההפעלה המובנית של IAM. מאפשרים לסוכנים לתקשר באופן טבעי באמצעות מדיניות סטנדרטית להפעלת ריצות:

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

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

  • ‫MCP_SERVICE_NAME: השם של שירות Cloud Run ליעד שמארח את שרת ה-MCP.
  • ‫CALLING_AGENT_PRINCIPAL: זהות המשתמש של הסוכן שמפעיל את שרת ה-MCP. לדוגמה, serviceAccount:my-agent@my-project.iam..
  • ‫REGION: Google Cloud האזור שבו שרת ה-MCP פרוס.

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

כדי ללמוד איך להגן על שרתי MCP באמצעות IAP ל-CLI ולגישה ל-SDK באופן פרוגרמטי, אפשר לעיין במאמר בנושא אימות שרתי MCP.

אימות בשם משתמשים

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

כדי לטפל באופן מאובטח בתהליכי עבודה מורכבים של הרשאות, כמו הסכמה ל-OAuth תלת-רגלי (3LO),‏ OAuth דו-רגלי (2LO) ומפתחות API, צריך להגדיר את Agent Identity Auth Manager.

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