Melakukan autentikasi menggunakan 2-legged OAuth dengan pengelola autentikasi

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

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

Penting: Dokumen ini menunjukkan cara melakukan autentikasi menggunakan Agent Identity API. Sebaiknya gunakan Agent Identity API karena IAM Connectors API (Pratinjau) tidak akan tersedia secara umum. Jika Anda menggunakan IAM Connectors API, bermigrasi ke Agent Identity API.

Alur kerja 2-legged OAuth

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

Sebelum memulai

1. Verifikasi bahwa Anda telah memilih metode autentikasi yang benar.

2. 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 Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

   Mengaktifkan API

3. Buat dan deploy agen.

4. Dapatkan client ID dan rahasia klien 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 Anda perlukan guna membuat dan menggunakan penyedia autentikasi Identitas Agen 2-legged, minta administrator untuk memberi Anda peran IAM berikut pada project:

• Untuk membuat penyedia autentikasi:
  • Agent Identity Admin (roles/agentidentity.admin)
  • Agent Identity Editor (roles/agentidentity.editor)
• Untuk menggunakan penyedia auth:
  • Pengguna Identitas Agen (roles/agentidentity.user)
  • Akses Default Agen (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 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: agentidentity.authProviders.create
• Untuk menggunakan penyedia auth:
  • 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 aplikasi pihak ketiga.

Untuk membuat penyedia autentikasi 2-legged, gunakan konsol Google Cloud atau Google Cloud CLI.

Konsol

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

   Buka Agent Registry

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

5. Di panel Tambahkan penyedia autentikasi, 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 menggunakan penyedia autentikasi, klik Berikan akses.

   Proses ini secara otomatis menetapkan peran Pengguna Identitas Agen (roles/agentidentity.user) ke identitas agen di sumber daya penyedia autentikasi.

9. Di bagian Auth provider credentials, masukkan informasi berikut:
   • Client ID
   • Rahasia Klien
   • URL Token
10. Klik Tambahkan konfigurasi penyedia.

Penyedia autentikasi yang baru dibuat akan muncul dalam daftar Penyedia Autentikasi.

gcloud CLI

1. Buat penyedia autentikasi:

   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. Pastikan penyedia autentikasi Anda muncul dalam daftar dan statusnya adalah ENABLED:

   gcloud agent-identity auth-providers list \
      --project="PROJECT_ID" \
      --location="LOCATION"

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

   1. Memberikan akses ke ID SPIFFE agen yang di-deploy (Identitas Agen):

      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. Memberikan akses ke akun pengguna pribadi Anda untuk pengembangan dan pengujian lokal (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"

Ganti kode berikut:

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

Lakukan autentikasi di kode agen Anda

Untuk mengautentikasi agen, Anda dapat menggunakan ADK.

Catatan: Contoh berikut mendaftarkan penyedia autentikasi di tingkat modul, yang berfungsi saat Anda menjalankan agen secara lokal atau men-deploy-nya dengan Agent CLI. Jika Anda men-deploy dengan Vertex AI Python SDK, daftarkan penyedia autentikasi di set_up(), bukan agar berjalan di container yang di-deploy. Untuk mengetahui informasi selengkapnya, lihat Men-deploy agen.

ADK

Referensi penyedia autentikasi dalam kode agen Anda dengan menggunakan toolset MCP di 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

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

Referensi penyedia autentikasi dalam kode agen Anda menggunakan kumpulan alat MCP Agent Registry di ADK.

Anda tidak membuat skema autentikasi untuk alur ini. Binding keluar server MCP sudah mencatat penyedia autentikasi yang akan digunakan.

Perhatian: Gunakan region yang sama untuk penyedia otorisasi, server MCP, dan klien Agent Registry. Penyedia autentikasi tidak tersedia di lokasi global, jadi jika Anda menetapkan location="global", pembuatan binding keluar akan gagal dengan error Location of auth provider does not match location of binding.

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

  

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 ke Google Cloud, pastikan Identitas Agen diaktifkan.

Agent CLI

Jika Anda menggunakan Agent Development Kit (ADK) dan Agent CLI, lakukan hal berikut untuk men-deploy agen dengan Identitas Agen diaktifkan:

1. Di folder aplikasi agen, buat file konfigurasi bernama .agent_engine_config.json untuk mengaktifkan Identitas Agen:

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

2. Men-deploy agen Anda ke Agent Runtime di Gemini Enterprise Agent Platform :

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

   Ganti kode berikut:

   • AGENT_NAME: Nama folder aplikasi agen Anda (misalnya, maps_agent).
   • PROJECT_ID: Project ID Google Cloud Anda.
   • LOCATION: Wilayah yang didukung tempat Anda ingin men-deploy agen (misalnya, us-west1).

Python SDK

Jika Anda men-deploy secara terprogram menggunakan Vertex AI Python SDK, gunakan tanda identity_type=AGENT_IDENTITY:

Perhatian: SDK akan melakukan serialisasi objek aplikasi Anda, sehingga panggilan CredentialManager.register_auth_provider() yang dijalankan skrip lokal Anda pada waktu impor tidak akan berjalan di penampung yang di-deploy. Sebagai gantinya, daftarkan penyedia autentikasi dalam metode set_up() aplikasi Anda, yang dipanggil runtime saat penampung dimulai. Jika tidak, agen akan gagal pada waktu kueri dengan No auth provider registered for custom auth scheme 'gcpAuthProviderScheme'. Untuk mengetahui informasi selengkapnya, lihat Pertimbangan deployment.

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

Ganti kode berikut:

• PROJECT_ID: Project ID Google Cloud Anda.
• LOCATION: Wilayah yang didukung tempat Anda ingin men-deploy agen (misalnya, us-west1).

Langkah berikutnya

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