Melakukan autentikasi menggunakan 2-legged OAuth dengan pengelola autentikasi

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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 Identitas Agen.

Penyedia autentikasi 2-legged OAuth mengelola kredensial dan token untuk Anda. Hal ini menghilangkan kebutuhan untuk menulis kode kustom guna 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 klien akan otomatis mengambil dan menyisipkan token akses yang dihasilkan ke dalam header pemanggilan alat.

Sebelum memulai

1. Pastikan Anda telah memilih metode autentikasi yang benar.

2. Aktifkan Agent Identity Connector API.

   Peran yang diperlukan untuk mengaktifkan API

   Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

   Mengaktifkan API

3. Buat dan deploy agen.

4. Dapatkan client ID dan client secret dari aplikasi pihak ketiga yang ingin Anda hubungkan.

5. Pastikan Anda memiliki peran yang diperlukan untuk menyelesaikan tugas ini.

Peran yang diperlukan

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

• Untuk membuat penyedia autentikasi:
  • Admin Konektor IAM (roles/iamconnectors.admin)
  • Editor Konektor IAM (roles/iamconnectors.editor)
• Untuk menggunakan penyedia autentikasi:
  • Pengguna Konektor IAM (roles/iamconnectors.user)
  • Akses Default Agen (roles/aiplatform.agentDefaultAccess)
  • Editor Konteks Agen (roles/aiplatform.agentContextEditor)
  • Pengguna Vertex AI (roles/aiplatform.user)
  • Pelanggan Service Usage (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 Identitas Agen 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 Identitas Agen 2-legged:

• Untuk membuat penyedia autentikasi: iamconnectors.connectors.create
• Untuk menggunakan penyedia autentikasi:
  • iamconnectors.connectors.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 Google Cloud konsol atau Google Cloud CLI.

Konsol

1. Di Google Cloud konsol, buka halaman Agent Registry.

   Buka Agent Registry

2. Klik nama agen yang ingin Anda buatkan penyedia autentikasi.
3. Klik Identity.
4. Di bagian Auth Providers, klik Add auth provider.

5. Di panel Add auth provider, masukkan nama dan deskripsi.

   Nama hanya boleh berisi huruf kecil, angka, atau tanda hubung, tidak boleh diakhiri dengan tanda hubung, dan harus dimulai dengan huruf kecil.

6. Dari daftar OAuth Type, pilih OAuth (2 legged) .
7. Klik Create and continue.
8. Untuk memberikan izin identitas agen Anda untuk menggunakan penyedia autentikasi, klik Grant access.

   Tindakan ini akan otomatis menetapkan peran Connector User (roles/iamconnectors.user) ke identitas agen pada resource penyedia autentikasi.

9. Di bagian Auth provider credentials, masukkan informasi berikut:
   • Client ID
   • Client Secret
   • Token URL
10. Klik Add provider config.

Penyedia autentikasi yang baru dibuat akan muncul dalam daftar Auth Providers.

Google Cloud CLI

1. Buat penyedia autentikasi:

   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"

2. Untuk memberikan izin identitas agen Anda untuk menggunakan penyedia autentikasi, perbarui kebijakan izin IAM untuk project atau penyedia autentikasi tertentu, dan berikan peran Connector User (roles/iamconnectors.user) ke akun utama agen.

   Identitas Agen didasarkan pada format ID SPIFFE standar industri. Dalam kebijakan izin IAM, identitas agen dirujuk menggunakan pengenal akun utama.

   Level project (gcloud)

   Memberikan peran di level project memungkinkan agen menggunakan penyedia autentikasi apa pun di project tersebut.

   • Untuk memberikan akses ke penyedia autentikasi di project kepada satu agen, jalankan perintah berikut:

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

   • Untuk memberikan akses ke penyedia autentikasi kepada semua agen di project, jalankan perintah berikut:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --role='roles/iamconnectors.user' \
         --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"

   Level konektor (curl)

   Untuk memberikan akses ke penyedia autentikasi tertentu kepada satu agen, gunakan setIamPolicy API. Perintah ini akan menimpa kebijakan izin yang ada pada resource.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json" \
       -d '{
     "policy": {
       "bindings": [
         {
           "role": "roles/iamconnectors.user",
           "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
         }
       ]
     }
   }' \
       "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"

   Ganti kode berikut:

   • PROJECT_ID: Project ID Anda Google Cloud .
   • AUTH_PROVIDER_NAME: Nama penyedia autentikasi.
   • ORGANIZATION_ID: ID organisasi Anda. Google Cloud
   • PROJECT_NUMBER: Nomor Google Cloud project Anda.
   • LOCATION: Lokasi untuk agen Anda (misalnya, us-central1).
   • ENGINE_ID: ID mesin penalaran Anda.

Melakukan autentikasi dalam kode agen Anda

Untuk mengautentikasi agen Anda, 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 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="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_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
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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="YOUR_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 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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

  

Menginstal dependensi untuk pengujian lokal

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

1. Buat dan aktifkan lingkungan virtual:

   python3 -m venv env
   source env/bin/activate

2. Instal paket yang diperlukan:

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

Men-deploy agen

Saat Anda men-deploy agen Anda ke Google Cloud, pastikan Identitas Agen di aktifkan.

Jika Anda men-deploy ke Runtime Agen, gunakan flag 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]"],
    },
)

Langkah berikutnya

• Ringkasan Identitas Agen
• Melakukan autentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi
• Melakukan autentikasi menggunakan kunci API dengan pengelola autentikasi
• Mengelola penyedia autentikasi Identitas Agen
• Memecahkan masalah pengelola autentikasi Identitas Agen