AWS bedrock-agentcore documentation change
Summary
Updated OAuth 2.0 authorization URL session binding documentation with minor text formatting changes (straight quotes to curly quotes), clarified deployment requirements for AgentCore Runtime, fixed markdown formatting for a URL, and reorganized implementation steps for better readability.
Security assessment
The changes are primarily editorial and organizational, focusing on improving clarity and formatting. No specific security vulnerability, weakness, or incident is mentioned or addressed. The existing security guidance (e.g., CSRF protection, session verification) is reiterated but not newly added.
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 7f070fdd6..149662ce4 100644 --- a//bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.md +++ b//bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.md @@ -11 +11 @@ AgentCore Identity provides OAuth 2.0 access token retrievals for your agent app -However, since a user may accidentally send the authorization URL to another user and gain access to that user's application or resource, your application must verify that the user who initiates an authorization request is still the same as the user who has granted consent to the application or resource. To do that, you need to register a publicly available HTTPS application endpoint with AgentCore Identity that handles user verification. +However, since a user may accidentally send the authorization URL to another user and gain access to that user’s application or resource, your application must verify that the user who initiates an authorization request is still the same as the user who has granted consent to the application or resource. To do that, you need to register a publicly available HTTPS application endpoint with AgentCore Identity that handles user verification. @@ -23 +23 @@ The following flow diagram and corresponding steps show the OAuth 2.0 authorizat - 3. **Authorize and obtain access token** – The user navigates to the authorization URL and grants consent for your agent to access his/her resource. After that, AgentCore Identity redirects the user's browser to your HTTPS application endpoint with information containing the originating user of the authorization request. At this point, your HTTPS application endpoint determines if the originating agent user is still the same as the currently logged in user of your application. If they match, your application endpoint invokes `CompleteResourceTokenAuth` so that AgentCore Identity can fetch and store the access token. + 3. **Authorize and obtain access token** – The user navigates to the authorization URL and grants consent for your agent to access his/her resource. After that, AgentCore Identity redirects the user’s browser to your HTTPS application endpoint with information containing the originating user of the authorization request. At this point, your HTTPS application endpoint determines if the originating agent user is still the same as the currently logged in user of your application. If they match, your application endpoint invokes `CompleteResourceTokenAuth` so that AgentCore Identity can fetch and store the access token. @@ -40 +40 @@ You can refer to sample code as an example of a working application: [OAuth 2.0 -When you are using the AgentCore CLI with `agentcore dev` in a local environment, to simplify your local development and testing, the CLI 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. +When you are using the AgentCore CLI with `agentcore dev` in a local environment, to simplify your local development and testing, the CLI 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. @@ -42 +42 @@ When you are using the AgentCore CLI with `agentcore dev` in a local environment -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** @@ -44 +44 @@ However, when deploying your agent code to AgentCore Runtime, your web applicati -###### 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. @@ -46 +46 @@ However, when deploying your agent code to AgentCore Runtime, your web applicati - 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. @@ -48,3 +48 @@ However, when deploying your agent code to AgentCore Runtime, your web applicati -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 AgentCore CLI) 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. + 2. **Update workload identity with application URL** – (Can be skipped if testing locally via AgentCore CLI) 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. @@ -65 +63 @@ Sample `UpdateWorkloadIdentity` API call: - * API response will contain an OAuth callback (redirect) URL like: `https://bedrock-agentcore.amazonaws.com/identities/callback/`123-456-7890`` + * API response will contain an OAuth callback (redirect) URL like: `https://bedrock-agentcore.amazonaws.com/identities/callback/123-456-7890` @@ -67 +65 @@ Sample `UpdateWorkloadIdentity` API call: -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. +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. @@ -75 +73 @@ Record this value as it's specific for each provider that is created and will be - 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. + 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. @@ -127 +125 @@ When implementing OAuth 2.0 authorization URL session binding, keep the followin - * 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. + * 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.