Dapatkan token akses OAuth 2.0

AgentCore Identitas memungkinkan pengembang memperoleh token OAuth baik untuk akses yang didelegasikan pengguna atau otentikasi mesin-ke-mesin berdasarkan penyedia kredensia OAuth 2.0 yang dikonfigurasi. Layanan akan mengatur proses otentikasi antara pengguna atau aplikasi ke server otorisasi hilir, dan akan mengambil dan menyimpan token yang dihasilkan. Setelah token tersedia di brankas AgentCore Identity, agen resmi dapat mengambilnya dan menggunakannya untuk mengotorisasi panggilan ke server sumber daya. Misalnya, kode sampel di bawah ini akan mengambil token untuk berinteraksi dengan Google Drive atas nama pengguna akhir. Untuk informasi selengkapnya, lihat Meng integrasikan dengan Google Drive menggunakan OAuth2 untuk contoh lengkapnya.

# Injects Google Access Token
@requires_access_token(
    # Uses the same credential provider name created above
    provider_name= "google-provider",
    # Requires Google OAuth2 scope to access Google Drive
    scopes= ["https://www.googleapis.com/auth/drive.metadata.readonly"],
    # Sets to OAuth 2.0 Authorization Code flow
    auth_flow= "USER_FEDERATION",
    # Prints authorization URL to console
    on_auth_url= lambda x: print("\nPlease copy and paste this URL in your browser:\n" + x),
    # If false, caches obtained access token
    force_authentication= False,
    callback_url='insert_oauth2_callback_url_for_session_binding',
)
async def write_to_google_drive(*, access_token: str):
    # Use the token to call Google Drive
    pass

# To invoke:
# asyncio.run(write_to_google_drive())

Prosesnya mirip dengan mendapatkan token untuk panggilan mesin-ke-mesin, seperti yang ditunjukkan pada contoh berikut:

import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key

@requires_access_token(
    provider_name= "my-api-key-provider", # replace with your own credential provider name
    scopes= [],
    auth_flow= 'M2M',
)
async def need_token_2LO_async(*, access_token: str):
    # Use the access token
    pass

# To invoke:
# asyncio.run(need_token_2LO_async())

Penyimpanan dan penggunaan token penyegaran otomatis

AgentCore secara otomatis menyimpan dan menggunakan token penyegaran bila tersedia dari penyedia OAuth2, mengurangi frekuensi permintaan otorisasi ulang pengguna. Ketika pengguna awalnya memberikan persetujuan melalui aliran kode otorisasi OAuth2 standar, sistem menyimpan token akses dan token penyegaran (jika disediakan) di brankas token aman. Hal ini memungkinkan agen untuk mendapatkan token akses baru secara otomatis ketika token asli kedaluwarsa, meningkatkan pengalaman pengguna dengan meminimalkan permintaan persetujuan berulang.

Token refresh biasanya memiliki rentang hidup yang lebih lama daripada token akses, dengan periode validitas default sekitar 30 hari dibandingkan dengan umur token akses yang lebih pendek (seringkali 1-2 jam). Ketika token akses kedaluwarsa, AgentCore secara otomatis menggunakan token penyegaran yang disimpan untuk meminta token akses baru dari penyedia. Jika token penyegaran yang valid disimpan, AgentCore melewatkan alur federasi pengguna dan langsung mengembalikan token akses baru. Jika token penyegaran juga kedaluwarsa atau tidak valid, sistem akan kembali meminta pengguna untuk otorisasi ulang penuh.

Fitur ini tidak memerlukan konfigurasi di dalamnya AgentCore - ini beroperasi secara otomatis ketika token penyegaran hadir dalam respons token penyedia OAuth2. Namun, Anda harus mengonfigurasi penyedia OAuth2 Anda untuk menyertakan token penyegaran dalam alur otorisasi. Konfigurasi spesifik tergantung pada penyedia Anda:

"customParameters": { "access_type": "offline" }

"scopes": ["openid", "profile", "offline_access"]

"scopes": ["api", "refresh_token"]

"scopes": ["read:jira-user", "offline_access"]

Jika penyedia Anda mendukung token penyegaran dan dikonfigurasi dengan benar, AgentCore akan secara otomatis menyimpan dan mengelolanya tanpa pengaturan tambahan. Untuk menghapus token penyegaran yang tersimpan dan memaksa pengguna untuk melakukan autentikasi ulang, atur forceAuthentication=true saat menelepon. GetResourceOauth2Token Ini menghapus token penyegaran dan memaksa aliran federasi lengkap. Untuk informasi tentang mengonfigurasi penyedia OAuth2, lihat Pengaturan dan konfigurasi penyedia.

Streaming URL otorisasi ke pemanggil aplikasi

Untuk aliran OAuth (3LO) tiga kaki, agen Anda perlu memberikan URL otorisasi ke aplikasi panggilan sehingga pengguna dapat menyelesaikan alur persetujuan. Sementara contoh di atas menunjukkan pencetakan URL ke konsol, aplikasi produksi memerlukan streaming URL kembali ke penelepon melalui mekanisme respons aplikasi Anda.

Pola implementasi umum

Pola respons streaming — Untuk aplikasi yang mendukung respons streaming, Anda dapat mengirim URL otorisasi sebagai bagian dari aliran respons:

import asyncio
from bedrock_agentcore.identity.auth import requires_access_token

@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    auth_flow="USER_FEDERATION",
    # Stream URL back to caller instead of printing
    on_auth_url=lambda url: stream_to_caller({
        "type": "authorization_required",
        "authorization_url": url,
        "message": "Please visit this URL to authorize access"
    }),
    force_authentication=False,
    callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def agent_with_streaming_auth(*, access_token: str):
    # Agent logic continues after user completes authorization
    return {"status": "success", "token_received": True}

def stream_to_caller(data):
    # Implementation depends on your streaming mechanism
    # Examples: WebSocket, Server-Sent Events, HTTP chunked response
    response_stream.send(json.dumps(data))

Pola panggilan balik — Untuk aplikasi yang menggunakan callback atau webhook, simpan URL otorisasi dan beri tahu penelepon:

import asyncio
from bedrock_agentcore.identity.auth import requires_access_token

@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    auth_flow="USER_FEDERATION",
    # Store URL and trigger callback
    on_auth_url=lambda url: handle_auth_callback(url),
    force_authentication=False,
    callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def agent_with_callback_auth(*, access_token: str):
    return {"status": "success", "data": "processed"}

def handle_auth_callback(authorization_url):
    # Store the URL associated with the request
    auth_store.save(request_id, {
        "authorization_url": authorization_url,
        "status": "pending_authorization"
    })

    # Notify the calling application
    callback_service.notify(callback_url, {
        "request_id": request_id,
        "authorization_url": authorization_url,
        "action_required": "user_authorization"
    })

Pola polling — Untuk aplikasi yang lebih suka polling, simpan URL otorisasi di lokasi yang dapat diambil:

import asyncio
from bedrock_agentcore.identity.auth import requires_access_token

@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    auth_flow="USER_FEDERATION",
    # Store URL for polling retrieval
    on_auth_url=lambda url: store_auth_url_for_polling(url),
    force_authentication=False,
    callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def agent_with_polling_auth(*, access_token: str):
    return {"status": "success", "data": "processed"}

def store_auth_url_for_polling(authorization_url):
    # Store in database, cache, or session store
    session_store.set(f"auth_url:{session_id}", {
        "authorization_url": authorization_url,
        "created_at": datetime.utcnow(),
        "status": "pending"
    }, ttl=300)  # 5 minute expiration

Pilih pola yang paling sesuai dengan arsitektur aplikasi Anda. Respons streaming memberikan pengalaman pengguna terbaik untuk aplikasi real-time, sementara pola panggilan balik dan polling bekerja dengan baik untuk skenario pemrosesan asinkron atau batch.

Indikator sumber daya dalam aliran AgentCore OAuth2

Indikator sumber daya menyediakan cara standar untuk menentukan server sumber daya mana yang harus menerima token akses OAuth2. AgentCore menggunakan Cognito sebagai penyedia otentikasi, yang mendukung indikator sumber daya yang sesuai dengan RFC 8707 yang memungkinkan Anda menentukan server sumber daya yang dituju selama permintaan token. Untuk menggunakan indikator sumber daya, Anda harus terlebih dahulu mengonfigurasi server otorisasi untuk mengenali server sumber daya tertentu menggunakan CreateResourceServer API Cognito. Setelah dikonfigurasi, saat Anda menentukan indikator sumber daya dalam permintaan token Anda, Cognito menyertakan pengenal server sumber daya yang sesuai dalam klaim aud dari token yang dihasilkan, memungkinkan server sumber daya memverifikasi bahwa token dimaksudkan untuk penggunaan spesifiknya. Ini memberikan beberapa manfaat penting: server sumber daya dapat memvalidasi bahwa token secara khusus ditujukan untuk mereka (prinsip hak istimewa terendah), meningkatkan auditabilitas dengan mengidentifikasi secara jelas server sumber daya mana yang ditargetkan setiap token, dan mengurangi risiko penyalahgunaan token di berbagai layanan dalam lingkungan aplikasi Anda.

Melalui implementasi RFC 8707 Cognito, AgentCore memungkinkan klien untuk menentukan server sumber daya secara langsung dalam permintaan otorisasi dan token, mengesampingkan parameter audiens default. Di Cognito, 'indikator sumber daya' yang dirujuk dalam RFC sesuai dengan nilai 'pengenal ResourceServer '. Indikator sumber daya sangat penting untuk implementasi Model Context Protocol (MCP), di mana mereka membantu mengurangi risiko keamanan spesifik yang diuraikan dalam spesifikasi otorisasi MCP. Indikator sumber daya sesuai dengan parameter sumber daya RFC 9728, memastikan pelingkupan token yang tepat untuk interaksi server MCP. Perhatikan bahwa implementasi saat ini mendukung pengikatan sumber daya tunggal, yang berarti Anda dapat menentukan satu server sumber daya per permintaan token.

Gunakan indikator sumber daya saat agen Anda perlu mengakses server sumber daya dengan persyaratan keamanan tertentu, atau saat Anda memerlukan kontrol menyeluruh atas validasi audiens token. Indikator sumber daya sangat berguna untuk aplikasi multi-tenant di mana token harus dibatasi untuk sumber daya pelanggan tertentu.