Tworzenie agenta AI, który działa w imieniu użytkownika, za pomocą Agent Identity i Menedżera uwierzytelniania

1. Wprowadzenie

Agent z własnymi danymi logowania i szerokimi uprawnieniami widzi dane wszystkich użytkowników. W tym ćwiczeniu programistycznym utworzysz agenta, który wywołuje interfejs API innej firmy przy użyciu danych logowania zalogowanego użytkownika, dzięki czemu widzi dokładnie to, co ta osoba, i nic więcej.

Utworzysz go za pomocą pakietu Google Agent Development Kit (ADK) i Gemini Enterprise.

Dowiesz się, jak zaprojektować architekturę podwójnej tożsamości, w której:

  1. Agent działa we własnym imieniu (tożsamość agenta): używając tożsamości agenta opartej na SPIFFE, agent wywołuje menedżera uwierzytelniania, przechowuje dane telemetryczne i wywołuje interfejsy Google Cloud API.
  2. Agent działa w imieniu użytkownika (tożsamość przekazana przez użytkownika): aby uzyskać dostęp do zasobów zewnętrznych, takich jak GitHub, agent uruchamia 3-etapowy proces wyrażania zgody OAuth (3LO), aby bezpiecznie wysyłać zapytania do narzędzi przy użyciu danych logowania użytkownika.

Architektura podwójnej tożsamości

Aby to zrobić, dowiesz się, jak:

  1. Utwórz agenta ADK, który łączy się z serwerem Model Context Protocol (MCP) GitHuba.
  2. Zaktualizuj narzędzie agenta ze statycznego osobistego tokena dostępu (PAT) GitHuba do przepływu trzyetapowej autoryzacji OAuth (3LO) za pomocą Google Cloud Auth Managera.
  3. Bezpiecznie wdróż agenta w Agent Runtime i udostępnij Agent Identity.
  4. Skonfiguruj role uprawnień, aby zapewnić tożsamości agenta dostęp do magazynu tokenów w imieniu użytkownika.
  5. Poznaj kompleksowy proces 3LO dla menedżera uwierzytelniania w Google Cloud.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz:

  • projekt Google Cloud z włączonymi płatnościami,
  • Pakiet Google Cloud SDK (gcloud CLI) zainstalowany i uwierzytelniony w projekcie na komputerze lokalnym. Wymagana jest wersja 586.0.0 lub nowsza – uruchom gcloud components update.
  • Python w wersji od 3.10 do 3.13 zainstalowany lokalnie.
  • Zainstalowany system zarządzania pakietami uv (pip install uv).
  • konto GitHub, aby zarejestrować aplikację OAuth i utworzyć tokeny; Jeśli nie masz konta GitHub, możesz użyć dowolnego serwera MCP innej firmy, który obsługuje trzyskładnikowe uwierzytelnianie OAuth 2.0.

2. Konfiguracja projektu

1. Uwierzytelnianie w Google Cloud

Uwierzytelnij się w Google Cloud z lokalnego wiersza poleceń, aby upewnić się, że Twoje środowisko ma uprawnienia niezbędne do wdrożenia w Agent Runtime, udostępnienia tożsamości agenta i skonfigurowania menedżera uwierzytelniania podczas tego modułu.

Uruchom te polecenia, aby zalogować się na konto Google Cloud, ustawić aktywny projekt (zastąp YOUR_PROJECT_ID identyfikatorem projektu Google Cloud) i skonfigurować domyślne uwierzytelnianie aplikacji (ADC):

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

2. Włączanie wymaganych usług Google Cloud

Włącz w projekcie Google Cloud interfejsy API niezbędne do wykonania tego modułu. Uruchom w terminalu to polecenie:

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

Wykonanie tego polecenia może potrwać minutę. Po zakończeniu powrócisz do znaku zachęty, co potwierdzi, że interfejsy API są aktywne.

3. Zainstaluj interfejs wiersza poleceń agentów i skonfiguruj projekt

agents-cli to narzędzie wiersza poleceń używane do tworzenia, zarządzania, testowania i wdrażania agentów ADK w Gemini Enterprise. Zainstaluj go lokalnie:

uvx google-agents-cli setup

Sprawdź instalację:

agents-cli --help

