אימות באמצעות OAuth דו-רגלי עם מנהל הרשאות

כדי לאפשר לסוכנים לבצע אימות בכלים חיצוניים כמו ServiceNow או Salesforce באמצעות הסמכות שלהם, צריך להגדיר אימות יוצא באמצעות ספקי אימות OAuth דו-רגלי (פרטי כניסה של לקוח) במנהל האימות של Agent Identity.

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

תהליך עבודה של OAuth דו-רגלי (‎2-legged OAuth)

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

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

  1. מוודאים שבחרתם בשיטת האימות הנכונה.

  2. מפעילים את Agent Identity API, אם הוא עדיין לא מופעל.

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    להפעלת ה-API

  3. יוצרים ופורסים נציג.

  4. משיגים את מזהה הלקוח ואת סוד הלקוח מהאפליקציה של הצד השלישי שאליה רוצים להתחבר.

  5. מוודאים שיש לכם את התפקידים הנדרשים כדי להשלים את המשימה.

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

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

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

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

ההרשאות הנדרשות

כדי ליצור ספק אימות של Agent Identity עם 2 רגליים ולהשתמש בו, נדרשות ההרשאות הבאות:

  • כדי ליצור ספקי אימות: agentidentity.authProviders.create
  • כדי להשתמש בספקי אימות:
    • agentidentity.authProviders.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

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

יצירת ספק אימות דו-שלבי

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

כדי ליצור ספק אימות דו-שלבי, צריך להשתמש במסוף Google Cloud , ב-Google Cloud CLI או ב-API בארכיטקטורת REST.

המסוף

  1. נכנסים לדף Agent Registry במסוף Google Cloud .

    כניסה ל-Agent Registry

  2. לוחצים על שם הנציג שרוצים ליצור לו ספק אימות.
  3. לוחצים על זהות.
  4. בקטע Auth Providers, לוחצים על Add auth provider.

  5. בחלונית Add auth provider, מזינים שם ותיאור.

    השם יכול לכלול רק אותיות קטנות, מספרים או מקפים, הוא לא יכול להסתיים במקף והוא חייב להתחיל באות קטנה.

  6. ברשימה OAuth Type, בוחרים באפשרות OAuth (2 legged).
  7. לוחצים על Create and continue.
  8. כדי לתת לזהות של הסוכן הרשאה להשתמש בספק האימות, לוחצים על מתן גישה.

    בתהליך הזה, התפקיד משתמש ב-Agent Identity (roles/agentidentity.user) מוקצה באופן אוטומטי לזהות הסוכן במשאב של ספק האימות.

  9. בקטע Auth provider credentials, מזינים את הפרטים הבאים:
    • מזהה לקוח
    • סוד לקוח
    • כתובת URL לטוקן
  10. לוחצים על Add provider config.

ספק האימות החדש שנוצר מופיע ברשימה Auth Providers.

