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

כדי לפתור שגיאות נפוצות שקורות כשמאמתים נציגים באמצעות Agent Identity ומנהל האימות של Agent Identity, צריך לבדוק את ההגדרות של ספק האימות, את קישורי התפקידים בניהול הזהויות והרשאות הגישה (IAM), את היקפי ההרשאות ב-OAuth ואת הגדרות האימות של אסימוני OpenID Connect ‏(OIDC).

כדי לנהל את ספקי האימות, קראו את המאמר ניהול ספקי האימות של Agent Identity. כדי לאמת טוקנים של מזהי 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 או להריץ את הפקודה add-iam-policy-binding.

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

לספקי OIDC, צריך לוודא שנקודת הקצה של המנפיק נגישה לציבור ותומכת במסמך Discovery של .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_ENABLE_RUNTIME_BOUND_TOKEN": "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 שהועברה בכותרת הבקשה שגויה, לא תקינה או לא קיימת בפרטי הכניסה של הפרויקט.

כדי לפתור את השגיאה, צריך לוודא שהעתקתם את המחרוזת הנכונה של מפתח ה-API מהדף Credentials במסוף 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 כדי לאחזר את פרטי הכניסה.

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

  • אם השגיאה הזו מתרחשת במהלך פיתוח מקומי (uv run adk web או uvicorn), ודאו שהקציתם את התפקיד לחשבון המשתמש האישי שלכם (user:USER_EMAIL).
  • אם השגיאה הזו מתרחשת כשאתם יוצרים אינטראקציה עם נציג שנפרס, ודאו שהקציתם את התפקיד לחשבון הראשי של מזהה ה-SPIFFE של הנציג (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. בודקים את המעקב לאחור של Python כדי לזהות שגיאות תחביר או לאתר חבילות חסרות.
  4. מוודאים שכל החבילות הנדרשות מופיעות בקובץ requirements.txt.

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

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

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

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

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

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

שגיאה ב-GitHub או במיקרוסופט שקשורה להיקפי הרשאות מרובים

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

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

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

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

שגיאות בנקודות הקצה של גילוי OpenID Connect ו-JWKS

שירות חיצוני או גורם מסתמך יכולים לשלוח שאילתה לנקודות הקצה של Google CloudSecurity Token Service OpenID Connect Discovery (/.well-known/openid-configuration) או של JSON Web Key Set (/openid/jwks) כדי לאמת טוקן של מזהה Agent Identity. כששולחים שאילתות לנקודות הקצה האלה, יכול להיות שהבקשה תיכשל עם אחת מהשגיאות הבאות: HTTP 400,‏ 404,‏ 429 או 500.

בטבלה הבאה מפורטות הסיבות לשגיאות האלה והפתרונות שלהן:

סטטוס HTTP מטרה רזולוציה
400 Bad Request השגיאה הזאת מתרחשת כי השם של משאב מאגר הזהויות של עומסי העבודה בכתובת ה-URL של הבקשה לא תקין, או שהבקשה כוללת כותרת HTTP מסוג Authorization. כדי לפתור את השגיאה:
  • מוודאים ששם המשאב של מאגר הזהויות של עומסי העבודה משתמש בפורמט נתמך של מתחם אמון של נציג (agents.global.org-ORGANIZATION_ID.system.id.goog או agents.global.proj-PROJECT_NUMBER.system.id.goog).
  • מסירים מהבקשה את כל הכותרות של Authorization או OAuth. נקודות הקצה (endpoint) /.well-known/openid-configuration ו-/openid/jwks גלויות לכולם ולא מחייבות אימות. אם מעבירים כותרות אימות, הבקשה נכשלת ומוצגת השגיאה HTTP 400.
404 Not Found השגיאה הזו מתקבלת כי מזהה הארגון, מספר הפרויקט או מאגר הזהויות של עומסי העבודה שצוינו לא קיימים, או כי נתיב כתובת ה-URL שגוי. כדי לפתור את השגיאה, צריך לוודא שמזהה הארגון, מספר הפרויקט ומתחם האמון (מזהה מאגר הזהויות של עומסי העבודה) בכתובת ה-URL מדויקים. צריך גם לוודא שנתיב כתובת ה-URL מסתיים ב-/.well-known/openid-configuration או ב-/openid/jwks.
429 Too Many Requests השגיאה הזו מתרחשת כי הגורם המאמת חרג ממגבלת קצב הבקשות, על ידי שליחת שאילתות לנקודות הקצה של הגילוי או של JWKS בלי לשמור את התגובה במטמון. כדי לפתור את השגיאה הזו, צריך להגדיר את הגורם המאמת כך שישמור במטמון את מסמך ה-Discovery ואת ה-JWKS למשך עד 24 שעות, בהתאם לכותרת התגובה Cache-Control: public, max-age=86400, must-revalidate.
500 Internal Server Error השגיאה הזו מתרחשת כי השרת נתקל בבעיה פנימית זמנית בזמן אחזור מפתחות החתימה הציבוריים. כדי לפתור את השגיאה, צריך להשתמש ב-JWKS שנשמר במטמון אם הוא זמין, או לנסות שוב את הבקשה עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).

אימות החתימה של הטוקן נכשל אחרי רוטציית מפתחות

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

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

כדי לפתור את הבעיה, צריך להגדיר את הגורם המאמת כך שכשהוא מקבל אסימון עם kid לא מזוהה, הוא יאחזר JWKS חדש מנקודת הקצה (endpoint) של /openid/jwks לפני שהוא דוחה את האסימון.

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