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 bilgisiyle bir ajan, 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 aracı oluşturacaksınız. Böylece aracı, kullanıcının görebildiği her şeyi ve daha fazlasını görebilecek.

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

Özellikle, aşağıdakilerin geçerli olduğu çift kimlikli bir mimari tasarlamayı öğreneceksiniz:

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

Çift Kimlik Mimarisi

Bunu başarmak için şunları yapmayı öğreneceksiniz:

  1. GitHub'ın Model Bağlam Protokolü (MCP) sunucusuna bağlanan bir ADK ajanı oluşturun.
  2. Google Cloud Auth Manager'ı kullanarak aracının aracını statik bir GitHub PAT'den (kişisel erişim jetonu) 3 aşamalı OAuth (3LO) akışına güncelleyin.
  3. Ajanı Agent Runtime'a güvenli bir şekilde dağıtın ve Agent Identity'yi (Ajan Kimliği) sağlayın.
  4. IAM rollerini, kullanıcının adına aracının jeton kasasına kimlik erişimi sağlamak için yapılandırın.
  5. Google Cloud'da Auth Manager için uçtan uca 3LO akışını anlayın.

Ön koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

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

2. Proje Ayarları

1. Google Cloud'da kimlik doğrulama

Ortamınızın bu laboratuvar sırasında Agent Runtime'a dağıtım yapma, Agent Identity'yi sağlama ve Auth Manager'ı yapılandırma için gerekli izinlere sahip olduğundan emin olmak üzere yerel komut satırınızdan Google Cloud'da kimliğinizi doğrulayın:

Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) yapılandırmak için Google Cloud hesabınıza giriş yapmak üzere aşağıdaki komutları çalıştırın:

gcloud auth login
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. CLI aracılarını yükleme ve projeyi ayarlama

agents-cli, ADK aracılarını Gemini Enterprise'a yerleştirmek, 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. Önce yerel bir prototiple başlayıp daha sonra Agent Runtime dağıtımı için geliştireceksiniz:

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

Bu işlem, temel aracı 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ı ekleyin

Oluşturulan pyproject.toml gemisinde google-adk[gcp,otel-gcp], bu aracının ihtiyaç duyduğu iki ek özellik eksik: GitHub araç seti için mcp ve laboratuvarın ilerleyen bölümlerinde Auth Manager için agent-identity. secure-agent-demo/pyproject.toml dosyasını açın ve google-adk satırını şu şekilde değiştirin:

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

Ardından yükleyin:

cd secure-agent-demo
agents-cli install

3. Ajanı oluşturma ve test etme

1. Ajanı oluşturma

Projenizde, agent.py dosyasındaki kodu aşağıdakiyle 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, aracının üç temel bileşenini tanımlar:

  • Sistem Talimatı (INSTRUCTION): Kişiliği belirler, asistanın kapsamını GitHub triyajı ile sınırlar ve katı güvenlik kurallarını (ör. salt okunur erişim ve hatalar oluşursa kullanıcıları kimlik doğrulamaya yönlendirme) uygular.
  • Aracı Yapılandırması (root_agent): gemini-3.8-flash modelini kullanarak bir ADK Agent oluşturur, HTTP yeniden deneme mantığını yapılandırır ve aracıya GitHub araç setini ekler.
  • Uygulama Sarmalayıcı (app): Kök aracıyı bir ADK App kapsayıcısına yerleştirerek Aracı Çalışma Zamanı'na dağıtılabilir hâle getirir.

2. GitHub MCP aracını ekleme

Aracı, Model Bağlam Protokolü (MCP) aracılığıyla GitHub'a bağlanır. MCP ağ geçidi bağlantı parametrelerini kaydetmek için app/ klasöründe tools.py adlı 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 aracı araçları olarak kaydeder.
  • Bağlantı Parametreleri (StreamableHTTPConnectionParams): Araç setini GitHub'ın herkese açık MCP ağ geçidine yönlendirir.
  • Yetkilendirme Başlıkları: GITHUB_TOKEN öğesini Bearer jetonu 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ı statik kimlik bilgileriyle yerel olarak çalıştırmak için:

  1. GitHub kişisel erişim jetonu oluşturun. Aksi takdirde, aracı yalnızca herkese açık verileri görebilir ve aşağıdaki istem hiçbir sonuç döndürmez. Bu nedenle, araca depolarınıza okuma erişimi verin.
  2. Ortamınızda ayarlayın: 
    export GITHUB_TOKEN="your_github_pat_here"
  3. secure-agent-demo klasörüne gidin. Koşu: 
    cd secure-agent-demo
