Temsilci Kimliği ve Yetkilendirme Yöneticisi ile kullanıcı adına hareket eden bir yapay zeka ajanı oluşturma

1. Giriş

Geniş kapsamlı izne sahip kendi kimlik bilgileri olan bir temsilci herkesin verilerini görür. Bu codelab'de, oturum açmış kullanıcının kendi kimlik bilgileriyle üçüncü taraf API'sini çağıran bir temsilci oluşturacaksınız. Böylece temsilci, yalnızca kullanıcının görebileceği bilgileri görür.

Bu asistanı Google Agent Development Kit (ADK) ve Gemini Enterprise ile oluşturacaksınız.

Özellikle, aşağıdaki özelliklere sahip bir çift kimlik mimarisini nasıl tasarlayacağınızı öğreneceksiniz:

  1. Temsilci kendi adına hareket eder (Temsilci Kimliği): Temsilci, SPIFFE destekli bir Temsilci Kimliği kullanarak Auth Manager'ı çağırır, telemetriyi depolar ve Google Cloud API'lerini çağırır.
  2. Temsilci, kullanıcı adına işlem yapar (Kullanıcı Tarafından Yetkilendirilmiş Kimlik): GitHub gibi harici kaynaklara erişmek için temsilci, kullanıcının kimlik bilgilerini kullanarak araçları güvenli bir şekilde sorgulamak üzere 3 taraflı OAuth (3LO) izin akışını tetikler.

İkili Kimlik Mimarisi

Bunu yapmak için şunları öğreneceksiniz:

  1. GitHub'ın Model Context Protocol (MCP) sunucusuna bağlanan bir ADK temsilcisi oluşturun.
  2. Temsilcinin aracını statik bir GitHub PAT'den (kişisel erişim jetonu) Google Cloud Auth Manager'ı kullanarak 3 aşamalı OAuth (3LO) akışına güncelleyin.
  3. Temsilciyi Agent Runtime'a güvenli bir şekilde dağıtın ve Agent Identity'yi temel hazırlayın.
  4. Temsilcinin kimliğinin kullanıcı adına jeton kasasına erişebilmesi için IAM rollerini yapılandırın.
  5. Google Cloud'da Auth Manager için uçtan uca 3LO akışını anlama

Ön koşullar

Başlamadan önce aşağıdakileri hazır bulundurun:

  • Faturalandırmanın etkin olduğu bir Google Cloud projesi.
  • Yerel makinenizde projeniz için yüklenmiş ve kimliği doğrulanmış Google Cloud SDK (gcloud CLI). 586.0.0 veya daha yeni bir sürüm gereklidir: gcloud components update komutunu çalıştırın.
  • Yerel olarak yüklenmiş Python 3.10 ila 3.13.
  • uv paket yöneticisi yüklü (pip install uv).
  • OAuth uygulaması kaydetmek ve jeton oluşturmak için GitHub hesabı. GitHub hesabınız yoksa üç aşamalı OAuth 2.0'ı destekleyen herhangi bir üçüncü taraf MCP sunucusunu kullanabilirsiniz.

2. Proje Ayarları

1. Google Cloud'da kimlik doğrulama

Bu laboratuvarda ortamınızın Agent Runtime'a dağıtım yapmak, Agent Identity'yi temel hazırlamak ve Auth Manager'ı yapılandırmak için gerekli izinlere sahip olduğundan emin olmak üzere yerel komut satırınızdan Google Cloud'da kimlik doğrulaması yapın.

Google Cloud hesabınızda oturum açmak, etkin projenizi ayarlamak (YOUR_PROJECT_ID yerine Google Cloud proje kimliğinizi yazın) ve Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) yapılandırmak için aşağıdaki komutları çalıştırın:

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login

2. Gerekli Google Cloud hizmetlerini etkinleştirme

Bu laboratuvarı çalıştırmak için Google Cloud projenizde gerekli API'leri etkinleştirin. Terminalinizde aşağıdaki komutu çalıştırın:

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

Bu komutun yürütülmesi bir dakika sürebilir. İşlem tamamlandığında, API'lerin etkin olduğunu onaylayan komut istemine geri döner.

3. Agents KSA'yı yükleme ve projeyi ayarlama

