אימות באמצעות הרשאה של סוכן

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

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

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

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

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

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

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

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

הענקת גישה לסוכנים

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

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

כדי להעניק לסוכן גישה למשאב, משתמשים במסוף Google Cloud או ב-CLI של gcloud.

המסוף

  1. במסוף Google Cloud , נכנסים לדף IAM של המשאב שרוצים להעניק לו גישה.
    • כדי להגדיר הרשאות לפרויקט, עוברים לדף IAM:

      כניסה לדף IAM

    • למשאבים אחרים, עוברים לדף של המשאב הרלוונטי ולוחצים על הכרטיסייה הרשאות או IAM.
  2. לוחצים על Grant Access.
  3. בשדה New principals, מזינים את מזהה חשבון המשתמש שמתאים לרמת הגישה שרוצים להעניק:
    • נציג אחד: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • כל הסוכנים בפרויקט: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • כל הנציגים בארגון: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. בשדה Select a role (בחירת תפקיד), מחפשים את התפקיד שרוצים להקצות ובוחרים אותו.
  5. לוחצים על Save.

Google Cloud CLI

כדי להעניק לסוכן גישה למשאב, מריצים את הפקודה הבאה: 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

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

  • ‫SERVICE: השירות Google Cloud (לדוגמה, storage או bigquery).
  • ‫RESOURCE_NAME: שם המשאב (לדוגמה, שם הקטגוריה או מזהה מערך הנתונים).
  • ‫PRINCIPAL_IDENTIFIER: מזהה החשבון הראשי שתואם לרמת הגישה שרוצים להעניק:
    • סוכן יחיד: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • כל הסוכנים בפרויקט: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • כל הנציגים בארגון: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ‫ORGANIZATION_ID: מזהה הארגון ב- Google Cloud .
  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
  • ‫LOCATION: המיקום של הסוכן (לדוגמה, us-central1). (חובה רק לגישה של סוכן יחיד).
  • ‫ENGINE_ID: המזהה של מנוע הנימוקים. (נדרש רק לגישה של סוכן יחיד).
  • ‫ROLE: תפקיד ה-IAM שרוצים להקצות.

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

ספריות הלקוח משתמשות אוטומטית בזהות הסוכן כשהסוכן שלכם נפרס בסביבה נתמכת. Google Cloud Google Cloud

בקטע הקוד הבא ב-Python אפשר לראות איך להשתמש באופן ידני בפרטי הכניסה של זהות הסוכן כדי לקרוא ל-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 Gateway, המדיניות אוכפת הוכחה ניתנת להצגה של בעלות (DPoP) על ידי אימות אסימון הגישה של הסוכן. המדיניות גם מחייבת שימוש ב-mTLS כדי לגשת ל-Agent Gateway. כך אפשר לוודא שאפשר להשתמש באסימונים שמשויכים לאישור רק בסביבת זמן הריצה המיועדת והמהימנה שלהם (לדוגמה, קונטיינר של Cloud Run). הגדרת בסיס האבטחה הזה מונעת שימוש חוזר בהרשאות גישה גנובות, ועוזרת להגן מפני גניבת הרשאות גישה והשתלטות על החשבון (ATO).

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

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

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

פריסת הסוכן

כשפורסים את הסוכן ב- Google Cloud, חשוב לוודא שאימות הזהות של הסוכן מופעל. אם אתם פורסים ל-Agent Runtime, משתמשים בדגל 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]"],
    },
)

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