‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

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

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

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

כדי ליצור ספקי אימות:
- אדמין של מחבר IAM (roles/iamconnectors.admin)
- עריכת מחברים ב-IAM ‏(roles/iamconnectors.editor)
כדי להשתמש בספקי אימות:
- משתמש במחבר IAM ‏(roles/iamconnectors.user)
- גישת ברירת המחדל של הסוכן (roles/aiplatform.agentDefaultAccess)
- עורך ההקשר של הסוכן (roles/aiplatform.agentContextEditor)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

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

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

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

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

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

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

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

כדי ליצור ספק אימות דו-שלבי, משתמשים במסוף Google Cloud או ב-Google Cloud CLI.

המסוף

נכנסים לדף Agent Registry במסוף Google Cloud .
כניסה ל-Agent Registry
לוחצים על שם הנציג שרוצים ליצור לו ספק אימות.
לוחצים על זהות.
בקטע Auth Providers, לוחצים על Add auth provider.
בחלונית Add auth provider, מזינים שם ותיאור.

השם יכול לכלול רק אותיות קטנות, מספרים או מקפים, הוא לא יכול להסתיים במקף והוא חייב להתחיל באות קטנה.
ברשימה OAuth Type, בוחרים באפשרות OAuth (2 legged).
לוחצים על Create and continue.
כדי לתת לזהות של הסוכן הרשאה להשתמש בספק האימות, לוחצים על מתן גישה.
הפעולה הזו מקצה באופן אוטומטי את התפקיד Connector User (roles/iamconnectors.user) לזהות הסוכן במשאב של ספק האימות.
בקטע Auth provider credentials, מזינים את הפרטים הבאים:
- מזהה לקוח
- סוד לקוח
- כתובת URL לטוקן
לוחצים על Add provider config.

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

‫CLI של gcloud

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

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --two-legged-oauth-client-id="CLIENT_ID" \
    --two-legged-oauth-client-secret="CLIENT_SECRET" \
    --two-legged-oauth-token-endpoint="TOKEN_ENDPOINT"

מוודאים שספק האימות מופיע ברשימה והסטטוס שלו הוא ENABLED:

gcloud alpha agent-identity connectors list \
   --project="PROJECT_ID" \
   --location="LOCATION"

נותנים הרשאות גישה כדי לאפשר לסוכן ולסביבת הפיתוח המקומית לאחזר את פרטי הכניסה מספק האימות. כדי לאפשר לנציג שנפרס ולחשבון המשתמש האישי שלכם לגשת לספק האימות, מקצים את התפקיד Connector User ‏(roles/iamconnectors.user) במשאב של ספק האימות:

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

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

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

gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.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_ENDPOINT: כתובת ה-URL של נקודת הקצה של הטוקן (לדוגמה, https://oauth2.googleapis.com/token).
‫ORGANIZATION_ID: מזהה הארגון ב- Google Cloud .
‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫ENGINE_ID: המזהה של סוכן מנוע החשיבה הרציונלית שנפרס.
‫USER_EMAIL: כתובת האימייל של חשבון המשתמש האישי שלכם.

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

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

ADK

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

from google.adk.agents.llm_agent import LlmAgent
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 using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

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

import httpx
from google.adk.agents.llm_agent import LlmAgent
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
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name=(
            "projects/PROJECT_ID/locations/"
            "LOCATION/connectors/"
            "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 = LlmAgent(
    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.

  from google.adk.agents.llm_agent import LlmAgent
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.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
from google.adk.integrations.agent_registry import AgentRegistry

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

# Create Google Cloud auth provider scheme by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/connectors/"
        "AUTH_PROVIDER_NAME"
    )
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "global/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    auth_scheme=auth_scheme,
)

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

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

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

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

יוצרים ומפעילים סביבה וירטואלית:
```
python3 -m venv env
source env/bin/activate
```

מתקינים את החבילות הנדרשות:

pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

פריסת הנציג

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

אם אתם פורסים ב-Agent Runtime ב-Gemini Enterprise Agent Platform, השתמשו בדגל identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

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

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(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]"],
    },
)