agents-cli, ADK temsilcilerini Gemini Enterprise'da yapılandırmak, yönetmek, test etmek ve dağıtmak için kullanılan komut satırı aracıdır. Yerel olarak yükleyin:

uvx google-agents-cli setup

Yüklemenizi doğrulayın:

agents-cli --help

CLI'nın yardım menüsünde kullanılabilir komutlar (ör. deploy, run ve status) gösterilir.

İlk proje iskeletini oluşturun. Yerel bir prototiple başlayıp daha sonra Agent Runtime dağıtımı için bu prototipi geliştireceksiniz:

agents-cli create secure-agent-demo --prototype --yes

Bu komut, temel temsilci kodunuzu, bağımlılıklarınızı ve test dosyalarınızı içeren secure-agent-demo dizinini oluşturur.

4. Gerekli ADK ekstralarını ekleme

Oluşturulan pyproject.toml dosyasına eksik olan iki ek bilgiyi ekleyin: GitHub araç seti için mcp ve laboratuvarın ilerleyen bölümlerinde kullanılacak Auth Manager için agent-identity. secure-agent-demo/pyproject.toml dosyasını açın ve tümünü değiştirin

google-adk

Şu öğeleri içeren bağımlılık satırı:

"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",

Ardından şunları yükleyin:

cd secure-agent-demo
agents-cli install

3. Temsilciyi oluşturma ve test etme

1. Temsilciyi oluşturma

Projenizde, secure-agent-demo/app/agent.py dosyasındaki kodu şununla değiştirin:

# app/agent.py

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from app.tools import github_toolset

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.

Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=INSTRUCTION,
    tools=[github_toolset()],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Bu dosya, temsilcinin üç temel bileşenini tanımlar:

  • Sistem Talimatı (INSTRUCTION): Karakteri ayarlar, asistanın kapsamını GitHub triyajı olarak belirler ve katı güvenlik kuralları uygular (salt okuma erişimi ve hata oluşursa kullanıcıları kimlik doğrulamaya yönlendirme gibi).
  • Temsilci Yapılandırması (root_agent): gemini-3.8-flash modelini kullanarak bir ADK Agent örneği oluşturur, HTTP yeniden deneme mantığını yapılandırır ve temsilciyi GitHub araç setiyle donatır.
  • Uygulama sarmalayıcı (app): Kök temsilciyi bir ADK App kapsayıcısına sarmalayarak Agent Runtime'a dağıtılabilir hale getirir.

2. GitHub MCP aracını ekleme

Temsilci, Model Context Protocol (MCP) kullanarak GitHub'a bağlanır. MCP ağ geçidi bağlantı parametrelerini kaydetmek için secure-agent-demo/app/tools.py konumunda yeni bir dosya oluşturun. Aşağıdaki kodu kopyalayıp yapıştırın:

# app/tools.py

from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")

