פתרון בעיות באימות הזהות של נציגים

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

הוראות להגדרת ספקי אימות מפורטות במאמר ניהול ספקי אימות של Agent Identity.

אי התאמה של ה-URI של ההפניה האוטומטית

אם אתם מקבלים שגיאה redirect URI mismatch מהאפליקציה של הצד השלישי במהלך תהליך OAuth, אתם צריכים לוודא שכתובת ה-URI של ההפניה האוטומטית שרשומה בפורטל המפתחים של הצד השלישי זהה בדיוק לכתובת ה-URI שנוצרה על ידי מנהל ההרשאות.

כדי לפתור את הבעיה, צריך למצוא את מזהה ה-URI להפניה אוטומטית שנוצר. לשם כך, אפשר לעיין בפרטים של ספק האימות במסוף Google Cloud או להריץ את הפקודה הבאה של gcloud:

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

חסר תפקיד משתמש

אם הסוכן לא יכול להשתמש בספק האימות, צריך לוודא שלזהות הסוכן יש את התפקיד roles/agentidentity.user במשאב של ספק האימות.

כדי לפתור את הבעיה, צריך להקצות את התפקיד באמצעות מסוף Google Cloud Google Cloud או להריץ את הפקודה add-iam-policy-binding.

בעיות בנקודות קצה של מנפיק

בספקי OIDC, צריך לוודא שנקודת הקצה של המנפיק נגישה לציבור ותומכת במסמך האיתור .well-known/openid-configuration.

אם Google Cloud לא יכול לאחזר את המטא-נתונים של ה-OIDC או את ה-JWKS, צריך לוודא שנקודת הקצה לא נמצאת מאחורי חומת אש או רשת מוגבלת.

שגיאה 401 UNAUTHENTICATED

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

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

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

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

שירות מפתח ה-API נחסם (API_KEY_SERVICE_BLOCKED)

אם מאמתים את מפתח ה-API, יכול להיות שתופיע השגיאה הבאה. השגיאה הזו מעידה על כך שהשירות חסום:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

השגיאה הזו מתרחשת כי שירות ה-API של היעד (לדוגמה, Cloud Translation API) לא הופעל ב Google Cloud פרויקט, או שההגבלות של מפתח ה-API לא מאפשרות גישה לשירות הזה.

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

  1. במסוף Google Cloud , עוברים לדף APIs & Services >Library ומוודאים שממשק ה-API של היעד מופעל.

    עוברים אל APIs & Services >Library

  2. במסוף Google Cloud , עוברים לדף APIs & Services >Credentials, עורכים את מפתח ה-API ומוודאים שההגבלות על ה-API מאפשרות גישה לשירות.

    עוברים אל APIs & Services >Credentials

מפתח API לא תקין (API_KEY_INVALID)

יכול להיות שתיתקלו בשגיאה הבאה כשאתם שולחים בקשות לשירות של צד שלישי. השגיאה הזו מציינת שמפתח ה-API לא תקין:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

השגיאה הזו מתרחשת כי המחרוזת של מפתח ה-API שמועברת ב-request header שגויה, לא תקינה או לא קיימת בפרטי הכניסה של הפרויקט.

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

נדחתה ההרשאה לאחזור פרטי הכניסה (agentidentity.authProviders.retrieveCredentials)

כשמריצים את adk web באופן מקומי או מקיימים אינטראקציה עם הסוכן שפרסתם, יכול להיות שתופיע השגיאה 403 Forbidden:

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

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

כדי לפתור את השגיאה, צריך להעניק את התפקיד Agent Identity User (roles/agentidentity.user) לחשבון הראשי:

  • אם השגיאה הזו מתרחשת במהלך פיתוח מקומי (uv run adk web או uvicorn), צריך לוודא שהקציתם את התפקיד לחשבון המשתמש האישי שלכם (user:USER_EMAIL).
  • אם השגיאה הזו מתרחשת כשמבצעים אינטראקציה עם סוכן שפרסתם, צריך לוודא שהענקתם את התפקיד למנהל ה-SPIFFE ID של הסוכן (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

כשל כללי בפריסה

כשפורסים את הסוכן באמצעות uv run adk deploy, יכול להיות שהפקודה תיכשל ותוצג הודעת שגיאה כללית.

השגיאה הזו מתרחשת בגלל תלות חסרה ב-Python, שגיאות תחביר ב-agent.py או משתני סביבה שהוגדרו בצורה שגויה.

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

  1. פותחים את מסוף Google Cloud ועוברים לדף Logs Explorer.
  2. מחפשים את היומנים של מאגר התגים הזמני לפריסה (לדוגמה, maps_mcp_agent_tmp... או bigquery_mcp_agent_tmp...).
  3. בודקים את ה-traceback של Python כדי לזהות שגיאות תחביר או לעקוב אחרי חבילות חסרות.
  4. מוודאים שכל החבילות הנדרשות מופיעות בקובץ requirements.txt.

לולאת אימות או היקפי הרשאות לא צפויים ב-ServiceNow

כשנציג מאומת ב-ServiceNow באמצעות OAuth תלת-רגלי, יכול להיות שתהליך האימות ייכשל או שהנציג ייכנס ללולאת בקשות.

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

כדי לפתור את הבעיה:

  1. נכנסים לחשבון ServiceNow כאדמינים.
  2. עוברים להגדרת אפליקציית OAuth ב-ServiceNow.
  3. חשוב לוודא שכל ההיקפים שהסוכן שלכם צריך נוספו במפורש לרשימת ההיקפים המותרים של האפליקציה.
  4. מגדירים את הסוכן כך שיבקש רק את ההיקפים שהופעלו ב-ServiceNow.

מידע נוסף זמין במאמר בנושא שירותים נתמכים של צדדים שלישיים.

שגיאה לגבי היקפים מרובים ב-GitHub או ב-Microsoft

כשמגדירים ספק אימות ל-GitHub או ל-Microsoft, האימות נכשל אם מבקשים כמה היקפי הרשאות של OAuth.

מנהל ההרשאות תומך בשילובים עם היקף יחיד עבור GitHub ו-Microsoft. מנהל ההרשאות לא תומך בבקשה של כמה היקפי הרשאות בו-זמנית.

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

מידע נוסף זמין במאמר בנושא שירותים נתמכים של צדדים שלישיים.

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