Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Melakukan autentikasi menggunakan 2-legged OAuth dengan pengelola autentikasi

Untuk mengizinkan agen Anda melakukan autentikasi ke alat eksternal seperti ServiceNow atau Salesforce menggunakan otoritasnya sendiri, konfigurasikan autentikasi keluar menggunakan penyedia autentikasi 2-legged OAuth (Kredensial Klien) di pengelola autentikasi Agent Identity.

Dengan mengelola kredensial dan token, penyedia autentikasi 2-legged OAuth menghilangkan kebutuhan akan kode kustom untuk menangani alur autentikasi

Alur kerja 2-legged OAuth

Penyedia autentikasi 2-legged OAuth menggunakan identitas agen dan tidak memerlukan izin pengguna. Google mengelola penyimpanan kredensial klien. Saat Anda menggunakan Agent Development Kit (ADK), kredensial tersebut akan otomatis mengambil dan menyisipkan token akses yang dihasilkan ke dalam header pemanggilan alat.

Sebelum memulai

Pastikan Anda telah memilih metode autentikasi yang benar.
Aktifkan Agent Identity API.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.
Mengaktifkan API
Buat dan deploy agen.
Dapatkan client ID dan client secret dari aplikasi pihak ketiga yang ingin Anda hubungkan.
Pastikan Anda memiliki peran yang diperlukan untuk menyelesaikan tugas ini.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat dan menggunakan penyedia autentikasi Agent Identity 2-legged, minta administrator untuk memberi Anda peran IAM berikut di project:

Untuk membuat penyedia autentikasi:
- Agent Identity Admin (roles/agentidentity.admin)
- Agent Identity Editor (roles/agentidentity.editor)
Untuk menggunakan penyedia autentikasi:
- Agent Identity User (roles/agentidentity.user)
- Agent Default Access (roles/aiplatform.agentDefaultAccess)
- Agent Context Editor (roles/aiplatform.agentContextEditor)
- Vertex AI User (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat dan menggunakan penyedia autentikasi Agent Identity 2-legged. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat dan menggunakan penyedia autentikasi Agent Identity 2-legged:

Untuk membuat penyedia autentikasi: agentidentity.authProviders.create
Untuk menggunakan penyedia autentikasi:
- agentidentity.authProviders.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Membuat penyedia autentikasi 2-legged

Buat penyedia autentikasi untuk menentukan konfigurasi dan kredensial untuk aplikasi pihak ketiga.

Untuk membuat penyedia autentikasi 2-legged, gunakan gcloud CLI:

Buat penyedia autentikasi:

gcloud alpha agent-identity authProviders 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"

Pastikan penyedia autentikasi Anda muncul dalam daftar dan statusnya adalah ENABLED:

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

Berikan izin akses untuk mengizinkan agen dan lingkungan pengembangan lokal Anda mengambil kredensial dari penyedia autentikasi. Untuk mengizinkan agen yang di-deploy dan akun pengguna pribadi Anda mengakses penyedia autentikasi, berikan peran Agent Identity User (roles/agentidentity.user) pada resource penyedia autentikasi:

Berikan akses ke SPIFFE ID agen yang di-deploy (Agent Identity):

gcloud alpha agent-identity authProviders 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"

Berikan akses ke akun pengguna pribadi Anda untuk pengembangan dan pengujian lokal (adk web):

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

Ganti kode berikut:

PROJECT_ID: Project ID Anda Google Cloud .
LOCATION: Lokasi tempat penyedia autentikasi dan agen Anda di-deploy (misalnya, us-west1).
AUTH_PROVIDER_NAME: Nama untuk penyedia autentikasi Anda (misalnya, bigquery-mcp-3lo-authprovider).
AUTHORIZATION_URL: URL server otorisasi (misalnya, https://accounts.google.com/o/oauth2/v2/auth).
TOKEN_URL: URL server token (misalnya, https://oauth2.googleapis.com/token).
CLIENT_ID: Client ID OAuth yang Anda buat dari layanan pihak ketiga.
CLIENT_SECRET: Rahasia klien OAuth yang Anda buat dari layanan pihak ketiga.
ORGANIZATION_ID: ID organisasi Anda. Google Cloud
PROJECT_NUMBER: Nomor Google Cloud project Anda.
ENGINE_ID: ID agen mesin penalaran yang di-deploy.
USER_EMAIL: Alamat email akun pengguna pribadi Anda.

Melakukan autentikasi dalam kode agen Anda

Untuk mengautentikasi agen, Anda dapat menggunakan ADK.

ADK

Referensi penyedia autentikasi dalam kode agen Anda menggunakan toolset MCP di 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
# 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 = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

Referensi penyedia autentikasi dalam kode agen Anda menggunakan alat fungsi yang diautentikasi di 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
# 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 = 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

Referensi penyedia autentikasi dalam kode agen Anda menggunakan toolset MCP Agent Registry di 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
# 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"
    )
)

# 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],
)

Menginstal dependensi untuk pengujian lokal

Untuk menguji agen Anda secara lokal di lingkungan virtual, instal dependensi yang diperlukan berikut:

Buat dan aktifkan lingkungan virtual:

python3 -m venv env
source env/bin/activate

Instal paket yang diperlukan:

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

Men-deploy agen

Saat Anda men-deploy agen ke Google Cloud, pastikan Agent Identity diaktifkan.

Jika Anda men-deploy ke Agent Runtime di Gemini Enterprise Agent Platform , gunakan identity_type=AGENT_IDENTITY flag:

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]"],
    },
)