Powinno pojawić się menu pomocy interfejsu wiersza poleceń z dostępnymi poleceniami (takimi jak deploy, run i status).

wygenerować początkową strukturę projektu, Zaczniesz od lokalnego prototypu, który później ulepszysz na potrzeby wdrożenia w środowisku wykonawczym Agent Runtime:

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

Spowoduje to utworzenie katalogu secure-agent-demo zawierającego podstawowy kod agenta, zależności i pliki testowe.

4. Dodawanie wymaganych dodatków ADK

Dodaj 2 brakujące dodatki w wygenerowanym pliku pyproject.toml: mcp dla zestawu narzędzi GitHub i agent-identity dla menedżera uwierzytelniania, który zostanie użyty w dalszej części modułu. Otwórz secure-agent-demo/pyproject.toml i zastąp całą sekcję

google-adk

dependency line with:

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

Następnie zainstaluj:

cd secure-agent-demo
agents-cli install

3. Tworzenie i testowanie agenta

1. Tworzenie agenta

W projekcie zastąp kod w pliku secure-agent-demo/app/agent.py tym kodem:

# 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",
)

Ten plik definiuje 3 kluczowe komponenty agenta:

  • Instrukcja systemowa (INSTRUCTION): ustawia personę, ogranicza zakres asystenta do klasyfikacji na GitHubie i wymusza rygorystyczne zasady bezpieczeństwa (takie jak dostęp tylko do odczytu i kierowanie użytkowników do uwierzytelniania w przypadku wystąpienia błędów).
  • Konfiguracja agenta (root_agent): tworzy instancję ADK Agent za pomocą modelu gemini-3.8-flash, konfiguruje logikę ponawiania prób HTTP i wyposaża agenta w zestaw narzędzi GitHub.
  • App Wrapper (app): umieszcza agenta głównego w kontenerze ADK App, dzięki czemu można go wdrożyć w środowisku wykonawczym agenta.

2. Dodawanie narzędzia MCP GitHub

Agent łączy się z GitHubem za pomocą protokołu Model Context Protocol (MCP). Utwórz nowy plik w secure-agent-demo/app/tools.py, aby zarejestrować parametry połączenia bramy MCP. Skopiuj i wklej ten kod:

# 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",
            },
        )
    )

Ta funkcja tworzy narzędzie, które wywołuje serwer MCP GitHuba:

  • Zestaw narzędzi MCP (McpToolset): dynamicznie wykrywa i rejestruje funkcje GitHuba jako wywoływalne narzędzia agenta.
  • Connection Parameters (StreamableHTTPConnectionParams): wskazuje zestawowi narzędzi publiczną bramę MCP GitHuba.
  • Nagłówki autoryzacji: wstrzykuje GITHUB_TOKEN jako token okaziciela i wymusza tryb „tylko do odczytu” (X-MCP-Readonly: true) bezpośrednio w warstwie transportowej.

3. Testowanie lokalne za pomocą osobistego tokena dostępu (PAT) z GitHuba

Aby uruchomić agenta lokalnie ze statycznymi danymi logowania:

  1. Utwórz szczegółowy osobisty token dostępu na stronie Osobiste tokeny dostępu na GitHubie:
    • Kliknij Generate new token (Wygeneruj nowy token) i nadaj tokenowi nazwę.
    • W sekcji Dostęp do repozytorium wybierz Wszystkie repozytoria (lub wybierz konkretne repozytoria, które chcesz przetestować).
    • W sekcji Uprawnienia > Repozytoria kliknij +Dodaj uprawnienia i wybierz Treści, Problemy i Żądania pull, aby ustawić je jako Tylko do odczytu (Metadane są automatycznie ustawiane jako Tylko do odczytu).
    • Kliknij Wygeneruj token i skopiuj wygenerowaną wartość tokena. (Jeśli używasz osobistego tokena dostępu (klasycznego), wybierz zakres repo).
  2. Ustaw ją w środowisku:
    export GITHUB_TOKEN="your_github_pat_here"
    
  3. Przejdź do folderu secure-agent-demo (jeśli jeszcze w nim nie jesteś) i uruchom lokalne środowisko testowe:
    cd secure-agent-demo
    agents-cli playground
    
  4. Otwórz interfejs środowiska testowego i wybierz folder app z menu. W polu czatu wpisz prompta, np. "Get the last 2 GitHub issues reported against my name" lub "List my 3 most recently updated repositories", i sprawdź, czy agent wywołuje zestaw narzędzi MCP GitHuba i zwraca dane z GitHuba. Aby sprawdzić, czy agent faktycznie używa Twojego tokena PAT do podejmowania działań w Twoim imieniu, zapytaj go o Twoje prywatne repozytoria lub wkłady.

