Dapatkan token akses OAuth 2.0

AgentCore Identitas memungkinkan pengembang untuk mendapatkan token OAuth untuk akses yang didelegasikan pengguna atau otentikasi mesin-ke-mesin berdasarkan penyedia kredensi OAuth 2.0 yang dikonfigurasi. Layanan akan mengatur proses otentikasi antara pengguna atau aplikasi ke server otorisasi hilir, dan itu 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, contoh kode di bawah ini akan mengambil token untuk berinteraksi dengan Google Drive atas nama pengguna akhir. Untuk informasi selengkapnya, lihat Mengintegrasikan 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 alur kode otorisasi OAuth2 standar, sistem menyimpan token akses dan token penyegaran (jika disediakan) di brankas token aman. Ini memungkinkan agen untuk mendapatkan token akses baru secara otomatis ketika token asli kedaluwarsa, meningkatkan pengalaman pengguna dengan meminimalkan permintaan persetujuan berulang.

Token penyegaran biasanya memiliki rentang hidup yang lebih lama daripada token akses, dengan periode validitas default sekitar 30 hari dibandingkan dengan masa pakai 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 lewati 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, secara otomatis AgentCore akan menyimpan dan mengelolanya tanpa pengaturan tambahan. Untuk menghapus token penyegaran yang tersimpan dan memaksa pengguna untuk mengautentikasi ulang, atur forceAuthentication=true saat memanggil. GetResourceOauth2Token Ini membersihkan token penyegaran dan memaksa aliran federasi lengkap. Untuk informasi tentang mengonfigurasi penyedia OAuth2, lihat Penyiapan dan konfigurasi penyedia.

URL otorisasi streaming ke penelepon aplikasi

Untuk alur OAuth (3LO) berkaki tiga, 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 pemanggil 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 callback — Untuk aplikasi yang menggunakan callback atau webhook, simpan URL otorisasi dan beri tahu pemanggil:

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 waktu nyata, 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 dimaksud selama permintaan token. Untuk menggunakan indikator sumber daya, Anda harus terlebih dahulu mengonfigurasi server otorisasi untuk mengenali server sumber daya tertentu menggunakan API Cognito. CreateResourceServer Setelah dikonfigurasi, saat Anda menentukan indikator sumber daya dalam permintaan token Anda, Cognito menyertakan pengidentifikasi 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 paling sedikit), peningkatan auditabilitas dengan mengidentifikasi dengan 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 otorisasi dan permintaan token, mengesampingkan parameter audiens default. Dalam Cognito, 'indikator sumber daya' yang disebut dalam RFC sesuai dengan nilai ResourceServer 'pengenal'. 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, artinya 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 yang baik atas validasi pemirsa token. Indikator sumber daya sangat berguna untuk aplikasi multi-penyewa di mana token harus dibatasi pada sumber daya pelanggan tertentu.