Mengautentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi

Jika Anda ingin agen Anda mengakses alat dan layanan eksternal (misalnya, tugas Jira atau repositori GitHub) atas nama pengguna tertentu, Anda harus mengonfigurasi penyedia autentikasi OAuth bercabang 3 di pengelola autentikasi Identitas Agen.

Penyedia autentikasi OAuth 3-legged mengelola pengalihan pengguna dan token untuk Anda. Hal ini menghilangkan kebutuhan untuk menulis kode kustom guna menangani alur OAuth 2.0 yang kompleks.

Alur kerja 3-legged OAuth

Penyedia autentikasi OAuth 3-legged memerlukan izin pengguna karena agen mengakses resource atas nama pengguna.

Dialog dan pengalihan: Antarmuka chat meminta pengguna untuk login, lalu mengalihkan pengguna ke halaman izin aplikasi pihak ketiga.
Izin dan penyimpanan: Setelah pengguna memberikan izin, token OAuth yang dihasilkan akan disimpan di brankas kredensial yang dikelola Google.
Penyisipan: Saat Anda menggunakan Agent Development Kit (ADK), agen akan otomatis mengambil token dari penyedia autentikasi dan menyisipkannya ke header pemanggilan alat.

Sebelum memulai

[Verifikasi bahwa Anda telah memilih metode autentikasi yang benar](/iam/docs/agent-identity-overview#auth-models).
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
Buat dan deploy agen.
Pastikan Anda memiliki aplikasi frontend untuk menangani perintah login pengguna dan pengalihan ke halaman izin pihak ketiga.
Pastikan Anda memiliki peran yang diperlukan untuk menyelesaikan tugas ini.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat dan menggunakan penyedia autentikasi 3-legged, minta administrator untuk memberi Anda peran IAM berikut pada project:

Untuk membuat penyedia autentikasi:
- IAM Connector Admin (roles/iamconnectors.admin)
- IAM Connector Editor (roles/iamconnectors.editor)
Untuk menggunakan penyedia auth:
- IAM Connector User (roles/iamconnectors.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 3-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 3-legged:

Untuk membuat penyedia autentikasi: iamconnectors.connectors.create
Untuk menggunakan penyedia auth:
- 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 3-legged

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

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

Konsol

Di konsol Google Cloud , buka halaman Agent Registry.
Buka Agent Registry
Klik nama agen yang ingin Anda buatkan penyedia autentikasinya.
Klik Identity.
Di bagian Auth Providers, klik Add auth provider.
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 diawali dengan huruf kecil.
Dari daftar OAuth Type, pilih OAuth (3 legged) .
Klik Create and continue.
Untuk memberikan izin identitas agen Anda menggunakan penyedia autentikasi, klik Berikan akses.
Tindakan ini akan otomatis memberikan peran Pengguna Konektor (roles/iamconnectors.user) kepada identitas agen di resource penyedia autentikasi.
Salin URL callback.
Di tab terpisah, daftarkan URL panggilan balik di aplikasi pihak ketiga Anda.
Dari aplikasi pihak ketiga Anda, dapatkan client ID, rahasia klien, URL token, dan URL otorisasi.
Di bagian Auth provider credentials, masukkan informasi berikut:
- Client ID
- Rahasia Klien
- URL Token
- URL otorisasi
Klik Tambahkan konfigurasi penyedia.

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

Google Cloud CLI

Buat penyedia auth dengan URL otorisasi dan token:

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"

Ambil URI pengalihan dari detail penyedia autentikasi:
```
gcloud alpha agent-identity connectors describe AUTH_PROVIDER_NAME \
    --location="LOCATION"
```
Perintah ini akan menampilkan URI pengalihan di kolom redirectUrl.
Daftarkan URI pengalihan dengan aplikasi pihak ketiga Anda untuk mendapatkan ID klien dan rahasia klien.

Perbarui penyedia autentikasi dengan client ID dan rahasia klien:

gcloud alpha agent-identity connectors update AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET"

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

Identitas Agen didasarkan pada format ID SPIFFE standar industri. Dalam kebijakan izin IAM, identitas agen dirujuk menggunakan ID akun utama.
Level project (gcloud)

Memberikan peran di level project memungkinkan agen menggunakan penyedia autentikasi apa pun dalam project tersebut.
- Untuk memberikan akses agen tunggal ke penyedia autentikasi dalam project, 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 semua agen dalam project ke penyedia autentikasi, 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"
Tingkat konektor (curl)

Untuk memberikan akses satu agen ke penyedia autentikasi tertentu, gunakan setIamPolicy API. Perintah ini akan menimpa kebijakan izin yang ada di 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 Google Cloud Anda.
- AUTH_PROVIDER_NAME: Nama penyedia autentikasi.
- ORGANIZATION_ID: ID Google Cloud organisasi Anda.
- PROJECT_NUMBER: Nomor project Google Cloud Anda.
- LOCATION: Lokasi untuk agen Anda (misalnya, us-central1).
- ENGINE_ID: ID mesin penalaran Anda.

Lakukan autentikasi di kode agen Anda

Untuk mengautentikasi agen, Anda dapat menggunakan ADK atau memanggil Agent Identity API secara langsung.

ADK

Merujuk 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())

# The URI to redirect the user to after consent is granted and the
# callback is received by the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create the Auth Provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# 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

Merujuk 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())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