4. Konfigurowanie menedżera uwierzytelniania

Chociaż kodowanie na stałe statycznych danych logowania (takich jak PAT) jest wygodne podczas tworzenia prototypów, naraża aplikacje produkcyjne na wyciek danych logowania, przestoje związane z ręcznym odświeżaniem tokenów i brak kontroli dostępu w chmurze.

Aby rozwiązać ten problem, Google Cloud udostępnia Menedżera uwierzytelniania tożsamości agentów. Menedżer uwierzytelniania tożsamości agentów to magazyn danych logowania, który pomaga chronić te dane. Umożliwia agentom uwierzytelnianie za pomocą klucza interfejsu API lub identyfikatora klienta OAuth i tajnego klucza klienta albo w imieniu użytkownika przez przekazywanie dostępu OAuth za pomocą tokenów dostępu użytkownika.

W Menedżerze uwierzytelniania konfigurujesz dostawców uwierzytelniania, którzy definiują typ uwierzytelniania i dane logowania dla konkretnych aplikacji innych firm. Dostawcy uwierzytelniania są regionalni, a region musi być zgodny z regionem, w którym wdrażasz agenta. Kompleksowy przepływ pracy menedżera uwierzytelniania działa w ten sposób:

Przepływ pracy menedżera uwierzytelniania

  1. Dynamiczne przechwytywanie zgody: gdy agent próbuje wykonać narzędzie w imieniu użytkownika, ADK sprawdza, czy w menedżerze uwierzytelniania są prawidłowe dane logowania. Jeśli nie ma żadnego, Auth Manager zwraca adres URL autoryzacji, aby zainicjować proces wyrażania zgody OAuth z 3 stronami (3LO).
  2. Bezpieczne przechowywanie w magazynie: gdy użytkownik autoryzuje aplikację, menedżer uwierzytelniania automatycznie przechwytuje wywołanie zwrotne protokołu OAuth i zapisuje uzyskane tokeny dostępu i tokeny odświeżania użytkownika w bezpiecznym magazynie danych logowania zarządzanym przez Google.
  3. Automatyczny cykl życia tokena: Auth Manager w pełni zarządza wygasaniem i rotacją tokenów w tle, eliminując potrzebę ręcznego odświeżania tokenów i przestoje.
  4. Wykonywanie narzędzi bez obiektów tajnych: w przypadku kolejnych działań agent (uwierzytelniający się za pomocą tożsamości agenta SPIFFE) dynamicznie żąda od menedżera uwierzytelniania tokena dostępu przekazanego użytkownikowi w czasie działania, dzięki czemu zarówno kod klienta, jak i kod agenta są całkowicie pozbawione obiektów tajnych.

Krok A. Skonfiguruj GitHuba jako dostawcę uwierzytelniania

Uruchom to polecenie gcloud, aby utworzyć dostawcę uwierzytelniania GitHub w projekcie Google Cloud. Identyfikator klienta i tajny klucz klienta podasz później: GitHub nie wyda ich, dopóki nie pozna adresu URL wywołania zwrotnego tego dostawcy.

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"

Opisz dostawcę, aby pobrać wygenerowany adres URL przekierowania OAuth:

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

Pole to redirectUrl, zagnieżdżone w authProviderTypeParams.threeLeggedOauth. Aby przeczytać ją bezpośrednio:

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

