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:
- 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.
- 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.

Bunu yapmak için şunları öğreneceksiniz:
- GitHub'ın Model Context Protocol (MCP) sunucusuna bağlanan bir ADK temsilcisi oluşturun.
- 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.
- Temsilciyi Agent Runtime'a güvenli bir şekilde dağıtın ve Agent Identity'yi temel hazırlayın.
- Temsilcinin kimliğinin kullanıcı adına jeton kasasına erişebilmesi için IAM rollerini yapılandırın.
- 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 (
gcloudCLI). 586.0.0 veya daha yeni bir sürüm gereklidir:gcloud components updatekomutunu çalıştırın. - Yerel olarak yüklenmiş Python 3.10 ila 3.13.
uvpaket 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-flashmodelini kullanarak bir ADKAgentö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 ADKAppkapsayı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:
- 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
repokapsamını seçin.)
- Ortamınızda ayarlayın:
export GITHUB_TOKEN="your_github_pat_here" secure-agent-demoklasö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- Playground arayüzünü açın ve açılır menüden
appklasö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:

- 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.
- 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.
- 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.
- 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
- 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).
- 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
redirectUrldeğerini yapıştırın. - Enable Device Flow (Cihaz Akışını Etkinleştir): İşaretlenmemiş olarak bırakın.
- Uygulama adı: Uygulamanız için bir ad girin (örneğin,
- Register application'ı (Uygulamayı kaydet) tıklayın.
- 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_IDveYOUR_GITHUB_CLIENT_SECRETolarak 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:
- Kullanıcı GitHub uygulamasını yetkilendirdiğinde GitHub, kullanıcıyı Temsilci Kimliği kimlik doğrulama sağlayıcısına
redirectUrlyönlendirir. - Auth Manager, kullanıcının tarayıcı pop-up'ını bir istemci tarafı geri çağırma URL'sine (
continue_uri) yönlendirir. - 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:finalizeuç noktasını çağırmak istemci uygulamanın sorumluluğundadır. - 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.
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_credentialgö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:finalizeyö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:
- Auth Manager belgelerindeki İstemci tarafı uygulamanızı güncelleme bölümü, izin sorgulamasını işlemeyi ve
credentials:finalizeyöntemini çağırmayı kapsar. - adk-python deposundaki çalıştırılabilir örnek istemci. Yukarıdaki üç sorumluluğun eksiksiz ve çalışan bir uygulaması için
main.pybölümünü okuyun.
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/validateUserIdgeri ç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:
- Öncelikle, istemciyi eş bir klasöre kopyalamak için
secure-agent-demodizininden bir dizin yukarı çıkın:cd .. - Tüm dosyaları indirmeden depo meta verilerini klonlamak (
--no-checkout), kullanıma alma yolunucontributing/samples/integrations/gcp_auth/clientile 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
- Yeni girdiğiniz
adk-pythondizininin içindenclientklasörüne gidin:cd contributing/samples/integrations/gcp_auth/client - Bir Python sanal ortamı oluşturup etkinleştirin, ardından istemcinin bağımlılıklarını
requirements.txtadresinden yükleyin:uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - İ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ından8501bağ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 - Sunucunun başarıyla başlatıldığını ve
http://localhost:8501bağ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
- Bir tarayıcı sekmesi açın ve istemci URL'nize gidin:
http://localhost:8501. - Sol bölmedeki Configuration Settings (Yapılandırma Ayarları) bölümünde Agent Type'ı (Aracı Türü)
Remote Agent (Vertex AI)(veyaRemote Agent Engine) olarak ayarlayın. - 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. - Select Engine (Motor Seçin) açılır menüsünden dağıtılan
apptemsilcinizi seçin ve Save & Apply Settings'i (Ayarları Kaydet ve Uygula) tıklayın. - Sohbet kutusuna hedefli bir sorgu (ör. son sorunlarınızı veya depolarınızı getirme) yazın:
(veyaGet the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories") yazın ve Enter tuşuna basın. - 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.
B Adımı: 3 Aşamalı OAuth İznini Tamamlama
- 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.
- İstenen izinleri inceleyin ve Yetkilendir'i tıklayın.
- GitHub, Google Cloud'a yönlendirir. Google Cloud da pop-up'ı
localhostgeri çağırma URL'nize/validateUserIdyönlendirir. - Geri çağırma hizmeti, kimlik bilgileri el sıkışmasını işler ve tamamlar.
C Adımı: Devam ettirme
- Pop-up pencere kapandığında üst sohbet sekmesi, kapanma işlemini otomatik olarak algılar.
- Ön uç, temsilciye bir devam yükü gönderir.
- 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:
- Google Cloud Console Günlük Gezgini'ne gidin.
- 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. - 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:
- Çalıştığı terminalde Ctrl+C tuşlarına basarak yerel uvicorn sunucusunu durdurun.
- 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
- Kimlik doğrulama akışı yapılandırmasını ve kapsamlarını anlamak için Agent Identity Auth Manager.
- Agent Runtime'a genel bakış
- ADK Belgeleri
- Model Bağlam Protokolü