# 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 kumpulan alat MCP Pendaftaran Agen 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())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Create Google Cloud auth provider by providing auth provider full resource name
auth_scheme=GcpAuthProviderScheme(
name="projects/GOOGLE_PROJECT/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
continue_uri=CONTINUE_URI)

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

toolset = registry.get_mcp_toolset(mcp_server_name="projects/GOOGLE_PROJECT/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],
)

Memanggil API secara langsung

Jika Anda tidak menggunakan ADK, agen Anda harus memanggil API iamconnectorcredentials.retrieveCredentials untuk mendapatkan token.

Karena ini adalah alur OAuth multi-langkah, API akan menampilkan Operasi yang Berjalan Lama (LRO). Agen Anda harus menangani siklus proses operasi:

Permintaan awal: Agen memanggil retrieveCredentials.
Izin diperlukan: Jika pengguna belum memberikan izin, API akan menampilkan LRO dengan metadata yang berisi auth_uri dan consent_nonce.
Pengalihan frontend: Aplikasi Anda harus mengalihkan pengguna ke auth_uri.
Penyelesaian: Setelah pengguna memberikan izin, panggil FinalizeCredential menggunakan consent_nonce untuk menyelesaikan alur dan mendapatkan token.

Memperbarui aplikasi sisi klien

Untuk menangani login dan pengalihan pengguna untuk OAuth 3-legged, aplikasi sisi klien Anda harus menerapkan langkah-langkah berikut untuk mengelola izin pengguna dan melanjutkan percakapan:

Menangani pemicu otorisasi
Menerapkan endpoint validasi pengguna
Melanjutkan percakapan dengan agen

Untuk contoh implementasi lengkap, lihat contoh frontend ValidateUserId.

Menangani pemicu otorisasi

Saat memerlukan izin pengguna, agen akan menampilkan panggilan fungsi adk_request_credential. Aplikasi Anda harus mencegat panggilan ini untuk memulai dialog atau pengalihan otorisasi pengguna.

Kelola konteks sesi dengan merekam consent_nonce yang disediakan oleh penyedia autentikasi. Nonce ini diperlukan untuk memverifikasi pengguna selama langkah validasi. Simpan auth_config dan auth_request_function_call_id dalam sesi untuk memfasilitasi kelanjutan alur setelah izin diberikan.

if (auth_request_function_call := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(auth_request_function_call)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, auth_provider_name, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = auth_request_function_call.get('id') if isinstance(auth_request_function_call, dict) else getattr(auth_request_function_call, 'id', None)
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    if auth_config.exchanged_auth_credential and auth_config.exchanged_auth_credential.oauth2:
        oauth2 = auth_config.exchanged_auth_credential.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Menerapkan endpoint validasi pengguna

Terapkan endpoint validasi di server web Anda (URI yang sama yang diberikan sebagai continue_uri selama konfigurasi). Endpoint ini harus melakukan hal berikut:

Menerima user_id_validation_state dan auth_provider_name sebagai parameter kueri.
Ambil user_id dan consent_nonce dari konteks sesi.
Panggil API FinalizeCredentials penyedia autentikasi dengan parameter ini.
Tutup jendela otorisasi setelah menerima respons keberhasilan.

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
  auth_provider_name = request.query_params.get("auth_provider_name")
  session_id = request.cookies.get("session_id")
  session = consent_sessions.get(session_id, {})

  payload = {
      "userId": session.get("user_id"),
      "userIdValidationState": request.query_params.get(
          "user_id_validation_state"
      ),
      "consentNonce": session.get("consent_nonce"),
  }

  finalize_url = f"https://iamconnectorcredentials.googleapis.com/v1alpha/{auth_provider_name}/credentials:finalize"

  try:
    async with httpx.AsyncClient(timeout=30.0) as client:
      resp = await client.post(finalize_url, json=payload)
      resp.raise_for_status()
  except httpx.HTTPError as e:
    err_text = e.response.text if hasattr(e, "response") else str(e)
    status = e.response.status_code if hasattr(e, "response") else 500
    return HTMLResponse(err_text, status_code=status)

  return HTMLResponse("""
      <script>
          window.close();
      </script>
      <p>Success. You can close this window.</p>
  """)

Melanjutkan percakapan agen

Setelah pengguna memberikan izin dan jendela otorisasi ditutup, ambil auth_config dan auth_request_function_call_id dari data sesi Anda. Untuk melanjutkan percakapan, sertakan detail ini dalam permintaan baru kepada agen sebagai function_response.

if request.is_auth_resume and session.auth_request_function_call_id and session.auth_config:
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

Men-deploy agen

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

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