AWS bedrock-agentcore medium security documentation change
Summary
Expanded documentation for OAuth2 authorization URL session binding with implementation steps, code samples, and deployment guidance
Security assessment
Added explicit guidance about requiring HTTPS callback endpoints, session validation via cookies, and CSRF protection via opaque state parameters. The sample code demonstrates session validation and user identity binding, which are security-critical controls for OAuth2 flows.
Diff
diff --git a/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.md b/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.md index e1043806a..3ddb1bd4f 100644 --- a//bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.md +++ b//bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.md @@ -34 +34,3 @@ By allowing your application endpoint to verify the user identity, AgentCore Ide -When calling the `CompleteResourceTokenAuth` API, your application must present the original inbound identity provider Oauth token or static user identifier that was used to generate the workload access token to represent the user and the agent application involved in the OAuth2.0 authorization flow. Additionally, each authorization URL that gets generated by AgentCore Identity is uniquely identified with its own session URI. This session URI must also be presented alongside the user identifier in order to bind the session with the intended user. +The following steps walk you through setting up the workload identity, the OAuth 2.0 credential provider, and the OAuth 2.0 application client from the resource provider for retrieving an OAuth 2.0 access token for your agent application. + +You can refer to sample code from the starter toolkit as an example of a working application: [OAuth 2.0 callback server implementation](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/main/src/bedrock_agentcore_starter_toolkit/operations/identity/oauth2_callback_server.py#L50-L81). @@ -38 +40,32 @@ When calling the `CompleteResourceTokenAuth` API, your application must present -Prior to your application calling the `CompleteResourceTokenAuth` API, your application must verify that the current user has an active, valid session with your application. By doing so your application can associate the intended user with the Authorization session. +When you are using the [Amazon Bedrock AgentCore Starter Toolkit](https://github.com/aws/bedrock-agentcore-starter-toolkit) in a local environment, to simplify your local development and testing, the toolkit hosts the callback endpoint and calls the `CompleteResourceTokenAuth` API on your behalf to verify the user session to get OAuth 2.0 access tokens so you can skip steps 1, 2 and 4 in the following setup. + +However, when deploying your agent code to AgentCore Runtime, your web application that connects to the agent runtime must host a publicly accessible HTTPS callback endpoint itself, the callback endpoint must be registered against the workload identity as an `AllowedResourceOAuth2ReturnUrl` by calling `UpdateWorkloadIdentity` using the agent ID provided by AgentCore Runtime, and then call the `CompleteResourceTokenAuth` API after verifying the current user's browser session to secure your OAuth 2.0 authorization flows. + +###### To implement OAuth 2.0 authorization URL session binding + + 1. **Create an application URL** – For your user-facing browser application, create and host a new URL that is accessible from the user browser and can accept requests from browser redirects. This page should either redirect to an application page that your user can continue with their agent session OR render some basic web page instructing your users to return their currently active agent session. In later parts of the implementation, this page is used for validation of the current user's active session, so this page should also be able to access and maintain your application user session data. + +As an example, your application may have its users interact with an agent at a primary application page like `https://`myagentapp.com`/assistant`. You'll want to expose a new URL like `https://`myagentapp.com`/callback` that for now will redirect to the primary application page. The actual code logic in your `/callback` endpoint will be updated later when following this guide. + + 2. **Update workload identity with application URL** – (Can be skipped if testing locally via toolkit) Once you have created and hosted an application URL for AgentCore Identity to redirect to, update your workload identity so that the application URL is registered as an `AllowedResourceOauth2ReturnUrl`. Make sure that the IAM credentials used have permissions to call `CreateWorkloadIdentity` or `UpdateWorkloadIdentity` depending on whether you're creating a new workload identity or updating an existing one. + +###### Note + +For workload identities created on your behalf by AgentCore Runtime or Gateway, the workload identity name will correspond to the runtime ID or gateway ID that is issued by the services. + +Sample `UpdateWorkloadIdentity` API call: + + aws bedrock-agentcore-control update-workload-identity --name GoogleCalendarAgent \ + --allowed-resource-oauth2-return-urls https://myagentapp.com/callback + + 3. **Create OAuth 2.0 credential provider in AgentCore Identity** – To register the OAuth 2.0 credential provider fully, you need permissions to call `CreateOauth2CredentialProvider` and `UpdateOauth2CredentialProvider`. Follow these steps: + + * Call `CreateOauth2CredentialProvider` with placeholders for client ID and client secret. + + * API response will contain an OAuth callback (redirect) URL like: `https://bedrock-agentcore.amazonaws.com/identities/callback/`123-456-7890`` + +Record this value as it's specific for each provider that is created and will be needed later by the OAuth 2.0 resource provider. + + * Go to your resource provider (for example, Google or GitHub) and create an OAuth 2.0 application client. Provide the callback URL issued by the service from the `CreateOauth2CredentialProvider` call to the resource provider as an allowed OAuth 2.0 callback URL. + + * Once the OAuth 2.0 application client has been created, record the client ID and client secret assigned to your app client as you need to update the OAuth 2.0 Credential Provider with these values. @@ -40 +73,5 @@ Prior to your application calling the `CompleteResourceTokenAuth` API, your appl -Once the application returns a valid response, your agent application will be able to retrieve the OAuth2.0 access tokens that were originally requested for the user. + * Call `UpdateOauth2CredentialProvider` and provide the client ID and client secret provided by the resource provider, replacing the placeholder values that were provided when creating the credential provider. + + 4. **Add code handler for calling`CompleteResourceTokenAuth`** – Once you have created your OAuth 2.0 credential provider, add code and the IAM permissions to call the `CompleteResourceTokenAuth` API in your application URL handler. When calling the `CompleteResourceTokenAuth` API, your application must present the original inbound identity provider OAuth token or `user_id` String that was used to generate the workload access token to represent the user and the agent application involved in the OAuth 2.0 authorization flow. This information should be fetched from the active application session on the user's browser (typically through a browser cookie or in browser local storage) and should NOT be pulled from any remote session cache. + +Additionally, each authorization URL that gets generated by AgentCore Identity is uniquely identified with its own session URI. This session URI must also be presented alongside the user identifier to bind the session with the intended user. @@ -44 +81,38 @@ Once the application returns a valid response, your agent application will be ab -When you are using the [Amazon Bedrock AgentCore Starter Toolkit](https://github.com/aws/bedrock-agentcore-starter-toolkit) in a local environment, the toolkit hosts the callback endpoint and calls the `CompleteResourceTokenAuth` API on your behalf to verify the user session to get OAuth2.0 access tokens. This is to simplify your local development and testing. +Prior to your application calling the `CompleteResourceTokenAuth` API, your application must verify that the current user has an active, valid session with your application. By doing so your application can associate the intended user with the Authorization session. Furthermore, if you have a backend service that your application depends on, you can move the code that calls `CompleteResourceTokenAuth` API to your backend, and have your application forward the inbound identity provider OAuth token or `user_id` to your backend. + +Sample application code: + + 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"}) + + 5. **Test** – Once you have completed the setup, you are ready to test the integration. Start by calling `GetResourceOauth2Token` and in your browser go to the Authorization URL that is returned. After completing the authorization at the OAuth 2.0 resource provider, you should see the browser redirect back to your application URL and invoke the `CompleteResourceTokenAuth` API. Once the application returns a valid response, your agent application will be able to retrieve the OAuth 2.0 access tokens that were originally requested for the user. These tokens can be fetched by calling the `GetResourceOauth2Token` API. + + @@ -46 +119,0 @@ When you are using the [Amazon Bedrock AgentCore Starter Toolkit](https://github -However, when deploying your agent code to AgentCore Runtime, your web application that connects to the agent runtime must host a publicly accessible HTTPS callback endpoint itself, the callback endpoint must be registered against the workload identity as an AllowedResourceOAuth2ReturnUrl by calling `UpdateWorkloadIdentity` using the agent ID provided by AgentCore Runtime, and then call the `CompleteResourceTokenAuth` API after verifying the current user's browser session in order to secure your Oauth2.0 authorization flows. @@ -54 +127 @@ When implementing OAuth 2.0 authorization URL session binding, keep the followin - * In order to secure your application callback endpoint against CSRF attacks, we highly recommend that you generate an opaque state to include in your API call to `GetResourceOAuth2Token`. Your application should be able to parse this value in order to ensure it's serving requests that were initiated by your agent application. + * To secure your application callback endpoint against CSRF attacks, we highly recommend that you generate an opaque state to include in your API call to `GetResourceOAuth2Token`. Your application should be able to parse this value to ensure it's serving requests that were initiated by your agent application.