def github_toolset() -> McpToolset:
    """Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=GITHUB_MCP_URL,
            headers={
                "Authorization": f"Bearer {GITHUB_TOKEN}",
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        )
    )

Bu işlev, GitHub'ın MCP sunucusunu çağıran bir araç oluşturur:

  • MCP Toolset (McpToolset): GitHub özelliklerini dinamik olarak keşfeder ve çağrılabilir temsilci araçları olarak kaydeder.
  • Connection Parameters (StreamableHTTPConnectionParams): Araç setini GitHub'ın herkese açık MCP ağ geçidine yönlendirir.
  • Yetkilendirme Başlıkları: GITHUB_TOKEN'yi hamiline ait jeton olarak ekler ve salt okuma modunu (X-MCP-Readonly: true) doğrudan aktarım katmanında zorunlu kılar.

3. GitHub PAT (Kişisel Erişim Jetonu) ile Yerel Olarak Test Etme

Aracıyı statik kimlik bilgileriyle yerel olarak çalıştırmak için:

  1. GitHub Kişisel Erişim Jetonları sayfasında ayrıntılı kişisel erişim jetonu oluşturun:
    • Yeni jeton oluştur'u tıklayın ve jetonunuza bir ad verin.
    • Repository access (Depo erişimi) bölümünde All repositories'i (Tüm depolar) seçin (veya test etmek istediğiniz belirli depoları seçin).
    • Permissions > Repositories (İzinler > Depolar) bölümünde +Add permissions'ı (+İzin ekle) tıklayın ve Contents (İçerikler), Issues (Sorunlar) ve Pull requests'i (Pull istekleri) Read-only (Salt okunur) olarak ayarlayın (Metadata [Meta veriler] otomatik olarak Salt okunur olarak ayarlanır).
    • Jeton oluştur'u tıklayın ve oluşturulan jeton değerini kopyalayın. (Alternatif olarak, Kişisel erişim jetonu (klasik) kullanıyorsanız repo kapsamını seçin.)
  2. Ortamınızda ayarlayın:
    export GITHUB_TOKEN="your_github_pat_here"
    
  3. secure-agent-demo klasörüne gidin (henüz bu klasörde değilseniz) ve yerel deneme alanını başlatın:
    cd secure-agent-demo
    agents-cli playground
    
  4. Playground arayüzünü açın ve açılır menüden app klasörünü seçin. Sohbet kutusunda "Get the last 2 GitHub issues reported against my name" veya "List my 3 most recently updated repositories" gibi hedefe yönelik bir istem deneyin ve temsilcinin GitHub MCP araç setini çağırıp GitHub verilerinizi döndürdüğünü doğrulayın. Temsilcinin sizin adınıza işlem yapmak için PAT jetonunuzu kullanıp kullanmadığını test etmek için özel depolarınız veya katkılarınız hakkında soru sormayı deneyin.

4. Kimlik Doğrulama Yöneticisi'ni yapılandırma

PAT gibi statik kimlik bilgilerini sabit kodlamak prototip oluşturma için kullanışlı olsa da üretim uygulamalarını kimlik bilgisi sızıntısına, manuel jeton yenileme kesinti süresine ve bulutta yerel erişim denetimlerinin eksikliğine maruz bırakır.

Google Cloud, bu sorunu çözmek için Agent Identity Auth Manager'ı sunar. Agent Identity Auth Manager, kimlik bilgilerini korumaya yardımcı olmak için tasarlanmış bir kimlik bilgisi kasasıdır. Temsilcilerin bir API anahtarı veya OAuth istemci kimliği ve gizli anahtarı kullanarak ya da son kullanıcı erişim jetonlarını kullanan OAuth yetkilendirmesi aracılığıyla bir kullanıcı adına kimlik doğrulaması yapmasına olanak tanır.

Auth Manager'da, belirli üçüncü taraf uygulamaları için kimlik doğrulama türünü ve kimlik bilgilerini tanımlayan kimlik doğrulama sağlayıcılarını yapılandırırsınız. Kimlik doğrulama sağlayıcıları bölgeseldir ve bölge, temsilciyi dağıttığınız bölgeyle eşleşmelidir. Uçtan uca Auth Manager iş akışı şu şekilde çalışır:

Auth Manager İş Akışı

  1. Dinamik izin engelleme: Temsilci, bir kullanıcı adına araç çalıştırmaya çalıştığında ADK, Auth Manager'da geçerli bir kimlik bilgisi olup olmadığını kontrol eder. Mevcut bir jeton yoksa Auth Manager, 3 aşamalı OAuth (3LO) izin akışını başlatmak için bir yetkilendirme URL'si döndürür.
  2. Güvenli Kasa Depolama Alanı: Son kullanıcı uygulamayı yetkilendirdikten sonra Auth Manager, OAuth geri çağırma işlemini otomatik olarak durdurur ve elde edilen kullanıcı erişimini ve yenileme jetonlarını Google tarafından yönetilen güvenli bir kimlik bilgisi kasasında depolar.
  3. Otomatik Jeton Yaşam Döngüsü: Auth Manager, jetonun geçerlilik süresini ve rotasyonunu arka planda tümüyle yönetir. Böylece manuel jeton yenileme mantığına veya kapalı kalma süresine gerek kalmaz.
  4. Gizli anahtar içermeyen araç yürütme: Sonraki işlemler için temsilci (SPIFFE temsilci kimliği aracılığıyla kimlik doğrulaması yapar), çalışma zamanında Auth Manager'dan kullanıcının yetkilendirilmiş erişim jetonunu dinamik olarak ister. Böylece hem istemci hem de temsilci kodu tamamen gizli anahtar içermez.

A Adımı: GitHub'ı kimlik doğrulama sağlayıcısı olarak yapılandırın

Google Cloud projenizde GitHub kimlik doğrulama sağlayıcısı oluşturmak için aşağıdaki gcloud komutunu çalıştırın. İstemci kimliğini ve gizli anahtarını daha sonra sağlarsınız: GitHub, bu sağlayıcının geri çağırma URL'sini öğrenene kadar bunları yayınlamaz.

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
    --three-legged-oauth-token-url="https://github.com/login/oauth/access_token"

Oluşturulan OAuth yönlendirme URL'sini almak için sağlayıcıyı tanımlayın:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1"

Alan, authProviderTypeParams.threeLeggedOauth altında iç içe yerleştirilmiş redirectUrl alanıdır. Doğrudan okumak için:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_PROJECT_ID" --location="us-central1" \
    --format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"

https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback gibi görünüyor.

B Adımı: OAuth uygulamasını GitHub'a kaydetme

  1. GitHub Geliştirici Ayarları sayfasına gidin, sol kenar çubuğunda OAuth Apps'i (OAuth Uygulamaları) seçin ve New OAuth App'i (Yeni OAuth Uygulaması) tıklayın (veya daha önce oluşturmadıysanız Register a new application'ı (Yeni uygulama kaydet) tıklayın).
  2. OAuth başvuru formu alanlarını doldurun:
    • Uygulama adı: Uygulamanız için bir ad girin (örneğin, secure-agent-demo).
    • Ana sayfa URL'si: Ön uç uygulamanızın URL'sini girin (yerel prototip oluşturma için http://localhost:8501; bunu üretimde dağıtılan URL'nizle güncelleyebilirsiniz).
    • Uygulama açıklaması: İsteğe bağlıdır (bu alanı boş bırakabilirsiniz).
    • Authorization callback URL (Yetkilendirme geri çağırma URL'si) (Yönlendirme URI'si): A adımında aldığınız redirectUrl değerini yapıştırın.
    • Enable Device Flow (Cihaz Akışını Etkinleştir): İşaretlenmemiş olarak bırakın.
  3. Register application'ı (Uygulamayı kaydet) tıklayın.
  4. Açılan uygulama sayfasında Client ID'yi (İstemci Kimliği) kopyalayın, ardından Generate a new client secret'ı (Yeni bir istemci gizli anahtarı oluştur) tıklayın ve oluşturulan Client secret'ı (İstemci gizli anahtarı) kopyalayın. Her iki değeri de kaydedin. Bir sonraki adımda bunları YOUR_GITHUB_CLIENT_ID ve YOUR_GITHUB_CLIENT_SECRET olarak kullanacaksınız.

C adımı: GitHub kimlik bilgilerini kimlik doğrulama sağlayıcısına ekleyin

YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID ve YOUR_GITHUB_CLIENT_SECRET değerlerini kendi değerlerinizle değiştirip şu komutu çalıştırın:

gcloud agent-identity auth-providers update github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
    --three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"

Komut, sağlayıcıyı clientId görünür olacak şekilde geri döndürür. Gizli anahtar döndürülmez.

👉 Bu adım tamamlandığında Google Cloud Auth Manager, GitHub OAuth uygulamanızın kimlik bilgileriyle tamamen yapılandırılmış olur. Böylece Google Cloud, izin ve jeton yaşam döngülerini yöneten güvenli kasa olarak çalışacak şekilde ayarlanır.

5. PAT jetonunu Auth Manager'a geçirme

Auth Manager tamamen yapılandırıldığına göre, bir sonraki adım temsilcinin araç kodunu güncellemektir. secure-agent-demo/app/tools.py dosyasının içeriğini aşağıdaki kodla değiştirin.

👉 Aşağıdaki OAUTH_PROVIDER_NAME değişkeninde proje kimliğini ve konumu değiştirin.

# app/tools.py

from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())

# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"

# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
    "OAUTH_CONTINUE_URI", 
    "http://localhost:8501/validateUserId"
)

def github_toolset() -> McpToolset:
    """Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
    auth_scheme = GcpAuthProviderScheme(
        name=OAUTH_PROVIDER_NAME,
        # Required to read private repositories. Auth Manager currently supports a
        # single scope for GitHub.
        scopes=["repo"],
        continue_uri=OAUTH_CONTINUE_URI,
    )
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://api.githubcopilot.com/mcp/",
            headers={
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        ),
        auth_scheme=auth_scheme,
    )