agents-cli playground
  4. Playground arayüzünü açın ve açılır listeden "app" klasörünü seçin. Sohbet kutusuna "Fetch my contributions across my private repositories over the last 6 months" yazın ve aracının GitHub aracını çağırdığını, özel depolarınızdaki verileri döndürdüğünü doğrulayın.

4. Kimlik doğrulama yöneticisini yapılandırma

Statik kimlik bilgilerini (ör. PAT) sabit kodlamak prototip oluşturma açısından kolaylık sağlasa da üretim uygulamalarını kimlik bilgilerinin sızmasına, manuel jeton yenileme sırasında hizmet dışı kalmaya ve buluta özel erişim kontrollerinin olmamasına karşı savunmasız 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. Bu sayede temsilciler, API anahtarı veya OAuth istemci kimliği ve sırrı kullanarak ya da son kullanıcı erişim jetonlarını kullanarak OAuth temsilciliği aracılığıyla bir kullanıcı adına kimlik doğrulaması yapabilir.

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, aracıyı dağıttığınız bölgeyle eşleşmelidir. Uçtan uca Yetkilendirme Yöneticisi iş akışı şu şekilde çalışır:

Auth Manager iş akışı

  1. Dinamik İzin Yakalama: Temsilci, bir kullanıcı adına bir aracı yürütmeye çalıştığında ADK, Auth Manager'da mevcut ve geçerli bir kimlik bilgisi olup olmadığını kontrol eder. Yoksa Auth Manager, 3 ayaklı OAuth (3LO) izin akışını başlatmak için bir yetkilendirme URL'si döndürür.
  2. Güvenli kasa depolama: Son kullanıcı uygulamayı yetkilendirdikten sonra Auth Manager, OAuth geri çağırmasını otomatik olarak yakalar ve sonuçtaki kullanıcı erişimini ve yenileme jetonlarını güvenli, Google tarafından yönetilen bir kimlik bilgisi kasasında saklar.
  3. Otomatik Jeton Yaşam Döngüsü: Auth Manager, jetonun süresinin dolmasını ve döndürülmesini arka planda tamamen 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 aracı (SPIFFE aracısı kimliği aracılığıyla kimlik doğrulama), çalışma zamanında kullanıcının yetkilendirilmiş erişim jetonunu Auth Manager'dan dinamik olarak ister. Böylece hem istemci hem de aracı 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 bilene kadar bunları yayınlamaz.

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="${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ı açıklayın:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1"

