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

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

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

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

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

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

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

אם הסוכן לא יכול להשתמש בספק האימות, צריך לוודא שלזהות הסוכן יש את התפקיד roles/iamconnectors.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_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 שמועברת בכותרת הבקשה שגויה, לא תקינה או לא קיימת בפרטי הכניסה של הפרויקט.

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

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

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

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

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

כדי לפתור את השגיאה, צריך להעניק את התפקיד Connector User (roles/iamconnectors.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.

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