Araç Kodunu Anlama

Önemli değişiklik auth_scheme. Bu aracı araç setine eklediğinizde, temsilci GitHub'ı her çağırdığında ADK önce Auth Manager'dan ilgili kullanıcının jetonunu ister. Jeton yoksa hata vermek yerine kullanıcıdan oturum açmasını ister. Sabit kodlu GITHUB_TOKEN tamamen kaldırıldı.

6. Temsilciyi Agent Runtime'a dağıtma

GitHub MCP aracını Auth Manager'ı kullanacak şekilde güncellediğimize göre bir sonraki adım, temsilciyi Agent Runtime'a dağıtmaktır. Aracı Kimliği etkinleştirilmiş olarak dağıtıldığında aracı için benzersiz bir SPIFFE kimliği sağlanır.

Proje için dağıtım yapılandırmasını başlatın. Terminalinizin secure-agent-demo proje kök dizininde olduğundan emin olun ve ardından şu komutu çalıştırın:

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

Bu komut, projenizin yapısını ADK uyumluluğu açısından inceler, temel container paketleme yapılandırmalarını hazırlar ve proje kök dizininizde varsayılan dağıtım ayarlarıyla önceden doldurulmuş bir agents-cli-manifest.yaml dosyası oluşturur.

👉 Temsilcinizin kimlik doğrulama sağlayıcınızla aynı bölgede dağıtıldığından emin olmak için yeni oluşturulan agents-cli-manifest.yaml dosyasını açın ve region alanını us-central1 olarak doğrulayın veya güncelleyin:

region: "us-central1"

Temsilciyi bir temsilci kimliğiyle dağıtma

adk deploy agent_engine ile dağıtın. Bu işlem, temsilciye kendi temsilci kimliğini sağlar. Bu kimlik, bu dağıtıma ait benzersiz, SPIFFE destekli bir şifreleme kimliğidir ve temsilci tarafından Auth Manager ile diğer Google Cloud hizmetlerinde kimlik doğrulaması yapmak için kullanılır.

👉 secure-agent-demo dizininden YOUR_PROJECT_ID değerini değiştirin ve şu komutları çalıştırın:

# Write a config file inside the `app/` folder instructing Agent Runtime to provision a SPIFFE-backed `AGENT_IDENTITY` for this deployment.
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json

# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
    --output-file app/requirements.txt

uv run adk deploy agent_engine app \
    --project="YOUR_PROJECT_ID" \
    --region="us-central1"

Dağıtımın kapsayıcıyı oluşturması ve yüklemesi birkaç dakika sürer. İşlem tamamlandığında CLI, dağıtılan kaynağın adını yazdırır. reasoningEngines/ENGINE_ID değerini not edin. Temsilcinizi yetkilendirmek ve kullanıcı arayüzü istemcisini bu değere yönlendirmek için bu değere ihtiyacınız vardır.

Temsilci kimliğini yetkilendirme

Temsilciniz artık bulutta çalıştığı için Auth Manager'da depolanan kimlik bilgileri deposuna erişim izni gerekiyor. Varsayılan olarak, temsilcinin SPIFFE kimliğinin harici bulut kaynaklarına erişimi yoktur.

Kimlik doğrulama sağlayıcı kaynağında temsilcinizin kimliğine roles/agentidentity.user rolünü vermek için aşağıdaki gcloud komutunu çalıştırın. Bu sayede temsilciniz, kasadan kullanıcı jetonları istemek için gereken izinleri alır.

# Get YOUR_ORG_ID
gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
  --format="value(projectNumber)"

Ardından IAM politikasını kimlik sağlayıcıya bağlayın (YOUR_PROJECT_ID ve --member ana hesabını değiştirerek):

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"

👉 Dağıtılan temsilcinizin tam --member="principal://..." değerini Google Cloud Console'dan da alabilirsiniz: Agent Runtime konsoluna gidin, dağıtılan temsilcinizi seçin, Identity (Kimlik) sekmesine gidin ve tam principal://... dizesini doğrudan kopyalayın.