Alan redirectUrl olup authProviderTypeParams.threeLeggedOauth altında yer alır. Doğrudan okumak için:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${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'da kaydetme

  1. GitHub Geliştirici Ayarları sayfasına gidin ve Yeni bir OAuth uygulaması kaydet'i tıklayın.
  2. Ana Sayfa URL'si için ön uç uygulamanızın URL'sini girin (ör. yerel prototip oluşturma için http://localhost:8501). Daha sonra bunu üretimdeki dağıtılmış URL'nizle değiştirebilirsiniz.
  3. Yönlendirme URI'sini önceki adımda alınan redirectUrl olarak ayarlayın.
  4. Register application'ı (Uygulamayı kaydet) ve ardından Generate a new client secret'ı (Yeni bir istemci gizli anahtarı oluştur) tıklayın. İstemci kimliğini ve istemci gizli anahtarını kaydedin.

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

Proje kimliğinizi, istemci kimliğinizi ve istemci gizli anahtarınızı değiştirip bu 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 şekilde geri yansıtır. Gizli dizi yansıtılmaz.

👉 Bu adım tamamlandığında Google Cloud Auth Manager, GitHub OAuth uygulaması kimlik bilgilerinizle tamamen yapılandırılır. 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

Yetkilendirme Yöneticisi tamamen yapılandırıldığına göre, bir sonraki adım aracının araç kodunu güncellemek olacaktır. app/tools.py kısmını 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

En önemli değişiklik auth_scheme. Araç setine eklemek, aracı GitHub'ı her çağırdığında ADK'nın önce Auth Manager'dan kullanıcının jetonunu istemesi ve henüz bir jeton yoksa başarısız olmak yerine kullanıcıdan oturum açmasını istemesi anlamına gelir. Sabit kodlu GITHUB_TOKEN tamamen kaldırıldı.

6. Agent'ı Agent Runtime'a dağıtma

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

Öncelikle projenin dağıtım yapılandırmasını başlatarak başlayalım. Terminalde çalıştırın:

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

Bu komut, proje yapınızı ADK uyumluluğu açısından inceler, temel kapsayıcı 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.

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

region: "us-central1"

Ajanı, Ajan Kimliği ile Dağıtma

adk deploy agent_engine ile dağıtın. Bu işlem, aracıya kendi Agent Identity'sini sağlar. Bu, dağıtıma ait, SPIFFE destekli benzersiz bir kriptografik kimliktir. Aracı, Auth Manager ve diğer Google Cloud hizmetlerinde kimliğini doğrulamak için bu kimliği kullanır.

👉 Bu komutları çalıştırmadan önce YOUR_PROJECT_ID yerine kendi değerinizi girin:

# Request 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, kapsayıcının oluşturulması ve yüklenmesi için birkaç dakika sürer. İşlem tamamlandığında CLI, dağıtılan kaynak adını yazdırır. Ajanınızı yetkilendirmek ve kullanıcı arayüzü istemcisini yönlendirmek için reasoningEngines/ENGINE_ID değerini not edin.

Ajan kimliğini yetkilendirme

Aracınız artık bulutta çalıştığına göre, Auth Manager'da depolanan kimlik bilgilerine erişmek için izne ihtiyacı var. Varsayılan olarak, aracının SPIFFE kimliği harici bulut kaynaklarına erişemez.

gcloud rolünü roles/agentidentity.user kimlik sağlayıcı kaynağındaki aracı kimliğinize atamak için aşağıdaki komutu çalıştırın. Bu, aracınıza kasadan kullanıcı jetonları istemek için tam olarak ihtiyaç duyduğu izinleri verir.

👉 YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER ve YOUR_ENGINE_ID yerine kendi değerlerinizi girin (motor kimliği, yukarıdaki dağıtım çıktısında yer alır).

YOUR_ORG_ID değerini almak için aşağıdaki komutu çalıştırın:

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

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"

Ş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, kimlik bilgisi sonlandırma API'sini Uygulama Varsayılan Kimlik Bilgilerinizle çağırır. Bu nedenle, bu olmadan izin verme akışı agentidentity.authProviders.retrieveCredentials üzerinde 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. Üçüncü taraf izni akışını anlama

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

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

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

Geri arama uç noktasını barındıran bu özel istemci olmadan el sıkışma işlemi tamamlanmaz ve kasa, kimlik bilgilerini depolayamaz.

Etkileşimli OAuth 3LO akışı birden fazla katmanı kapsar. Bir 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 sonraki adımda ayrıntılı olarak ele alacağız.

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

3 bacaklı OAuth sıra akışı

El sıkışma anlaşmasında Müşteri'nin temel sorumlulukları

  • İzin isteğini iletin (5-6. adım): Aracı, izin URL'sini ve tek kullanımlık bir tek seferlik rastgele sayı içeren bir adk_request_credential yayınlar. İstemci, pop-up'ı açar ve tek seferlik rastgele sayıyı çerez olarak depolar.
  • Yönlendirme geri çağırmasını barındırın (10-11. adımlar): /validateUserId, burada Auth Manager, izin verildikten sonra pop-up'ı gönderir.
  • Jetonu sonlandırın (12-14. adımlar): Doğrulama durumunu yönlendirmeden önbelleğe alınmış nonce ile birleştirin ve jetonu kasada saklayan credentials:finalize işlevini çağırın.

Kendi istemcinizi oluşturma

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

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

3LO İzin Akışı sıralı diyagramında izlediğimiz gibi, Auth Manager'ın tarayıcı pop-up'ını istemci tarafı geri çağırma uç noktasına yönlendirmesi gerekir. Örnek istemci, bu uç noktayı /validateUserId adresinde barındırır. Yerel olarak çalıştıralım.

İstemci dosyalarını Yerel'e kopyalama

adk-python GitHub deposundaki gcp_auth/client klasörüne gidin. Bu klasör, sohbet istemcisi kapsayıcımızı oluşturmak için gereken öğeleri içerir.

👉 gcp_auth/client altındaki tüm dosyaları yerel ortamınıza kopyalayın:

  • main.py: Önceki bölümde ele aldığımız jeton sonlandırma geri çağırmasını (/validateUserId) içeren FastAPI uygulama komut dosyası.
  • static/: HTML sayfalarını içerir.

Alternatif olarak, klasörün seyrek ödemesini de yapabilirsiniz:

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. Az önce kopyaladığınız client klasörüne gidin: 
    cd adk-python/contributing/samples/integrations/gcp_auth/client
  2. Sanal ortam oluşturun ve istemcinin bağımlılıklarını yükleyin. Klasörde requirements.txt var ancak pyproject.toml yok. Bu nedenle, tek başına uv run uvicorn ..., Failed to spawn: uvicorn ile başarısız oluyor: 
    uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install --python .venv/bin/python -r requirements.txt
  3. İstemciyi dağıttığınız aracıya yönlendirin ve 8501 bağlantı noktasında 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 üzerinde dinleme yaptığını 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 artık güvenli uçtan uca kullanıcı tarafından 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çıp istemci URL'nize gidin: http://localhost:8501.
  2. Sol bölmede, Aracı Türü'nü Remote Agent Engine olarak ayarlayın.
  3. Google Cloud projenizi ve konumunuzu yazın. Load Remote Agents simgesini tıklayın. Bu işlem, projenize dağıtılan tüm aracıları yükler.
  4. Açılır listeden doğru aracı seçin ve ayarları kaydedin.
  5. Sohbet kutusuna şunu yazın: 
    Fetch my contributions across my private repositories over the last 6 months
    yazıp Enter tuşuna basın.
  6. Sohbet kullanıcı arayüzünü inceleyin: Temsilcinin henüz kullanıcı oturumunuz için kimlik bilgileri olmadığı için kimlik doğrulama sorgusu alır ve ileti 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 geri 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 ettir

  1. Pop-up pencere kapandığında üst sohbet sekmesi kapanmayı otomatik olarak algılar.
  2. Ön uç, devam ettirme yükünü tekrar aracıya gönderir.
  3. Aracı, 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 verileri özel depolarınızdan doğrudan sohbet penceresine aktarır. Bu veriler, aracının kendi başına ulaşamayacağı verilerdir.

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

Jeton değişimi ve sonlandırmanın güvenli bir şekilde işlendiğini doğrulamak için:

  1. Google Cloud Console Günlük Gezgini'ne gidin.
  2. Nonce ayıklama ve başarılı doğrulama işlemlerini 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. Aracı çalışma zamanı günlüklerini inceleme: Alternatif olarak, yürütme günlüklerini doğrudan Agent Platform Console'da görüntüleyebilirsiniz:
    • Agent Runtime Console'a gidin.
    • Listeden dağıtılan temsilcinizi tıklayın.
    • Playground (Deneme Alanı) sekmesine geçin. Bu sekmede, alt bölmede canlı aracı günlükleri gösterilir. Böylece aracının muhakeme döngüsünü, araç yürütme ayrıntılarını ve jeton alma yaşam döngüsünü anlık olarak görebilirsiniz.

10. Temizleme

Google Cloud'da sürekli olarak ücretlendirilmemek 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 hareket eden bir ajanı başarıyla oluşturup güvenliğini sağladınız.

Öğrendikleriniz:

  • Aracı Sistem Kimliği: Aracının, GCP altyapısıyla güvenli bir şekilde arayüz oluşturmak, telemetri günlüklerini yönetmek ve kimlik bilgisi sonlandırma API'lerini çağırmak için kendi Hesap kimliği altında nasıl çalıştığı.
  • Kullanıcı Tarafından Yetkilendirilmiş Kimlik: Aracının, 3 ayaklı OAuth (3LO) izin akışını tetikleyerek harici platformlarda (ör. GitHub) kullanıcı adına işlem yapmak için nasıl yetki istediği.
  • Güvenli Araç Entegrasyonu: Sabit kodlanmış Gizli Anahtarlar kullanmak yerine kullanıcı jetonlarını dinamik olarak getirmek için Google Cloud Auth Manager'ı kullanarak ADK ajanlarını Model Bağlam Protokolü (MCP) sunucularına bağlama.
  • IAM Politikası Yapılandırması: Hem Agent Runtime kimliğini hem de kendi hesabınızı kimlik doğrulama sağlayıcısında yetkilendirmek için ayrıntılı izin bağlamalarını ayarlama.

Daha fazla bilgi