Wygląda na to, że https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Krok B. Zarejestruj aplikację OAuth w GitHubie

  1. Otwórz stronę ustawień dewelopera GitHub, na pasku bocznym po lewej stronie wybierz OAuth Apps (Aplikacje OAuth) i kliknij New OAuth App (Nowa aplikacja OAuth) lub Register a new application (Zarejestruj nową aplikację), jeśli nie masz jeszcze utworzonej aplikacji.
  2. Wypełnij pola formularza aplikacji OAuth:
    • Nazwa aplikacji: wpisz nazwę aplikacji (np. secure-agent-demo).
    • Adres URL strony głównej: wpisz adres URL aplikacji frontendowej (http://localhost:8501 w przypadku lokalnego prototypowania; możesz go zaktualizować do adresu URL wdrożonego w środowisku produkcyjnym).
    • Application description (Opis aplikacji): opcjonalnie (możesz pozostawić to pole puste).
    • Authorization callback URL (Adres URL wywołania zwrotnego autoryzacji, identyfikator URI przekierowania): wklej redirectUrl pobrany w kroku A.
    • Enable Device Flow (Włącz przepływ urządzenia): pozostaw niezaznaczone.
  3. Kliknij Register application (Zarejestruj aplikację).
  4. Na stronie aplikacji skopiuj identyfikator klienta, a następnie kliknij Wygeneruj nowy tajny klucz klienta i skopiuj wygenerowany tajny klucz klienta. Zapisz obie wartości – w następnym kroku użyjesz ich jako YOUR_GITHUB_CLIENT_ID i YOUR_GITHUB_CLIENT_SECRET.

Krok C. Dodaj dane logowania GitHub do dostawcy uwierzytelniania

Zastąp parametry YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID i YOUR_GITHUB_CLIENT_SECRET swoimi wartościami i uruchom to polecenie:

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"

Polecenie wyświetla dostawcę z widocznym clientId. Tajny klucz nie jest wyświetlany.

👉 Po wykonaniu tego kroku menedżer uwierzytelniania Google Cloud jest teraz w pełni skonfigurowany z danymi logowania aplikacji OAuth na GitHubie, co pozwala Google Cloud działać jako bezpieczny magazyn, który obsługuje cykle życia zgody i tokenów.

5. Przełączanie tokena PAT na Menedżera uwierzytelniania

Po pełnym skonfigurowaniu menedżera uwierzytelniania następnym krokiem jest zaktualizowanie kodu narzędzia agenta. Zastąp zawartość pliku secure-agent-demo/app/tools.py tym kodem.

👉 Zastąp identyfikator projektu i lokalizację w zmiennej OAUTH_PROVIDER_NAME poniżej.

# 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,
    )

Zrozumienie kodu narzędzia

Kluczowa zmiana to auth_scheme. Dołączenie go do zestawu narzędzi oznacza, że za każdym razem, gdy agent wywołuje GitHuba, ADK najpierw prosi menedżera uwierzytelniania o token tego użytkownika. Jeśli token nie istnieje, ADK prosi użytkownika o zalogowanie się, zamiast zgłaszać błąd. Kodowany na stałe element GITHUB_TOKEN został całkowicie usunięty.

6. Wdrażanie agenta w Agent Runtime

Zaktualizowaliśmy narzędzie MCP GitHuba, aby używało menedżera uwierzytelniania. Następnym krokiem jest wdrożenie agenta w Agent Runtime. Wdrożenie go z włączoną tożsamością agenta powoduje udostępnienie unikalnego identyfikatora SPIFFE dla agenta.

Zainicjuj konfigurację wdrożenia dla projektu. Upewnij się, że terminal znajduje się w katalogu głównym projektu secure-agent-demo, a następnie uruchom:

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

To polecenie sprawdza strukturę projektu pod kątem zgodności z ADK, przygotowuje konfiguracje pakowania kontenerów i generuje plik agents-cli-manifest.yaml w katalogu głównym projektu, który jest wstępnie wypełniony domyślnymi ustawieniami wdrażania.

👉 Otwórz nowo utworzony plik agents-cli-manifest.yaml i sprawdź lub zaktualizuj pole region, ustawiając wartość us-central1, aby mieć pewność, że agent zostanie wdrożony w tym samym regionie co dostawca uwierzytelniania:

region: "us-central1"

Wdrażanie agenta z tożsamością agenta

Wdróż za pomocą adk deploy agent_engine. Zapewnia to agentowi własną tożsamość agenta – unikalną, opartą na SPIFFE tożsamość kryptograficzną należącą do tego wdrożenia, której agent używa do uwierzytelniania w menedżerze uwierzytelniania i innych usługach Google Cloud.