Şimdi sağlayıcıda kendi hesabınıza aynı rolü verin. Bir sonraki adımda çalıştırdığınız kullanıcı arayüzü istemcisi, Uygulama Varsayılan Kimlik Bilgilerinizle kimlik bilgisi tamamlama API'sini çağırır. Bu nedenle, bu adım olmadan izin akışı agentidentity.authProviders.retrieveCredentials adresinde 403 hatasıyla başarısız olur:

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="user:YOUR_EMAIL_ADDRESS"

7. 3LO izin akışını anlama

Temsilci, güvenli bir temsilci kimliğiyle Agent Runtime'a dağıtıldıktan sonraki adım, kullanıcıların temsilciyle sohbet edebileceği özel bir ön uç arayüzü sağlamaktır. Daha da önemlisi, Google Cloud Auth Manager'ın kimlik doğrulama döngüsünü tamamlamak için bir istemci uygulama geri çağırma işleyicisine ihtiyacı vardır.

Google Cloud Auth Manager, kullanıcı kimlik bilgilerini bir kasada güvenli bir şekilde yönetse de OAuth jeton değişimini kendi başına tamamlayamaz. 3LO el sıkışması, boşluğu doldurmak için istemci uygulamayı kullanır:

  1. Kullanıcı GitHub uygulamasını yetkilendirdiğinde GitHub, kullanıcıyı Temsilci Kimliği kimlik doğrulama sağlayıcısına redirectUrl yönlendirir.
  2. Auth Manager, kullanıcının tarayıcı pop-up'ını bir istemci tarafı geri çağırma URL'sine (continue_uri) yönlendirir.
  3. Bu yönlendirmeyi yakalamak, tarayıcının çerezlerinden tek seferlik rastgele sayıyı okumak ve el sıkışmayı tamamlamak için Google Cloud'un credentials:finalize uç noktasını çağırmak istemci uygulamanın sorumluluğundadır.
  4. Müşteri, değişimi tamamladıktan sonra Google Cloud, jetonu kimlik doğrulama sağlayıcısının kasasına güvenli bir şekilde kaydeder. Böylece temsilci, GitHub aracını çağırabilir.

Geri çağırma uç noktasını barındıran bu özel istemci olmadan el sıkışma tamamlanamaz ve kasa, kimlik bilgilerini depolayamaz.

Etkileşimli OAuth 3LO akışı birden fazla katmanı kapsar. Araç isteğinin tam yürütme yaşam döngüsü aşağıda verilmiştir. Bu konuyu aşağıdaki açıklamada ve bir sonraki adımda ayrıntılı olarak ele alacağız.

👉 Resmi büyütmek için tıklayın.

3 Legged OAuth sequence flow

El Sıkışma Sürecinde Müşterinin Temel Sorumlulukları

  • İzin doğrulamasını iletme (5-6. adımlar): Temsilci, izin URL'sini ve tek seferlik rastgele sayıyı içeren bir adk_request_credential gönderir. İstemci, pop-up'ı açar ve tek seferlik rastgele sayıyı çerez olarak depolar.
  • Yönlendirme geri çağırma işlevini barındırın (10-11. adımlar): /validateUserId. Kimlik Doğrulama Yöneticisi, izin verildikten sonra pop-up'ı buraya gönderir.
  • Jetonu tamamlama (12-14. adımlar): Yönlendirmeden gelen doğrulama durumunu önbelleğe alınmış tek seferlik rastgele sayı ile birleştirin ve jetonu kasada depolayan credentials:finalize yöntemini çağırın.

Kendi istemcinizi oluşturma

Bu laboratuvar için bu istemciyi yazmanız gerekmez. Bir sonraki adımda önceden oluşturulmuş bir istemci çalıştırılır. Bunu kendi uygulamanızda kullanmak istediğinizde yararlanabileceğiniz iki referans şunlardır:

8. Kullanıcı arayüzü istemcisini yerel olarak çalıştırma

3LO İzin Akışı sıra diyagramında gösterildiği gibi, Auth Manager tarayıcı penceresini istemci tarafı geri çağırma uç noktasına yönlendirir. adk-python deposundaki örnek istemci, bu uç noktayı /validateUserId adresinde barındırır. Aşağıdaki adımları uygulayarak dosyayı indirin ve yerel olarak çalıştırın.