‫CLI של gcloud

  1. יוצרים את ספק האימות:

    gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --two-legged-oauth-client-id="CLIENT_ID" \
    --two-legged-oauth-client-secret="CLIENT_SECRET" \
    --two-legged-oauth-token-url="TOKEN_URL"
  2. מוודאים שספק האימות מופיע ברשימה והסטטוס שלו הוא ENABLED: 
    gcloud agent-identity auth-providers list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  3. נותנים הרשאות גישה כדי לאפשר לסוכן ולסביבת הפיתוח המקומית לאחזר את פרטי הכניסה מספק האימות. כדי לאפשר לנציג שנפרס ולחשבון המשתמש האישי שלכם לגשת לספק האימות, מקצים את התפקיד משתמש ב-Agent Identity (roles/agentidentity.user) במשאב של ספק האימות:

    1. נותנים גישה למזהה ה-SPIFFE של הסוכן שנפרס (Agent Identity):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

    2. מתן גישה לחשבון המשתמש האישי שלכם לצורך פיתוח ובדיקה מקומיים (adk web):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="user:USER_EMAIL"

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: המיקום שבו נפרסו ספק האימות והנציג (לדוגמה, us-west1).
  • ‫AUTH_PROVIDER_NAME: השם של ספק האימות (לדוגמה, jira-mcp-2lo-authprovider).
  • CLIENT_ID: מזהה הלקוח ב-OAuth שיצרתם בשירות של הצד השלישי.
  • CLIENT_SECRET: סוד הלקוח של OAuth שיצרתם בשירות של הצד השלישי.
  • ‫TOKEN_URL: כתובת ה-URL של שרת האסימונים (לדוגמה, https://oauth2.googleapis.com/token).
  • ‫ORGANIZATION_ID: מזהה הארגון ב- Google Cloud .
  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
  • ‫ENGINE_ID: המזהה של סוכן מנוע החשיבה הרציונלית שנפרס.
  • ‫USER_EMAIL: כתובת האימייל של חשבון המשתמש האישי שלכם.

REST

  1. יוצרים את ספק האימות:

    ה-method authProviders.create של Agent Identity API יוצרת ספק אימות OAuth עם 2 רגליים בפרויקט ובמיקום.

    לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud . מזהי פרויקטים הם מחרוזות אלפאנומריות, כמו my-project.
    • ‫LOCATION: המיקום שבו נפרסו ספק האימות והנציג (לדוגמה, us-west1).
    • ‫AUTH_PROVIDER_NAME: השם של ספק האימות (לדוגמה, jira-mcp-2lo-authprovider). השם יכול להכיל רק אותיות קטנות, מספרים או מקפים, הוא לא יכול להסתיים במקף וחייב להתחיל באות קטנה.
    • ‫CLIENT_ID: מזהה הלקוח ב-OAuth שיצרתם בשירות של הצד השלישי.
    • ‫CLIENT_SECRET: סוד הלקוח של OAuth שיצרתם בשירות של הצד השלישי.
    • ‫TOKEN_URL: כתובת ה-URL של שרת האסימונים (לדוגמה, https://oauth2.googleapis.com/token).

    ה-method של ה-HTTP וכתובת ה-URL: 

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

    תוכן בקשת JSON: 

    {
  "authProviderTypeParams": {
    "twoLeggedOauth": {
      "clientId": "CLIENT_ID",
      "clientSecret": "CLIENT_SECRET",
      "tokenUrl": "TOKEN_URL"
    }
  }
}

    כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

    אתם אמורים לקבל תגובת JSON שדומה לזו:

    {
  "name": "projects/my-project/locations/us-west1/authProviders/jira-mcp-2lo-authprovider",
  "createTime": "2026-04-03T21:15:41.367155Z",
  "updateTime": "2026-04-03T21:15:41.367155Z",
  "authProviderTypeParams": {
    "twoLeggedOauth": {
      "clientId": "my-oauth-client-id",
      "tokenUrl": "https://oauth2.googleapis.com/token"
    }
  },
  "state": "ENABLED"
}

  2. כדי לאפשר לנציג שפרסתם ולחשבון המשתמש האישי שלכם לאחזר פרטי כניסה מספק האימות, אתם צריכים להקצות את התפקיד משתמש ב-Agent Identity (roles/agentidentity.user) במשאב של ספק האימות:

    ה-method authProviders.setIamPolicy של Agent Identity API מגדירה את מדיניות ההרשאות במשאב של ספק האימות.

    לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud . מזהי פרויקטים הם מחרוזות אלפאנומריות, כמו my-project.
    • ‫LOCATION: המיקום שבו נפרסו ספק האימות והנציג (לדוגמה, us-west1).
    • ‫AUTH_PROVIDER_NAME: השם של ספק האימות.
    • ‫ORGANIZATION_ID: מזהה הארגון ב- Google Cloud.
    • ‫PROJECT_NUMBER: המספר של הפרויקט ב- Google Cloud שבו הנציג פרוס (לדוגמה, 987654321098).
    • ‫ENGINE_ID: המזהה של סוכן מנוע חשיבה רציונלית שנפרס.
    • ‫USER_EMAIL: כתובת האימייל של חשבון המשתמש האישי שלכם.

    ה-method של ה-HTTP וכתובת ה-URL: 

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

    תוכן בקשת JSON: 

    {
  "policy": {
    "bindings": [
      {
        "role": "roles/agentidentity.user",
        "members": [
          "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
          "user:USER_EMAIL"
        ]
      }
    ]
  }
}

    כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

    אתם אמורים לקבל תגובת JSON שדומה לזו:

    {
  "version": 1,
  "etag": "BwYKmjvelug=",
  "bindings": [
    {
      "role": "roles/agentidentity.user",
      "members": [
        "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
        "user:alex@example.com"
      ]
    }
  ]
}

אימות בקוד של הנציג

כדי לאמת את הנציג, אתם יכולים להשתמש ב-ADK.

ADK

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

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register the Google Cloud Auth Provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create the Google Cloud Auth Provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

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

import httpx
from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name=(
            "projects/PROJECT_ID/locations/"
            "LOCATION/authProviders/"
            "AUTH_PROVIDER_NAME"
        )
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

מפנים לספק האימות בקוד של הסוכן באמצעות ערכת הכלים של Agent Registry MCP ב-ADK.

אתם לא צריכים ליצור סכימת אימות לתהליך הזה. הקישור היוצא של שרת ה-MCP כבר מתעד באיזה ספק אימות להשתמש.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
)

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

התקנת יחסי תלות לבדיקה מקומית

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

  1. יוצרים ומפעילים סביבה וירטואלית: 
    python3 -m venv env
source env/bin/activate
  2. מתקינים את החבילות הנדרשות: 
    pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

פריסת הנציג

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

Agent CLI

אם אתם משתמשים בערכה לפיתוח סוכנים (ADK) וב-Agent CLI, כדי לפרוס את הסוכן עם Agent Identity:

  1. בתיקיית האפליקציה של הנציג, יוצרים קובץ תצורה בשם .agent_engine_config.json כדי להפעיל את Agent Identity:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  2. פורסים את הסוכן ב-Agent Runtime ב-Gemini Enterprise Agent Platform:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

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

    • ‫AGENT_NAME: השם של תיקיית האפליקציה של הנציג (לדוגמה, maps_agent).
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud.
    • ‫LOCATION: האזור הנתמך שבו רוצים לפרוס את הנציג (לדוגמה, us-west1).

Python SDK

אם אתם פורסים באופן פרוגרמטי באמצעות Vertex AI Python SDK, השתמשו בדגל identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# 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")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(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]",
            "google-adk[agent-identity,mcp]>=2.7.1",
        ],
    },
)

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור הנתמך שבו רוצים לפרוס את הנציג (לדוגמה, us-west1).

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