👉 W katalogu secure-agent-demo zastąp YOUR_PROJECT_ID i uruchom te polecenia:

# 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"

Wdrażanie, czyli utworzenie i przesłanie kontenera, może potrwać kilka minut. Po zakończeniu interfejs wiersza poleceń wyświetli nazwę wdrożonego zasobu. Zanotuj wartość reasoningEngines/ENGINE_ID, ponieważ będzie ona potrzebna do autoryzacji agenta i wskazania go klientowi UI.

Autoryzowanie tożsamości agenta

Teraz, gdy agent działa w chmurze, potrzebuje uprawnień dostępu do danych logowania przechowywanych w usłudze Auth Manager. Domyślnie tożsamość SPIFFE agenta nie ma dostępu do zewnętrznych zasobów w chmurze.

Uruchom to polecenie gcloud, aby przyznać rolę roles/agentidentity.user tożsamości agenta w zasobie dostawcy uwierzytelniania. Dzięki temu agent otrzyma dokładnie te uprawnienia, których potrzebuje do żądania tokenów użytkownika z magazynu, i nic więcej.

# 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)"

Następnie powiąż uprawnienia z dostawcą uwierzytelniania (zastępując YOUR_PROJECT_ID i podmiot zabezpieczeń --member):

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"

👉 Pełną wartość --member="principal://..." wdrożonego agenta możesz też uzyskać w konsoli Google Cloud: otwórz konsolę Agent Runtime, wybierz wdrożonego agenta, otwórz kartę Tożsamość i skopiuj cały ciąg znaków principal://....

Teraz przypisz swojemu kontu tę samą rolę u dostawcy. Klient UI, którego uruchomisz w następnym kroku, wywołuje interfejs API finalizacji danych logowania za pomocą domyślnego uwierzytelniania aplikacji, więc bez tego proces uzyskiwania zgody nie powiedzie się i zwróci błąd 403 w agentidentity.authProviders.retrieveCredentials:

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. Proces uzyskiwania zgody w ramach autoryzacji 3LO

Agent został wdrożony w środowisku wykonawczym agentów z bezpieczną tożsamością agenta. Następnym krokiem jest udostępnienie użytkownikom niestandardowego interfejsu frontendu, który umożliwi im czatowanie z agentem. Co ważniejsze, Google Cloud Auth Manager wymaga modułu obsługi wywołania zwrotnego aplikacji klienckiej, aby zakończyć pętlę uwierzytelniania.

Chociaż Google Cloud Auth Manager bezpiecznie zarządza danymi logowania użytkowników w magazynie, nie może samodzielnie sfinalizować wymiany tokenów OAuth. Uzgadnianie połączenia 3LO polega na tym, że aplikacja kliencka wypełnia lukę:

  1. Gdy użytkownik autoryzuje aplikację GitHub, GitHub przekierowuje go z powrotem do redirectUrl dostawcy uwierzytelniania tożsamości agenta .
  2. Następnie Menedżer uwierzytelniania przekierowuje wyskakujące okienko przeglądarki użytkownika z powrotem do adresu URL wywołania zwrotnego po stronie klienta (continue_uri).
  3. Aplikacja kliencka musi przechwycić to przekierowanie, odczytać liczbę jednorazową z plików cookie przeglądarki i wywołać punkt końcowy credentials:finalize Google Cloud, aby zakończyć uzgadnianie.
  4. Gdy klient sfinalizuje wymianę, Google Cloud bezpiecznie zapisze token w magazynie dostawcy uwierzytelniania, co umożliwi agentowi wywołanie narzędzia GitHub.

Bez tego niestandardowego klienta hostującego punkt końcowy wywołania zwrotnego uzgadnianie pozostaje niekompletne, a magazyn nie może przechowywać danych logowania.

Interaktywny proces OAuth 3LO obejmuje wiele warstw. Oto pełny cykl życia żądania narzędzia. Wyjaśnimy to poniżej i w następnym kroku.

👉 Kliknij obraz, aby go powiększyć.

Przepływ sekwencji 3-etapowego protokołu OAuth

