אימות ב-Cloud de Confiance באמצעות הזהות של הסוכן

הסוכנים יכולים לגשת לממשקי API של Cloud de Confiance ולמשאבים אחרים באמצעות הזהות שלהם. ‫Google ממליצה על השיטה הזו לנציגים שמתארחים ב- Cloud de Confianceכדי ליצור אינטראקציה עם שירותים אחרים של Cloud de Confiance .

כשהסוכן פועל לפי ההרשאות שלו, הוא משתמש בזהות SPIFFE הראשית שלו כדי לבקש אסימוני גישה ל- Cloud de Confiance .

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

1. מוודאים שבחרתם בשיטת האימות הנכונה.
2. יוצרים ופורסים סוכן עם Agent Identity מופעל.
3. מוודאים שיש לכם את התפקידים הנדרשים כדי להשלים את המשימה.

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות בשביל לתת לסוכן גישה לשירותי Cloud de Confiance , אתם צריכים לבקש מהאדמין לתת לכם את התפקידים הבאים ב-IAM ברמת המשאב:

• כדי לתת גישה לסוכן:
  • אדמין IAM בפרויקט (roles/resourcemanager.projectIamAdmin)
  • אדמין אבטחה (roles/iam.securityAdmin)
• תפקידים מומלצים לזהות הסוכן:
  • עורך ההקשר של הסוכן (roles/aiplatform.agentContextEditor)
  • גישת ברירת המחדל של הסוכן (roles/aiplatform.agentDefaultAccess)
  • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
  • דפדפן (roles/browser)
  • צפייה באובייקטים באחסון (roles/storage.objectViewer)

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

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

מתן גישה לסוכנים

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

במדיניות ההרשאות של IAM, זהויות של סוכנים משתמשות במזהי חשבונות משתמשים.

כדי לתת לסוכן גישה למשאב, משתמשים במסוף Cloud de Confiance או ב-CLI של gcloud.

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

הפניה לזהות הסוכן בקוד

ספריות הלקוח של Cloud de Confiance משתמשות באופן אוטומטי ב-Agent Identity כשהסוכן נפרס בסביבה נתמכת של Cloud de Confiance .

קטע הקוד הבא ב-Python מראה איך להשתמש באופן ידני בפרטי הכניסה של Agent Identity כדי להפעיל את Cloud Vision API באמצעות הערכה לפיתוח סוכנים (ADK).

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

אופציונלי: ביטול ההסכמה לשימוש באסימונים שקשורים לאישורים

מדיניות ברירת מחדל של בקרת גישה מבוססת-הקשר בניהול Google עוזרת לאבטח את פרטי הכניסה של Agent Identity. מעבר ל-Agent Gateway, המדיניות אוכפת את Demonstrating Proof of Possession (DPoP)‎ באמצעות אימות של טוקן הגישה של הסוכן. כדי לגשת ל-Agent Gateway, המדיניות דורשת גם Mutual TLS ‏ (mTLS). הדרישה הזו עוזרת להבטיח שרק סביבת זמן הריצה המהימנה והמיועדת, כמו קונטיינר של Cloud Run או Pod של Google Kubernetes Engine (GKE), תוכל להשתמש באסימונים שקשורים לאישור. בזכות רמת האבטחה הבסיסית הזו, לא ניתן להשתמש שוב בפרטי כניסה גנובים, וכך אפשר להגן מפני גניבת פרטי כניסה והשתלטות על החשבון (ATO).

קישור אישורים עוזר להגן על שני סוגים של פרטי כניסה של סוכנים:

• Cloud de Confiance טוקני גישה: טוקני גישה מסוג OAuth 2.0 לטווח קצר, שמאמתים בקשות לממשקי API של Cloud de Confiance ולמשאבים אחרים (*.googleapis.com).
• טוקנים של מזהה OpenID Connect ‏ (OIDC): אסימוני JWT (‏JSON Web Tokens) שמאמתים בקשות לשירותים חיצוניים ולכלים ולשירותים שמתארחים ב Cloud de Confiance סביבות זמן ריצה, כמו Cloud Run (*.mtls.run.app) או GKE.

ביטול ההסכמה לקישור של כל אסימוני הגישה והאסימונים המזהים

לא מומלץ לבטל את ההסכמה למדיניות ברירת המחדל של בקרת גישה מבוססת-הקשר ואסימונים שמקושרים לאישורים בסביבת זמן הריצה. ההגדרה GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false מסירה את ההגנה של קישור האסימונים גם לטוקני גישה וגם לטוקנים של מזהה של OIDC, מה שהופך את האסימונים האלה לטווח קצר לפגיעים לגניבה או להתקפות של הפעלה מחדש. Cloud de Confiance

עם זאת, אתם יכולים לבטל את ההסכמה בסביבת זמן הריצה במקרים הנדירים הבאים:

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

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

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

ביטול ההסכמה לבקשות ספציפיות של טוקן מזהה

כברירת מחדל, ספריות הלקוח הנתמכות של Google Auth מקשרות באופן קריפטוגרפי טוקנים של מזהי OIDC לאישור X.509 הייחודי של הנציג, על ידי הכללת טביעת האצבע של האישור בטענת הנכוֹנוּת (claim) של cnf (x5t#S256) בטוקן.

שירותים מסוימים, כמו Cloud Run, אוכפים קישור אישורים כשהתביעה cnf קיימת. אם הנציג שלכם שולח קריאה לשירותים האלה דרך נקודת קצה שאינה mTLS, כמו כתובת URL רגילה של *.run.app, או אם נקודת קצה לא דורשת קישור אישור, אתם יכולים לבטל את ההסכמה לבקשות ספציפיות של טוקן מזהה. ההגדרה הזו משפיעה רק על הבקשה הזו ולא משביתה את הקישור של האישור לטוקני הגישה של Cloud de Confiance .

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

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

פריסת הנציג

כשפורסים את הנציג ב- Cloud de Confiance by S3NS, צריך לוודא ש-Agent Identity מופעל. אם אתם פורסים ב-Agent Runtime ב-Gemini Enterprise Agent Platform, השתמשו בדגל identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

המאמרים הבאים

• אימות מול שירותים חיצוניים באמצעות הזהות של הנציג
• אימות באמצעות OAuth דו-רגלי עם מנהל אימות
• אימות באמצעות OAuth תלת-רגלי עם מנהל אימות
• אימות באמצעות מפתח API עם מנהל אימות
• ניהול ספקי האימות של Agent Identity
• סקירה כללית על Agent Identity