Müşteri dosyalarını indirme

adk-python içindeki contributing/samples/integrations/gcp_auth/client dizini üç önemli öğe içerir:

  • main.py: Dağıtılan Agent Engine'inize bağlanan ve OAuth jetonlarını tamamlamak için /validateUserId geri çağırma uç noktasını barındıran FastAPI arka ucu.
  • static/: Tarayıcı sohbet kullanıcı arayüzü için HTML ve JavaScript dosyaları.
  • requirements.txt: İstemci sunucusunu çalıştırmak için gereken Python paketleri.

adk-python büyük bir depo olduğundan, yalnızca contributing/samples/integrations/gcp_auth/client klasörünü indirmek için Git'in seyrek ödeme özelliğini kullanın:

  1. Öncelikle, istemciyi eş bir klasöre kopyalamak için secure-agent-demo dizininden bir dizin yukarı çıkın:
    cd ..
    
  2. Tüm dosyaları indirmeden depo meta verilerini klonlamak (--no-checkout), kullanıma alma yolunu contributing/samples/integrations/gcp_auth/client ile kısıtlamak ve yalnızca bu klasörü kullanıma almak için aşağıdaki komutları çalıştırın:
    git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git
    cd adk-python
    git sparse-checkout init --cone
    git sparse-checkout set contributing/samples/integrations/gcp_auth/client
    git checkout
    

İstemciyi çalıştırma

  1. Yeni girdiğiniz adk-python dizininin içinden client klasörüne gidin:
    cd contributing/samples/integrations/gcp_auth/client
    
  2. Bir Python sanal ortamı oluşturup etkinleştirin, ardından istemcinin bağımlılıklarını requirements.txt adresinden yükleyin:
    uv venv --python 3.13 .venv
    source .venv/bin/activate
    uv pip install --python .venv/bin/python -r requirements.txt
    
  3. İstemciyi Google Cloud projenize, bölgenize (us-central1) ve dağıtılan Agent Engine kimliğinize (YOUR_ENGINE_ID) yönlendiren ortam değişkenlerini ayarlayın, ardından 8501 bağlantı noktasında yerel FastAPI sunucusunu başlatın:
    export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=us-central1
    export AGENT_ID=YOUR_ENGINE_ID
    
    .venv/bin/uvicorn main:app --port 8501
    
  4. Sunucunun başarıyla başlatıldığını ve http://localhost:8501 bağlantı noktasını dinlediğini doğrulayın.

9. OAuth akışını test etme

Tüm hizmetler dağıtıldığına, IAM bağlamaları yapılandırıldığına ve ortam değişkenleri ayarlandığına göre, güvenli uçtan uca kullanıcı tarafından yetkilendirilmiş yetkilendirme akışını test etmeye hazırsınız.

A Adımı: Araç yürütme işlemini başlatın

  1. Bir tarayıcı sekmesi açın ve istemci URL'nize gidin: http://localhost:8501.
  2. Sol bölmedeki Configuration Settings (Yapılandırma Ayarları) bölümünde Agent Type'ı (Aracı Türü) Remote Agent (Vertex AI) (veya Remote Agent Engine) olarak ayarlayın.
  3. Google Cloud proje kimliğinizi ve konumunuzu (us-central1) girin, ardından Uzak Aracıları Yükle'yi tıklayın. Bu işlem, projenize dağıtılan temsilcileri yükler.
  4. Select Engine (Motor Seçin) açılır menüsünden dağıtılan app temsilcinizi seçin ve Save & Apply Settings'i (Ayarları Kaydet ve Uygula) tıklayın.
  5. Sohbet kutusuna hedefli bir sorgu (ör. son sorunlarınızı veya depolarınızı getirme) yazın:
    Get the last 2 GitHub issues reported against my name
    
    (veya "List my 3 most recently updated repositories") yazın ve Enter tuşuna basın.
  6. Sohbet kullanıcı arayüzünü inceleyin: Temsilcinin henüz kullanıcı oturumunuz için kimlik bilgileri olmadığından bir kimlik doğrulama sorgulaması alır ve görüşme dizisinde "Kimlik Doğrulama Gerekli" kartını gösterir.
  1. Ayrı bir tarayıcı pop-up penceresi açılır ve sizi Google Cloud'un Auth Manager'ı üzerinden GitHub OAuth yetkilendirme sayfasına yönlendirir.
  2. İstenen izinleri inceleyin ve Yetkilendir'i tıklayın.
  3. GitHub, Google Cloud'a yönlendirir. Google Cloud da pop-up'ı localhost geri çağırma URL'nize /validateUserId yönlendirir.
  4. Geri çağırma hizmeti, kimlik bilgileri el sıkışmasını işler ve tamamlar.