Główne obowiązki klienta w ramach uzgadniania

  • Przekazywanie prośby o zgodę (kroki 5–6): agent wysyła zdarzenie adk_request_credential zawierające adres URL zgody i jednorazową liczbę. Klient otwiera wyskakujące okienko i zapisuje liczbę jednorazową jako plik cookie.
  • Hostowanie wywołania zwrotnego przekierowania (kroki 10–11): /validateUserId, gdzie Auth Manager wysyła wyskakujące okienko po wyrażeniu zgody.
  • Finalizowanie tokena (kroki 12–14): połącz stan weryfikacji z przekierowania z liczbą jednorazową z pamięci podręcznej i wywołaj credentials:finalize, co spowoduje zapisanie tokena w skarbcu.

Tworzenie własnego klienta

Nie musisz pisać tego klienta na potrzeby modułu – w następnym kroku uruchomisz gotowy program. Jeśli chcesz wdrożyć to rozwiązanie we własnej aplikacji, możesz skorzystać z tych 2 materiałów referencyjnych:

8. Lokalne uruchamianie klienta UI

Jak pokazano na diagramie sekwencji procesu uzyskiwania zgody 3LO, menedżer uwierzytelniania przekierowuje okno przeglądarki z powrotem do punktu końcowego wywołania zwrotnego po stronie klienta. Przykładowy klient w repozytorium adk-python hostuje ten punkt końcowy pod adresem /validateUserId. Pobierz i uruchom go lokalnie, wykonując te czynności.

Pobieranie plików klienta

Katalog contributing/samples/integrations/gcp_auth/client w adk-python zawiera 3 kluczowe zasoby:

  • main.py: backend FastAPI, który łączy się z wdrożonym Agent Engine i hostuje punkt końcowy wywołania zwrotnego /validateUserId, aby sfinalizować tokeny OAuth.
  • static/: pliki HTML i JavaScript interfejsu czatu w przeglądarce.
  • requirements.txt: pakiety Pythona wymagane do uruchomienia serwera klienta.

adk-python to duże repozytorium, dlatego użyj funkcji sparse checkout w Git, aby pobrać tylko folder contributing/samples/integrations/gcp_auth/client:

  1. Najpierw przejdź o jeden katalog wyżej niż secure-agent-demo, aby sklonować klienta do folderu nadrzędnego:
    cd ..
    
  2. Uruchom te polecenia, aby sklonować metadane repozytorium bez pobierania wszystkich plików (--no-checkout), ograniczyć ścieżkę do contributing/samples/integrations/gcp_auth/client i pobrać tylko ten folder:
    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
    

Uruchamianie klienta

  1. W katalogu adk-python, do którego właśnie wszedłeś, przejdź do folderu client:
    cd contributing/samples/integrations/gcp_auth/client
    
  2. Utwórz i aktywuj środowisko wirtualne Pythona, a następnie zainstaluj zależności klienta z pliku requirements.txt:
    uv venv --python 3.13 .venv
    source .venv/bin/activate
    uv pip install --python .venv/bin/python -r requirements.txt
    
  3. Ustaw zmienne środowiskowe wskazujące klienta na projekt w chmurze Google Cloud, region (us-central1) i wdrożony identyfikator silnika agenta (YOUR_ENGINE_ID), a następnie uruchom lokalny serwer FastAPI na porcie 8501:
    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. Sprawdź, czy serwer został uruchomiony i nasłuchuje na porcie http://localhost:8501.

9. Testowanie procesu OAuth

Wszystkie usługi są wdrożone, powiązania uprawnień skonfigurowane, a zmienne środowiskowe ustawione. Możesz teraz przetestować bezpieczny, kompleksowy proces autoryzacji delegowanej przez użytkownika.

