OAuth 2.0 授權 URL 工作階段繫結

叫用代理程式 – 當原始代理程式使用者想要存取他/她擁有的一些應用程式或資源時，您的代理程式程式碼會叫用 GetResourceOauth2Token API 來擷取授權 URL。

產生授權 URL – AgentCore Identity 會產生授權 URL 和工作階段 URI，讓使用者導覽至 和同意存取。

授權和取得存取權杖 – 使用者導覽至授權 URL，並授予您的代理程式存取其資源的同意。之後，AgentCore Identity 會使用包含授權請求原始使用者的資訊，將使用者的瀏覽器重新導向至 HTTPS 應用程式端點。此時，您的 HTTPS 應用程式端點會判斷原始代理程式使用者是否仍與目前登入的應用程式使用者相同。如果相符，您的應用程式端點會叫用 ，CompleteResourceTokenAuth以便 AgentCore Identity 可以擷取和存放存取權杖。

重新叫用代理程式以取得存取權杖 – 應用程式傳回有效的回應後，您的代理程式應用程式將能夠擷取最初為使用者請求的 OAuth2.0 存取權杖。如果使用者不相符，您的應用程式只會執行任何動作或記錄嘗試。

建立應用程式 URL – 針對面向使用者的瀏覽器應用程式，建立和託管可從使用者瀏覽器存取的新 URL，並可接受瀏覽器重新導向的請求。此頁面應重新導向至應用程式頁面，您的使用者可以繼續使用其代理程式工作階段，或轉譯一些基本網頁，指示您的使用者傳回其目前作用中的代理程式工作階段。在實作的稍後部分，此頁面用於驗證目前使用者的作用中工作階段，因此此頁面也應該能夠存取和維護您的應用程式使用者工作階段資料。

例如，您的應用程式可能會讓其使用者在 等主要應用程式頁面上與 代理程式互動https://myagentapp.com/assistant。您會想要公開新的 URLhttps://myagentapp.com/callback，例如現在將重新導向至主要應用程式頁面。您/callback端點中的實際程式碼邏輯稍後會在遵循本指南時更新。

使用應用程式 URL 更新工作負載身分 – （如果透過 AgentCore CLI 在本機測試，則可以略過） 一旦您建立並託管要重新導向的 AgentCore Identity 應用程式 URL，請更新您的工作負載身分，以便將應用程式 URL 註冊為 AllowedResourceOauth2ReturnUrl 。請確定使用的 IAM 登入資料具有呼叫 CreateWorkloadIdentity 或 的許可，UpdateWorkloadIdentity取決於您要建立新的工作負載身分或更新現有的工作負載身分。

UpdateWorkloadIdentity API 呼叫範例：

aws bedrock-agentcore-control update-workload-identity --name GoogleCalendarAgent \
--allowed-resource-oauth2-return-urls https://myagentapp.com/callback

在 AgentCore Identity 中建立 OAuth 2.0 登入資料提供者 – 若要完整註冊 OAuth 2.0 登入資料提供者，您需要呼叫 CreateOauth2CredentialProvider和 UpdateOauth2CredentialProvider 的許可。請遵循下列步驟：

新增用於呼叫 CompleteResourceTokenAuth 的程式碼處理常式 – 建立 OAuth 2.0 登入資料提供者後，請新增程式碼和 IAM 許可，以在應用程式 URL 處理常式中呼叫 CompleteResourceTokenAuth API。呼叫 CompleteResourceTokenAuth API 時，您的應用程式必須呈現原始傳入身分提供者 OAuth 權杖或用於產生工作負載存取權杖的user_id字串，以代表 OAuth 2.0 授權流程中涉及的使用者和代理程式應用程式。此資訊應該從使用者瀏覽器上的作用中應用程式工作階段擷取 （通常是透過瀏覽器 Cookie 或瀏覽器本機儲存體），而且不應從任何遠端工作階段快取提取。

此外，AgentCore Identity 產生的每個授權 URL 都會以自己的工作階段 URI 唯一識別。此工作階段 URI 也必須與使用者識別符一起顯示，才能將工作階段與預期使用者繫結。

應用程式程式碼範例：

def _handle_3lo_callback(self, request: Request) -> JSONResponse:
    session_id = request.query_params.get("session_id")

    if not session_id:
        console.print("Missing session_id in OAuth2 3LO callback")
        return JSONResponse(status_code=400, content={"message": "missing session_id query parameter"})

    session_details = validate_session_cookies(request.cookies.get('my-application-cookie'))

    user_id = None
    if oauth2_config:
        user_id = session_details.get(USER_ID)

    if not user_id:
        console.print(f"Missing {USER_ID} in session_details")
        return JSONResponse(status_code=500, content={"message": "Internal Server Error"})

    console.print(f"Handling 3LO callback for workload_user_id={user_id} | session_id={session_id}", soft_wrap=True)

    region = agent_config.aws.region
    if not region:
        console.print("AWS Region not configured")
        return JSONResponse(status_code=500, content={"message": "Internal Server Error"})

    identity_client = IdentityClient(region)
    identity_client.complete_resource_token_auth(
        session_uri=session_id, user_identifier=UserIdIdentifier(user_id=user_id)
    )

    return JSONResponse(status_code=200, content={"message": "OAuth2 3LO flow completed successfully"})

測試 – 完成設定後，您就可以測試整合。首先，在瀏覽器中呼叫 GetResourceOauth2Token和 ，前往傳回的授權 URL。在 OAuth 2.0 資源提供者完成授權後，您應該會看到瀏覽器重新導向回您的應用程式 URL 並叫用 CompleteResourceTokenAuth API。一旦應用程式傳回有效的回應，您的代理程式應用程式將能夠擷取最初為使用者請求的 OAuth 2.0 存取字符。您可以透過呼叫 GetResourceOauth2Token API 來擷取這些字符。