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

Mengautentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi

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

Penyedia autentikasi 3-legged OAuth mengelola pengalihan dan token pengguna 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 3-legged OAuth memerlukan izin pengguna karena agen mengakses resource atas nama pengguna.

Pesan 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 vault 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

[Pastikan 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 diperlukan untuk membuat dan menggunakan penyedia autentikasi 3-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 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 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 3-legged

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

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

Konsol

Di Google Cloud konsol, buka halaman Agent Registry.
Buka Agent Registry
Klik nama agen yang ingin Anda buatkan penyedia autentikasi.
Klik Identity.
Di bagian Auth Providers, klik Add auth provider.
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 diawali dengan huruf kecil.
Dari daftar OAuth Type, pilih OAuth (3 legged) .
Klik Create and continue.
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 di resource penyedia autentikasi.
Salin URL callback.
Di tab terpisah, daftarkan URL callback 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 Add provider config.

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

Google Cloud CLI

Buat penyedia autentikasi 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 akan menampilkan URI pengalihan di kolom redirectUrl.
Daftarkan URI pengalihan dengan aplikasi pihak ketiga Anda untuk mendapatkan client ID 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 untuk menggunakan penyedia autentikasi, perbarui kebijakan IAM izinkan 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 IAM izinkan, 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 izinkan 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 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.

Mengautentikasi dalam kode agen Anda

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

ADK

Referensi penyedia autentikasi dalam kode agen Anda menggunakan alat 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

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

# 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 alat 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())

# 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 iamconnectorcredentials.retrieveCredentials API 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 yang metadatanya 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 3-legged OAuth, 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 agen

Untuk contoh implementasi lengkap, lihat contoh frontend ValidateUserId.

Menangani pemicu otorisasi

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

Kelola konteks sesi dengan mencatat consent_nonce yang diberikan 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.
Mengambil user_id dan consent_nonce dari konteks sesi.
Memanggil FinalizeCredentials API penyedia autentikasi dengan parameter ini.
Menutup 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 ke 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 Anda men-deploy agen 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]"],
    },
)