Krok A. Rozpocznij działanie narzędzia

  1. Otwórz kartę przeglądarki i przejdź na adres URL klienta: http://localhost:8501.
  2. W panelu po lewej stronie w sekcji Ustawienia konfiguracji ustaw Typ agenta na Remote Agent (Vertex AI) (lub Remote Agent Engine).
  3. Wpisz identyfikator projektu i lokalizację (us-central1) w Google Cloud, a następnie kliknij Wczytaj zdalnych agentów. Spowoduje to wczytanie agentów wdrożonych w projekcie.
  4. Wybierz wdrożonego agenta app z menu Wybierz silnik i kliknij Zapisz i zastosuj ustawienia.
  5. W polu czatu wpisz zapytanie ukierunkowane (np. dotyczące pobierania ostatnich problemów lub repozytoriów):
    Get the last 2 GitHub issues reported against my name
    
    (lub "List my 3 most recently updated repositories") i naciśnij Enter.
  6. Obserwuj interfejs czatu: ponieważ agent nie ma jeszcze danych logowania do sesji użytkownika, otrzymuje wyzwanie uwierzytelniania i wyświetla kartę Wymagane uwierzytelnianie w wątku rozmowy.
  1. Otworzy się osobne wyskakujące okienko przeglądarki, które przekieruje Cię przez menedżera uwierzytelniania Google Cloud na stronę autoryzacji OAuth GitHuba.
  2. Sprawdź wymagane uprawnienia i kliknij Autoryzuj.
  3. GitHub przekieruje z powrotem do Google Cloud, które przekieruje wyskakujące okienko na Twój adres URL wywołania zwrotnego localhost /validateUserId.
  4. Usługa wywołania zwrotnego przetwarza i finalizuje uzgadnianie danych logowania.

Krok C. Wznów

  1. Gdy wyskakujące okienko zostanie zamknięte, karta czatu nadrzędnego automatycznie wykryje zamknięcie.
  2. Frontend wysyła do agenta ładunek wznowienia.
  3. Agent bezpiecznie pobiera nowo wymieniony token z Google Cloud Auth Managera, wywołuje narzędzia GitHub MCP w Twoim imieniu i przesyła dane z GitHuba bezpośrednio do okna czatu – dane, do których agent nie mógłby dotrzeć samodzielnie.

Krok D. Sprawdź logi Cloud

Aby sprawdzić, czy wymiana tokenów i finalizacja zostały przetworzone w bezpieczny sposób:

  1. Otwórz Eksplorator logów w konsoli Google Cloud.
  2. Znajdź logi serwera potwierdzające wyodrębnienie liczby jednorazowej i pomyślną weryfikację:
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
    INFO:secure-agent-client:Successfully finalized auth provider credentials.
    
  3. Sprawdzanie logów Agent Runtime: możesz też wyświetlić logi wykonywania bezpośrednio w konsoli Agent Platform:
    • Otwórz konsolę Agent Runtime.
    • Kliknij na liście wdrożonego agenta.
    • Przejdź na kartę Playground. W dolnym panelu wyświetlą się logi działań agenta na żywo, pokazujące w czasie rzeczywistym pętlę rozumowania agenta, szczegóły wykonywania narzędzia i cykl życia pobierania tokena.

10. Czyszczenie

Aby uniknąć bieżących opłat w Google Cloud, wyczyść wdrożone zasoby:

# 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

Usuwanie plików lokalnych

Opcjonalnie, aby całkowicie wyczyścić środowisko lokalne:

  1. Zatrzymaj lokalny serwer uvicorn, naciskając Ctrl+C w terminalu, w którym jest uruchomiony.
  2. Usuń katalogi projektu utworzone podczas tego modułu:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. Gratulacje!

Udało Ci się utworzyć i zabezpieczyć agenta, który działa w imieniu zalogowanego użytkownika.

Czego się nauczysz:

  • Tożsamość systemowa agenta: sposób, w jaki agent działa w ramach własnej tożsamości konta, aby bezpiecznie komunikować się z infrastrukturą GCP, zarządzać dziennikami telemetrycznymi i wywoływać interfejsy API finalizacji danych logowania.
  • Tożsamość przekazana przez użytkownika: sposób, w jaki agent prosi o autoryzację do działania w imieniu użytkownika na platformach zewnętrznych (takich jak GitHub) przez uruchomienie procesu uzyskiwania zgody OAuth z 3 stronami (3LO).
  • Bezpieczna integracja narzędzi: jak połączyć agenty ADK z serwerami Model Context Protocol (MCP) za pomocą Google Cloud Auth Managera, aby dynamicznie pobierać tokeny użytkowników zamiast używać obiektów tajnych zakodowanych na stałe.
  • Konfiguracja zasad uprawnień: jak skonfigurować szczegółowe powiązania uprawnień, aby autoryzować zarówno tożsamość Agent Runtime, jak i własne konto u dostawcy uwierzytelniania.

Więcej informacji