C Adımı: Devam ettirme

  1. Pop-up pencere kapandığında üst sohbet sekmesi, kapanma işlemini otomatik olarak algılar.
  2. Ön uç, temsilciye bir devam yükü gönderir.
  3. Temsilci, yeni değiştirilen jetonu Google Cloud Auth Manager'dan güvenli bir şekilde alır, sizin adınıza GitHub MCP araçlarını çağırır ve GitHub verilerinizi doğrudan sohbet penceresine aktarır. Temsilci, bu verilere kendi başına erişemezdi.

D Adımı: Cloud günlüklerini inceleyin

Jeton değişiminin ve sonlandırma işleminin güvenli bir şekilde işlendiğini doğrulamak için:

  1. Google Cloud Console Günlük Gezgini'ne gidin.
  2. Tek seferlik rastgele sayının çıkarıldığını ve başarıyla doğrulandığını onaylayan sunucu günlüklerini bulun:
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
    INFO:secure-agent-client:Successfully finalized auth provider credentials.
    
  3. Temsilci çalışma zamanı günlüklerini inceleme: Alternatif olarak, yürütme günlüklerini doğrudan Agent Platform konsolunda görüntüleyebilirsiniz:
    • Agent Runtime Console'a gidin.
    • Listeden dağıtılan temsilcinizi tıklayın.
    • Playground sekmesine geçin. Bu sekmede, alt bölmede canlı temsilci günlükleri gösterilir. Bu günlüklerde temsilcinin akıl yürütme döngüsü, araç yürütme ayrıntıları ve jeton alma yaşam döngüsü gerçek zamanlı olarak gösterilir.

10. Temizleme

Google Cloud'da ücret ödemeye devam etmemek için dağıtılan kaynaklarınızı temizleyin:

# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3

# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
    --project=YOUR_PROJECT_ID --location=us-central1

# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.

# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID

# Optionally, delete the GitHub PAT Token and the OAuth app: 
# https://github.com/settings/personal-access-tokens

Yerel dosyaları temizleme

İsteğe bağlı olarak, yerel ortamınızı tamamen temizlemek için:

  1. Çalıştığı terminalde Ctrl+C tuşlarına basarak yerel uvicorn sunucusunu durdurun.
  2. Bu laboratuvar sırasında oluşturulan proje dizinlerini kaldırın:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. Tebrikler!

Oturum açmış kullanıcı adına işlem yapan bir temsilciyi başarıyla oluşturup güvenliğini sağladınız.

Öğrendikleriniz:

  • Temsilci Sistem Kimliği: Temsilcinin, GCP altyapısıyla güvenli bir şekilde arayüz oluşturmak, telemetri günlüklerini yönetmek ve kimlik bilgisi tamamlama API'lerini çağırmak için kendi hesap kimliği altında nasıl çalıştığı.
  • Kullanıcı Tarafından Yetkilendirilmiş Kimlik: Temsilcinin, 3 ayaklı OAuth (3LO) izin akışını tetikleyerek harici platformlarda (ör. GitHub) kullanıcı adına işlem yapmak için nasıl yetkilendirme istediği.
  • Güvenli Araç Entegrasyonu: Sabit kodlanmış gizli anahtarlar yerine kullanıcı jetonlarını dinamik olarak almak için Google Cloud Auth Manager'ı kullanarak ADK aracılarını Model Context Protocol (MCP) sunucularına bağlama.
  • IAM Politikası Yapılandırması: Kimlik doğrulama sağlayıcısında hem temsilci çalışma zamanı kimliğini hem de kendi hesabınızı yetkilendirmek için ayrıntılı izin bağlamalarını ayarlama.

Daha fazla bilgi