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

במסמך הזה מוסבר איך לפתור שגיאות נפוצות שמתרחשות בזמן אימות סוכנים באמצעות Agent Identity ומנהל ההרשאות של 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.

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

בספקי 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_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 מהדף פרטי כניסה במסוף 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. הכלי לניהול הרשאות לא תומך בבקשה של כמה היקפי הרשאות בו-זמנית.

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

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

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

שירות חיצוני או צד נסמך יכולים לשלוח שאילתה לנקודות הקצה של זיהוי OpenID Connect של שירות אסימוני האבטחה ( Google Cloud/.well-known/openid-configuration) או של JSON Web Key Set‏ (/openid/jwks) כדי לאמת אסימון מזהה של סוכן. כששולחים שאילתות לנקודות הקצה האלה, יכול להיות שהבקשה תיכשל עם השגיאה 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 מהבקשה. נקודות הקצה /.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 בלי לשמור במטמון את התגובה. כדי לפתור את השגיאה הזו, צריך להגדיר את הכלי לאימות כך שישמור במטמון את מסמך הגילוי ואת JWKS למשך עד 24 שעות בהתאם לכותרת התגובה Cache-Control: public, max-age=86400, must-revalidate.
500 Internal Server Error השגיאה הזו מתרחשת כי השרת נתקל בבעיה פנימית זמנית במהלך אחזור מפתחות החתימה הציבוריים. כדי לפתור את השגיאה הזו, משתמשים ב-JWKS שנשמר במטמון אם הוא זמין, או מנסים שוב את הבקשה עם השהיה מעריכית לפני ניסיון חוזר.

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

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

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

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

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