OAuth 2.0 授权 URL 会话绑定

调用代理 -当原始代理用户想要访问拥有的某些应用程序或资源时，您的代理代码会调用 GetResourceOauth2Token API 来检索授权 URL。 he/she

生成授权 URL — I AgentCore dentity 生成授权 URL 和会话 URI，供用户导航并同意访问。

授权并获取访问令牌 -用户导航到授权 URL 并同意您的代理访问 his/her 资源。之后， AgentCore Identity 使用包含授权请求原始用户的信息将用户的浏览器重定向到您的 HTTPS 应用程序终端节点。此时，您的 HTTPS 应用程序终端节点确定原始代理用户是否仍与应用程序的当前登录用户相同。如果它们匹配，您的应用程序终端节点会调用，CompleteResourceTokenAuth这样 Id AgentCore entity 就可以提取和存储访问令牌。

Re-invoke 代理获取访问令牌 -应用程序返回有效响应后，您的代理应用程序将能够检索最初为用户请求的 OAuth2.0 访问令牌。如果用户不匹配，则您的应用程序只会不执行任何操作或记录尝试。

创建应用程序 URL — 对于面向用户的浏览器应用程序，创建并托管一个新的 URL，该网址可从用户浏览器访问，并且可以接受来自浏览器重定向的请求。此页面应重定向到用户可以继续进行代理会话的应用程序页面，或者呈现一些基本的网页，指示用户返回其当前处于活动状态的代理会话。在实施的后续部分中，此页面用于验证当前用户的活动会话，因此此页面还应该能够访问和维护您的应用程序用户会话数据。

例如，您的应用程序可能会让其用户在主应用程序页面上与代理进行交互，例如https://myagentapp.com/assistant。你需要公开一个像https://myagentapp.com/callback这样的新网址，现在将重定向到主应用程序页面。稍后将在遵循本指南时更新/callback端点中的实际代码逻辑。

使用应用程序 URL 更新工作负载身份 —（如果通过 AgentCore CLI 进行本地测试，则可以跳过）创建并托管了要重定向到的 Id AgentCore entity 的应用程序 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 身份” 中创建 OAuth 2.0 凭据提供商 — 要完全注册 OAuth 2.0 凭据提供商，您需要具有调用和的权限。CreateOauth2CredentialProvider UpdateOauth2CredentialProvider按照以下步骤进行操作：

添加用于调用的代码处理程序 CompleteResourceTokenAuth -创建 OAuth 2.0 凭证提供商后，在应用程序 URL 处理程序中添加调用 CompleteResourceTokenAuth API 的代码和 IAM 权限。调用 CompleteResourceTokenAuth API 时，您的应用程序必须出示用于生成工作负载访问令牌的原始入站身份提供商 OAuth 令牌或user_id字符串，以代表 OAuth 2.0 授权流程中涉及的用户和代理应用程序。这些信息应从用户浏览器上的活动应用程序会话中获取（通常通过浏览器 cookie 或浏览器本地存储空间），不应从任何远程会话缓存中提取。

此外，由 I AgentCore dentity 生成的每个授权 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 并调用 API。CompleteResourceTokenAuth应用程序返回有效响应后，您的代理应用程序将能够检索最初为用户请求的 OAuth 2.0 访问令牌。这些令牌可以通过调用 GetResourceOauth2Token API 来获取。