Who Is Consenting - OAuth Session Binding and the Consent Portal in AgentCore Identity
First Published:
Last Updated:
However, one question remains: Is the person who opens the authorization URL and gives consent the same person who is using the agent? The authorization URL is simply a URL, and a user could inadvertently send it to someone else. If another person opens that URL and gives consent, a token associated with that other person could be stored as belonging to the person using the agent. The AgentCore Identity developer guide addresses this issue in its section on OAuth 2.0 authorization URL session binding (referred to as "session binding" in this article).
According to the available documentation, the responsibility for verifying that the user is the same rests with the agent's application. The application must provide a publicly accessible HTTPS endpoint. After consent is given, AgentCore Identity redirects the user's browser to that endpoint. The endpoint then extracts the user who is signed in to the application within that browser, using the application's own session. It then passes both the user and the session URI to
CompleteResourceTokenAuth. AgentCore Identity verifies that the user who was passed is the same user who initiated the process before retrieving and storing the token. If the users do not match, the developer guide states that the application should either take no action or simply log the attempt.In September 2026, AgentCore Identity introduced a consent portal. This portal is a consent screen operated by AWS for AgentCore Gateway, together with a session binding endpoint. With the consent portal, applications no longer need to host their own endpoints. However, the introduction of the consent portal does not eliminate the need for session binding entirely. The developer guide states that an authorization URL returned when a target is called directly is subject to the same session binding requirements as other authorization URLs created by AgentCore Identity.
This article clarifies who is responsible for verifying that the individual who provided consent is the same person using the agent. It is not an introduction to AgentCore Identity. It does not detail the steps for configuring inbound authentication, nor does it provide a general overview of OAuth. It also does not discuss potential attack vectors or pricing. The information presented was verified as of November 17, 2026.
Related articles on this site:
- Identity Lifecycle for AI Agents - Registration, Delegated Authorization, Access Review, and What Retirement Leaves Behind
- Which MCP Clients a Remote MCP Server Lets In - Client ID Metadata Documents, Pre-Registration, Deprecated Dynamic Client Registration, and the Allowlists Layered on Top
- Agent Interoperability Architecture on AWS - Cross-Runtime Agents with A2A, MCP, and Amazon Bedrock AgentCore Gateway
- Amazon Bedrock AgentCore Implementation Guide Part 2: Multi-Layer Security with Identity, Gateway, and Policy
- OWASP Top 10 for Agentic Applications Mapped to AWS Controls - What Each Control Mitigates and What Residual Risk Remains
Table of Contents
- 1. Scope and Assumptions
- 2. How to Read the Tables
- 3. Who Can Open the Authorization URL
- 4. The Four Steps of Session Binding and Who Checks Each One
- 5. The Callback URL and the Session Binding URL
- 6. The User the Application Presents
- 7. When the Users Do Not Match
- 8. The Consent Portal
- 9. How Session Binding Differs from the OAuth state Parameter
- 10. Where the Sources Disagree and What They Do Not Say
- 11. How This Relates to Existing Articles and the OWASP Agentic Top 10
- 12. Decisions This Design Leaves to You
- 13. Failure Modes
- 14. Frequently Asked Questions About OAuth Session Binding in AgentCore Identity
- 15. Summary
- 16. References
1. Scope and Assumptions
This chapter defines the intended audience, scope, relevant materials, and terminology used in this article. The key conclusions are as follows:- An authorization URL can be opened by people other than the one who received it. The developer guide explains that session binding is necessary because users may inadvertently share authorization URLs with others.
- It is the application's responsibility to verify that the user interacting with the agent is the same user who initially consented. The application must provide a publicly accessible HTTPS endpoint and register it with AgentCore Identity.
- The application's endpoint retrieves the user from the application session in the browser and passes them, along with the session URI, to
CompleteResourceTokenAuth. The developer guide emphasizes that the application should not retrieve users from a remote session cache. - AgentCore Identity verifies that the user passed to it is the same user who initiated the flow before exchanging the authorization code for an access token. If the users do not match, the application should take no action or record the attempt.
- The callback URL and the session binding URL are distinct URLs. The callback URL points to AgentCore Identity and is registered with the external service's OAuth application. The session binding URL points to the application's endpoint and is registered with the workload identity. In AgentCore Gateway, it is configured on the target as the return URL.
- The consent portal is a mechanism by which AWS manages the session binding endpoint for AgentCore Gateway. The prerequisites are inbound JWT authentication on the Gateway, the same OIDC issuer, and the
openidscope. Authorization URLs returned when a target is called directly are subject to the same session binding requirements. - In OAuth, the
stateparameter is used to associate the authorization response with the original browser state of the request. Session binding associates consent with the application's user. The developer guide also recommends usingcustomState, which plays the role ofstate.
1.1 Who This Article Is For
This article is intended for developers and security engineers working with AgentCore Identity who need to enable agents to use external OAuth tokens on behalf of users. Examples of external services include GitHub, Slack, and Google Calendar. This article assumes that readers build authorization code grant (3LO) flows in which users give consent. Specifically, this article is aimed at readers who may believe any of the following:- The authorization server authenticates the user, so anyone who has given consent is the same as the person using the agent.
- AgentCore Identity manages the consent flow, so applications do not need to do anything after obtaining consent.
- Using the OAuth
stateparameter allows you to determine that the person who gave consent is the same as the person using the agent. - Using a consent portal eliminates the need to consider session binding.
It is important to note that these assumptions may only partially hold true, or may not hold true at all, depending on the specific documentation or passages being read.
1.2 What This Article Covers and What It Does Not
This article addresses the following topics:- The steps involved from the issuance of an authorization URL to the storage of a token, and who verifies what at each step.
- The differences between callback URLs and session binding URLs, and where each is registered.
- The user information that the application passes to
CompleteResourceTokenAuth, and from where that information is obtained. - What the application does not do when the users do not match.
- The responsibilities of the consent portal, and what it does not handle.
- The differences between OAuth's
stateand session binding, and the corresponding requirement in the MCP specification.
This article does not cover the following topics:
- An introduction to AgentCore Identity, the process of configuring inbound authentication, or creating credential provider configurations.
- Agent registration, recording delegated authorization, access reviews, and decommissioning. This is covered in the existing article Identity Lifecycle for AI Agents - Registration, Delegated Authorization, Access Review, and What Retirement Leaves Behind.
- Which MCP clients a remote MCP server accepts. This is covered in the existing article Which MCP Clients a Remote MCP Server Lets In - Client ID Metadata Documents, Pre-Registration, Deprecated Dynamic Client Registration, and the Allowlists Layered on Top.
- Token exchange (on-behalf-of) for carrying a user's identity from one hop to another. This is covered in Section 5.2 of the existing article Agent Interoperability Architecture on AWS - Cross-Runtime Agents with A2A, MCP, and Amazon Bedrock AgentCore Gateway.
- Session-specific permissions for AgentCore Runtime. This is covered in a separate article on this site, Scoping Each Session on AgentCore Runtime - Session Context Keys, Who Chooses the Session ID, and What the Keys Do Not Prove.
- General concepts of OAuth, attack methods, and pricing.
1.3 Confirmation Date and Sources
This article was verified on November 17, 2026, using the following materials. Throughout the text, these will be referred to by their short names, as indicated in parentheses.- Amazon Bedrock AgentCore Developer Guide: OAuth 2.0 authorization URL session binding (session binding page).
- From the same guide: four pages related to the consent portal: Configure a consent portal (consent portal page), Consent portal prerequisites (prerequisites page), Configure a consent portal target (target page), and Consent portal execution role (execution role page).
- Also from the same guide: MCP servers targets (Gateway MCP target page) and Example: Authentication with an authorization code grant when invoking a gateway (Gateway 3LO example page).
- Further from the same guide: Get workload access token (workload access token page) and Security best practices for AgentCore Runtime (Security best practices page).
- Amazon Bedrock AgentCore API Reference:
GetResourceOauth2Token,CompleteResourceTokenAuth,UserIdentifier. - What's New: two entries. September 1, 2026: Amazon Bedrock AgentCore Identity now offers a managed consent portal (consent portal What's New). November 13, 2026: Amazon Bedrock AgentCore Identity now supports OAuth 2.0 discovery URLs (discovery URL What's New).
- AWS Machine Learning Blog: three posts. April 6, 2026: Connecting MCP servers to Amazon Bedrock AgentCore Gateway using Authorization Code flow (Gateway authorization code post). May 5, 2026: Secure AI agents with Amazon Bedrock AgentCore Identity on Amazon ECS (ECS post). September 14, 2026: Manage end-user OAuth consent for AI agents with Amazon Bedrock AgentCore (consent portal post).
- Section 10.12 of RFC 6749 (The OAuth 2.0 Authorization Framework) and sections 2.1 and 4.7 of RFC 9700 (Best Current Practice for OAuth 2.0 Security).
- Version 2026-07-28 of the Model Context Protocol specification, specifically the Elicitation page (MCP Elicitation page). As of the verification date, the latest URL for this specification has been redirected to this version.
1.4 Terms Used in This Article
This article uses the following terms with the following meanings:- 3LO: An OAuth flow that uses the authorization code grant and in which the user gives consent. In the AgentCore Identity API, this corresponds to the
oauth2FlowvalueUSER_FEDERATION. - Authorization URL: The URL returned by AgentCore Identity in the response to
GetResourceOauth2Token. The user opens this URL to provide consent. - Session URI: An identifier issued by AgentCore Identity for each authorization URL. In the API Reference, this is referred to as
sessionUriand begins withurn:ietf:params:oauth:request_uri:. The sample code in the developer guide and the ECS post receive this value as a query parameter namedsession_id. - Application session: The state where a user is signed in to an agent's application. This is often maintained using a browser cookie.
- Originating user: The user represented by the workload access token when
GetResourceOauth2Tokenis called. The developer guide refers to this as the "originating user." - Person who consented: The person who opens the authorization URL and provides consent on the external service's authorization server.
- Callback URL and session binding URL: The two URLs defined in Chapter 5.
- Consent portal: A consent screen operated by AWS, provided by AgentCore Identity for AgentCore Gateway. The developer guide writes "consent portal" in lowercase, while the consent portal post writes "Consent portal." This article follows the terminology used in the developer guide.
In this article, the term "session" refers only to the session URI, the application session, and the browser session of the consent portal described in Chapter 8. The runtime session (
runtimeSessionId) within AgentCore Runtime is not considered a "session" in this article. Permissions associated with a runtime session are covered in a separate article on this site, Scoping Each Session on AgentCore Runtime - Session Context Keys, Who Chooses the Session ID, and What the Keys Do Not Prove. Similarly, the MCP session (Mcp-Session-Id) within AgentCore Gateway is not considered a "session" in this article.2. How to Read the Tables
This chapter defines the columns in the tables and how to describe the status of the materials. The terminology used to describe the status of materials is consistent with that used on this website and previously published materials.2.1 Terms for the State of the Sources
This article uses four terms to describe the condition of the sources. Within the tables, this English terminology will be used.- Stated: The source contains a statement regarding the matter in question.
- No statement found: Even when the sources in Section 1.3 are searched with different keywords and different families of sources, no statement on the matter is found. This does not indicate that the matter is absent or impossible.
- Sources disagree: The statements from two different sources regarding the same matter are inconsistent. This includes cases where the statements directly contradict each other, as well as cases where the scope, intensity, or timing differ, and it is not possible to determine which statement is correct based on the text. This article also uses this term for two statements within one source. This article will present both statements and their sources without designating either as incorrect.
- Inference: This represents an inference made by this article, and is not a statement found within any of the sources. This article will clearly indicate when a statement is an inference.
Dates referenced in this article will always be presented with the year. Pages may be revised after the date of verification.
3. Who Can Open the Authorization URL
This chapter explains the problem that session binding addresses.3.1 What the Authorization URL Is
When an agent needs a token from an external service, the agent's code callsGetResourceOauth2Token. If a saved token is not available, AgentCore Identity returns an authorization URL and a session URI instead. The agent's application then displays this authorization URL to the user. This may be presented within a chat window, or it may be passed to an IDE or MCP client.The authorization URL is a standard URL that can be opened in the user's browser. As an inference by this article, the URL itself does not know who opens it. If a user receives this URL and forwards it to someone else, that other person can also open the same URL.
3.2 Two People, One Consent
The session binding page explains why session binding is needed as follows: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.
In this scenario, there are two individuals involved. One is the user who is using the agent and whose request led to the call to
GetResourceOauth2Token. This article calls this person the originating user. The other is the person who consented by opening the authorization URL. While these individuals are often the same, the authorization URL itself does not guarantee this.The authorization server authenticates the user as a user of an external service before obtaining consent. As an inference by this article, what the authorization server verifies is the owner of the account on the external service. The authorization server does not know which user of the agent's application started the request that led to this consent. Therefore, the mechanism to verify whether these two individuals are the same must reside outside the authorization server.
The ECS post lists two potential issues that session binding prevents. One is the scenario where another person's token is associated with your ID, causing your agent to inadvertently access resources belonging to someone else. The ECS post refers to this as CSRF. The other is the scenario where your token is associated with another person's ID, allowing that other person to access your resources. The ECS post refers to this as a browser swapping attack. Both scenarios involve a situation where the association between a token, the consent it was obtained with, and the user it belongs to is compromised. This article does not go into how these attacks are carried out.
4. The Four Steps of Session Binding and Who Checks Each One
This chapter outlines the four steps of session binding and provides a table detailing who is responsible for verifying each step. Figure 1 illustrates the process flow and indicates where user verification takes place.
4.1 The Four Steps
The session binding page describes the process in four steps:- Invoke agent: The agent's code calls
GetResourceOauth2Tokento receive the authorization URL. - Generate authorization URL: AgentCore Identity creates the authorization URL and the session URI.
- Authorize and obtain access token: The user opens the authorization URL and provides consent. AgentCore Identity redirects the user's browser to the application's HTTPS endpoint. The endpoint determines if the originating user is the same as the user currently signed in to the application. If they are the same, the endpoint calls
CompleteResourceTokenAuth. - Re-invoke agent to obtain access token: The agent's code calls
GetResourceOauth2Tokenagain to receive the access token.
Regarding the third step, the session binding page describes the process as follows:
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.
The third step involves four actions. In Figure 1 and Table 1, this article divides this step into 3a through 3d. This division is based on how the Gateway authorization code post and the ECS post describe their steps.
- 3a: The person opens the authorization URL and consents on the external service's authorization server.
- 3b: The authorization server sends the authorization code to AgentCore Identity's callback URL.
- 3c: AgentCore Identity redirects the user's browser to the application's session binding URL, with the session URI.
- 3d: The application's endpoint passes the session URI and the user to
CompleteResourceTokenAuth. AgentCore Identity exchanges the authorization code for an access token and stores it in the token vault.
4.2 Who Checks What
Table 1 shows, for each step, who checks what. The verification date is November 17, 2026.| Step | What happens | Who checks | What is checked | Source state |
|---|---|---|---|---|
| 1 | Your agent code calls GetResourceOauth2Token with a workload access token | AgentCore Identity | Whether a valid token is already stored for this user | Stated (ECS post) |
| 2 | AgentCore Identity returns an authorization URL and a session URI | Your application | Which channel delivers the URL to the user | Inference |
| 3a | The person opens the URL and consents at the authorization server | Authorization server | Who owns the account at the third-party service | Inference |
| 3b | The authorization server sends the authorization code to the callback URL | AgentCore Identity | (Receives the code; no token is stored yet) | Stated (ECS post) |
| 3c | AgentCore Identity redirects the browser to your session binding URL with the session URI | Your application endpoint | Whether the browser has an active, valid session with your application | Stated (session binding page) |
| 3d | Your endpoint calls CompleteResourceTokenAuth with the session URI and the user | AgentCore Identity | Whether the presented user is the user who started the flow | Stated (Gateway MCP target page) |
| 4 | Your agent code calls GetResourceOauth2Token again | AgentCore Identity | Returns the stored access token | Stated (session binding page) |
In Table 1, the external service's authorization server performs neither of the two user checks. The application endpoint checks the application session (3c), and AgentCore Identity compares the presented user with the originating user (3d).
4.3 What the Application and AgentCore Identity Each Compare
Step 3 on the session binding page states that the endpoint determines whether the originating user is the same as the current user. In contrast, the Gateway MCP target page states that AgentCore Identity does the comparison.The application is then responsible for calling the CompleteResourceTokenAuth API, presenting both the user’s identity and the session URI. Amazon Bedrock AgentCore Identity validates that the user who started the flow is the same user who completed it before exchanging the authorization code for an access token.
The sample code on the session binding page validates the application's session using a cookie, extracts the user's ID, and passes that ID along with the session URI to
CompleteResourceTokenAuth. The sample code provided on that page does not include any logic to compare the current user with the originating user. As an inference by this article, the two pages can be read as the following division of labor: the application determines who is currently using the browser based on its own session and passes that information. AgentCore Identity then compares the passed user with the user who initiated the flow.Under this reading, AgentCore Identity handles the comparison. However, the application determines one of the values being compared. If the application passes the originating user instead of the current user, the two values being compared will always be the same. For example, the application could retrieve the originating user from server-side storage using the session URI as a key, and pass that information. In that scenario, no verification is performed. This article suggests that the reason the developer guide specifies that users should not be retrieved from a remote session cache is related to this point. This will be addressed in Chapter 6.
5. The Callback URL and the Session Binding URL
This chapter describes two URLs related to session binding, and indicates where each should be registered. The ECS post notes that these two URLs are often confused, and clarifies the distinction as follows:Callback URL: Automatically generated when creating an OAuth client in AgentCore Identity. It points to AgentCore Identity and must be registered with the Authorization Server as the redirect target where the authorization code is sent after user authentication.
Session Binding URL: The URL pointing back to a customer-managed service that completes the session binding between the authenticated user and the OAuth flow. This endpoint is implemented and hosted by the customer.
5.1 The Callback URL
AgentCore Identity issues the callback URL for each credential provider. According to the session binding page, the response fromCreateOauth2CredentialProvider includes the OAuth callback URL. The page provides https://bedrock-agentcore.amazonaws.com/identities/callback/123-456-7890 as an example, noting that this value differs for each credential provider. This URL should be registered as an allowed callback URL in the OAuth application of an external service (such as Google or GitHub). The authorization code is then delivered to AgentCore Identity via this callback URL (see Table 1, 3b).5.2 The Session Binding URL
The session binding URL is an endpoint URL that the application itself provides. The session binding page requires that this URL be reachable from the browser and be able to read the application user's session data. The URL is registered inallowedResourceOauth2ReturnUrls on the workload identity. When calling GetResourceOauth2Token, the application can pass this URL to the resourceOauth2ReturnUrl parameter. According to the API Reference, this URL must be one of the URLs registered for the workload identity.For workload identities created by AgentCore Runtime or AgentCore Gateway, the name of the workload identity will correspond to the Runtime ID or Gateway ID. The session binding page notes this point.
The session binding page also includes the following note regarding the
agentcore dev tool: agentcore dev does not have an OAuth callback endpoint and does not call CompleteResourceTokenAuth. Even when testing locally, the application must implement this endpoint.5.3 The Return URL on a Gateway Target
When a Gateway target uses 3LO, the user's browser will return to the default return URL (defaultReturnUrl). The target page and the Gateway MCP target page state that this URL is configured on the target (the sources differ on where it is set; see Section 10.1). According to the Gateway 3LO example page, the MCP request's _meta section includes a returnUrl parameter, allowing the return destination to be changed for each call. Setting forceAuthentication in the same _meta to true removes the previous authentication from the token vault and returns a new authorization URL.The Gateway MCP target page states that session binding applies both when the target is created (implicit sync) and when the tool is invoked. If an administrator creates a target through the AWS Management Console and completes authorization there, the
CompleteResourceTokenAuth call will be made on behalf of the resource owner, and no further action is required.6. The User the Application Presents
This chapter describes the user information that the application passes toCompleteResourceTokenAuth, and specifies the source of that user information.6.1 userId or userToken
According to the API Reference, theCompleteResourceTokenAuth request requires two values, both of which are mandatory. Table 2 details these two values.| Field | What it holds | Constraint in the API Reference |
|---|---|---|
sessionUri | The identifier of the authorization session | Pattern urn:ietf:params:oauth:request_uri:[a-zA-Z0-9-._~]+, 1 to 1024 characters |
userIdentifier | The user, as a union of userId or userToken | Only one member can be specified |
The
UserIdentifier must contain one of the two values: userId, which is the ID of the user for whom the workload access token was retrieved; or userToken, which is an OAuth 2.0 token issued by the user's identity provider (IdP) and used to create the workload access token. Upon successful completion, CompleteResourceTokenAuth returns an HTTP 200 status code with an empty response body.6.2 Where the Application Reads the User From
The session binding page describes how the application determines the user it is passing along, as follows: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.
The Important note on the same page reads as follows:
Prior to your application calling the CompleteResourceTokenAuth API, your application must verify that the current user has an active, valid session with your application.
Under the reading in Section 4.3, this is the core of the application's responsibility. The application passes the user who is currently signed in to the application in the browser that arrived at the session binding URL. If that browser does not have a valid application session, it will not call
CompleteResourceTokenAuth.The same note also states that the code that calls
CompleteResourceTokenAuth may be moved to a backend service that the application depends on. In that case, the application passes either the inbound IdP's OAuth token or the user_id to the backend. As an inference by this article, even after the move, the value still comes from the application session in the current browser.In the ECS post's architecture, the Application Load Balancer authenticates the user using OIDC and places the user's claims in the
x-amzn-oidc-data header. Both the agent and the session binding service extract the user's ID from the sub field within this header. The ECS post states:Session binding prevents both attacks by ensuring that the user ID at the agent workload matches the user ID at the Session Binding Service, with both identities cryptographically verified through the authentication chain.
6.3 Why the userId Path Needs a Trusted Source
The workload access token page states, regarding theuserId passed to GetWorkloadAccessTokenForUserId:Because the platform cannot verify the userId string, you are responsible for ensuring the integrity of the value passed to this API.
The same page recommends prioritizing
GetWorkloadAccessTokenForJWT whenever a JWT is available. This is because the JWT path allows for verification of the token issuer and signature. The Security best practices page also recommends prioritizing the JWT path over the userId path in production environments when obtaining tokens on behalf of a user.This statement is about the step that retrieves a workload access token. As an inference by this article, from AgentCore Identity's point of view, the
userId of CompleteResourceTokenAuth is also a string that the application passes. The application decides both the userId of the originating user and the userId of the current user. If using the userId path, both values must be obtained from the context of an authenticated principal. The workload access token page states that the userId should be retrieved from the context of an authenticated principal and that arbitrary values provided by the client should not be used.7. When the Users Do Not Match
This chapter describes what the application does and does not do when the users do not match.7.1 What the Application Does Not Do
In its description of step 4, the session binding page states the following:If the users do not match, your application simply does nothing or logs the attempt.
What the application does not do is call
CompleteResourceTokenAuth. If it does not, AgentCore Identity will not exchange the authorization code for an access token, nor will it store the token in the token vault (see Table 1, 3d). As an inference by this article, even if the agent's code calls GetResourceOauth2Token in step 4, no token is returned.As an inference by this article, for the application to record attempts, it must know the originating user. There are two possible ways to achieve this. One is for the application to record the association between the session URI received in the second step and the originating user. The other is to call
CompleteResourceTokenAuth and record the error returned by AgentCore Identity. In either case, the user passed to CompleteResourceTokenAuth is taken from the current browser application session. The originating user recorded by the first method is used only for comparison and is not used as the value passed to the function.The API Reference for
CompleteResourceTokenAuth lists six possible errors: AccessDeniedException, InternalServerException, ResourceNotFoundException, ThrottlingException, UnauthorizedException, and ValidationException. No statement was found in the sources reviewed for this article on which error is returned when the users do not match (No statement found).7.2 The Ten-Minute Window and Forcing a New Flow
The session binding page states the following as an additional consideration:Each authorization URL and its corresponding session identifier are only valid for 10 minutes.
The Gateway MCP target page describes this ten-minute period as further limiting the window for misuse. As an inference by this article, ten minutes narrows the window, but it does not prevent another person from opening the URL within those ten minutes. What prevents that is the check at steps 3c and 3d.
The
sessionStatus field in the response from GetResourceOauth2Token will have a value of either IN_PROGRESS or FAILED. According to the API Reference, the forceAuthentication parameter in the request to GetResourceOauth2Token always initiates a new 3LO flow, regardless of any existing session. The ECS post states that when an external service revokes a token, a new authentication flow can be initiated with forceAuthentication: true.7.3 What CloudTrail Records
The consent portal post states that AgentCore logs consent operations to AWS CloudTrail, specifically mentioning three events:GetResourceOauth2Token, CompleteResourceTokenAuth, and GetWorkloadAccessTokenForJWT. The post further explains that the GetResourceOauth2Token event includes information such as the credential provider, requested scopes, OAuth flow, the consent portal's execution role, and Region. It notes that the token and state values are masked. As an inference by this article, failed CompleteResourceTokenAuth events can provide valuable data for correlating with application logs.8. The Consent Portal
This chapter outlines what the consent portal does and what it does not. Figure 2 shows where the browser and the token go, both with and without the consent portal.
8.1 What the Portal Takes Over
The consent portal post lists what developers had to build themselves before the consent portal: displaying authorization URLs, providing a publicly accessible HTTPS callback, authenticating returning users, managing browser sessions, and completing the process by callingCompleteResourceTokenAuth. The post describes the consent portal as a consent screen and session binding endpoint, operated by AWS, for AgentCore Gateway.The consent portal page describes the nature of the consent portal as follows:
The portal keeps the OAuth flow server-side: the browser never holds a token.
According to the Behind the scenes section of the consent portal post, the process works as follows: the consent portal validates the IdP's response and creates an encrypted browser session. When a user selects "Connect," the consent portal calls
GetResourceOauth2Token, receiving the authorization URL and session URI. After an external service returns the authorization code to AgentCore Identity, the browser returns to the consent portal's session binding endpoint, operated by AWS. The consent portal then calls CompleteResourceTokenAuth with the authenticated user context.As an inference by this article, in the consent portal, the sign-in to the consent portal determines the current user. Users sign in to the consent portal with the same IdP as the Gateway's inbound JWT authentication. When a consent portal is created, AWS validates that the Gateway’s authorization configuration and the consent portal's credential provider point to the same OIDC issuer. Consequently, the user signed in to the consent portal and the user calling the Gateway are both users of the same IdP.
The consent portal What's New describes who benefits from using the consent portal as follows:
Developers using agent IDE-based clients, which cannot natively present OAuth consent URLs or handle post-consent session binding, can now use the managed consent portal as a dedicated authorization surface for these workflows.
8.2 Prerequisites
According to the prerequisites page and the consent portal post, the consent portal requires the following:- AgentCore Gateway. Its inbound authentication type must be JWT, and its authorizer must reference an OIDC identity provider (IdP). The consent portal connects to exactly one gateway. According to the consent portal post, a gateway can have only one consent portal, and the gateway cannot be changed after the portal is created.
- OAuth2 credential provider for the identity provider (IdP) that users will use to sign in (primary IdP). This provider must use the same OIDC issuer as the gateway's JWT authorization. The scopes permitted on the IdP application that backs it must include
openid. - Execution role that the consent portal will assume. The consent portal uses this role to read the gateway and credential provider configurations and retrieve the OAuth client secret.
The prerequisites page describes the requirements for the primary IdP as follows:
The consent portal requires a primary IdP that issues JWT access tokens and is OIDC-compatible. Providers that issue opaque access tokens cannot be used as the primary IdP. Similarly, providers that support only OAuth 2.0 and cannot issue an ID token also cannot be used as the primary IdP. Such unsupported IdPs remain valid as outbound credential providers for gateway targets.
8.3 Three URLs in a Portal Setup
Using the consent portal results in three URLs. Table 3 is based on the table in the consent portal post.| URL | Where it is configured | What returns there |
|---|---|---|
<portal-url>/callback | The corporate IdP application (primary IdP) | The user, after signing in to the portal |
<portal-url>/connect/callback | Each gateway target, as the default return URL | The user, after consenting at the outbound provider (the managed session binding endpoint) |
AgentCore Identity callbackUrl | The outbound provider application | The authorization code |
The second row in Table 3 corresponds to the session binding URL described in Chapter 5. The third row corresponds to the callback URL described in Chapter 5.
According to the target page, the configuration of
defaultReturnUrl (as shown in the second row) is required even for targets that existed before the consent portal. Furthermore, only targets with a grantType of AUTHORIZATION_CODE will appear on the Connections page of the consent portal. Targets configured with CLIENT_CREDENTIALS do not appear, as they do not require user-specific consent.The target page describes the following behavior when a
defaultReturnUrl is missing or incorrect:If defaultReturnUrl is missing or incorrect, the outbound provider returns the user somewhere other than the consent portal and the consent never binds to the session.
8.4 What the Portal Does Not Take Over
Even with a consent portal in place, users may sometimes call a target directly. The target page describes that case as follows:When a target is called directly without a valid stored credential, AgentCore Identity returns an authorization URL for the user to navigate to and grant consent, rather than returning an access token. This happens, for example, when a user invokes a target directly (such as through a coding agent) without first granting consent on the consent portal, or when a previously obtained token expires. To grant consent and let AgentCore Identity fetch and store a new access token, the user must return to the consent portal. This direct authorization URL is subject to the same session-binding requirements as any authorization URL that AgentCore Identity generates. For more information, see OAuth 2.0 authorization URL session binding.
As an inference by this article, the consent portal does not eliminate the need for session binding. The consent portal is a form in which AWS hosts the session binding endpoint. The portal does not take over the following:
- 3LO that does not go through the gateway. The consent portal connects to only one gateway. Configurations where the application directly calls
GetResourceOauth2Tokenare outside the consent portal. - Return URL settings. It is the administrator's responsibility to configure each target's
defaultReturnUrlto<portalUrl>/connect/callback. - User-facing names. The target page states that the names of the target and the credential provider are shown to users as defined.
- Scenarios without refresh tokens. The consent portal post explains that if an external service does not issue a refresh token, or if it has expired or been revoked, the user must return to the consent portal and reauthorize.
The target page also states that even if targets are added or modified, they may not immediately appear in the Connections page, and the list is cached for a maximum of 5 minutes.
8.5 The November 2026 Discovery URL Change
On November 13, 2026, the discovery URL What's New announced that AgentCore Identity now supports OAuth 2.0 authorization server discovery URLs, both for inbound JWT authorization and for custom OAuth credential providers for outbound access. Previously, it only supported OIDC discovery URLs.As an inference by this article, this change does not alter the requirements for the primary IdP of the consent portal. As of the verification date, the prerequisites page states that OAuth 2.0-only providers that cannot issue an ID token cannot be used as the primary IdP (Section 8.2). While the expanded support for OAuth 2.0 discovery URLs increases the potential options, the consent portal still requires an IdP that supports OIDC and can issue JWT access tokens.
9. How Session Binding Differs from the OAuth state Parameter
This chapter explains what thestate parameter in OAuth and session binding are each associated with.9.1 What state Binds To
Section 10.12 of RFC 6749 describes the CSRF protection for the client redirect URI as follows:The client MUST implement CSRF protection for its redirection URI. This is typically accomplished by requiring any request sent to the redirection URI endpoint to include a value that binds the request to the user-agent's authenticated state (e.g., a hash of the session cookie used to authenticate the user-agent). The client SHOULD utilize the "state" request parameter to deliver this value to the authorization server when making an authorization request.
Section 4.7.1 of RFC 9700 describes this protection as follows:
The long-established countermeasure is that clients pass a random value, also known as a CSRF Token, in the state parameter that links the request to the redirection URI to the user agent session as described.
The
state parameter binds together a request to the redirect URI and the browser's session. As an inference by this article, this countermeasure assumes that the browser initiating the authorization request and the browser receiving the response are the same.9.2 Why the Agent Flow Needs More Than state
As an inference by this article, in AgentCore Identity's 3LO, the browser does not initiate the flow. The agent's code on the server makes the first call toGetResourceOauth2Token. The authorization URL is then delivered to the user through channels such as chat or the IDE. Consequently, there is no browser session active at the point when the flow is initiated. What the binding attaches to is not a browser but the user of the application that uses the agent. Session binding binds consent to this user.The value corresponding to
state also exists within AgentCore Identity, specifically as customState in GetResourceOauth2Token. The API Reference describes customState as follows:An opaque string that will be sent back to the callback URL provided in resourceOauth2ReturnUrl. This state should be used to protect the callback URL of your application against CSRF attacks by ensuring the response corresponds to the original request.
The session binding page also strongly recommends including an opaque state value in the call to
GetResourceOauth2Token to protect the application's callback endpoint from CSRF attacks. The ECS post describes customState as an optional parameter. As an inference by this article, customState can be used to verify that the returned request matches the request initiated by the application. However, it cannot verify who provided the consent. customState and session binding are not replacements for each other; they should be used together.9.3 The Same Requirement in MCP URL Mode Elicitation
The MCP specification, version 2026-07-28, describes URL mode elicitation, in which the MCP server acts as an OAuth client of an external service. In its security considerations, the MCP Elicitation page states:URL mode elicitation returns a URL that an attacker can use to send to a victim. The MCP Server MUST verify the identity of the user who opens the URL before accepting information.
The same page continues with:
To prevent this attack, the server MUST ensure that the user who started the elicitation request (the end-user who is accessing the server via the MCP client) is the same user who completes the authorization flow.
The page further provides an example, though not a formal requirement, illustrating how the MCP server provides the user with its own connect URL, rather than the authorization server's URL. That connect URL checks whether the user of the session cookie is the same as the user who was using the MCP client.
According to the Gateway authorization code post, when AgentCore Gateway detects that a user does not have a token during a tool call, it returns the authorization URL as part of the response in the URL mode elicitation process to the MCP client. As an inference by this article, in an AgentCore Gateway configuration, the return endpoint of the target performs the check that the MCP specification requires of the server. The return endpoint is either the application's session binding URL or the consent portal's
<portalUrl>/connect/callback.10. Where the Sources Disagree and What They Do Not Say
This chapter highlights discrepancies between sources and identifies matters for which no statement was found in the sources.10.1 Where the Sources Differ
Table 4 highlights discrepancies identified in this article.| Topic | Source A | Source B | How this article reads it |
|---|---|---|---|
| Who compares the two users | Session binding page, step 3: your HTTPS application endpoint determines if the originating user is the same as the currently logged in user | Gateway MCP target page and Gateway authorization code post: AgentCore Identity validates that the user who started the flow is the same user who completed it | Sources disagree. The application presents the current user; AgentCore Identity compares it with the originating user (Inference, Section 4.3) |
| Who redirects the browser to the session binding URL | ECS post, step 10: AgentCore Identity redirects the user to the Session Binding URL | ECS post, implementation section: GitHub redirects the user to the session binding URL | Sources disagree. This article follows the session binding page and step 10 |
| Spelling of the API name | Session binding page, additional considerations: GetResourceOAuth2Token | API Reference: GetResourceOauth2Token | Sources disagree. This article uses the API Reference spelling |
Where defaultReturnUrl is set | Gateway 3LO example page: the defaultReturnUrl that you specified when creating the gateway | Consent portal target page and Gateway MCP target page: a return URL configured on the target | Sources disagree. This article follows the two pages that place it on the target |
For the first row, this article's inference is as described in Section 4.3. Under either reading, the user that the application passes still comes from the application session in the current browser.
10.2 What the Sources Do Not Say
No statement on the following was found in the sources reviewed for this article (No statement found):- Which error
CompleteResourceTokenAuthreturns when the users do not match (Section 7.1). - Which value in the redirect carries the information containing the originating user that step 3 of the session binding page describes. The only value that the sample code and the ECS post read from the redirect is the session URI.
11. How This Relates to Existing Articles and the OWASP Agentic Top 10
This chapter clarifies the relationship between this article and existing articles, and outlines its connection to the OWASP Top 10 for Agentic Applications.Section 4.1 of the existing article "Identity Lifecycle for AI Agents" identifies three pieces of information that downstream calls from an agent should possess: which agent is making the call, on behalf of whom, and within what scope. As an inference by this article, session binding serves as a step in determining "on behalf of whom" for tokens stored using 3LO. If another person consents, the record of "on behalf of whom" itself is wrong. Section 6.5.2 of the same article addresses the persistence of user consent provided to external services, even after deletion within AWS. This article focuses on the point at which consent is obtained, and does not address the point at which consent is revoked.
Section 5.2 of the existing article "Agent Interoperability Architecture on AWS" describes a mechanism for transferring a user's identity across hops without repeatedly requesting consent, using token exchange. This article addresses the flow that involves requesting consent from the user, which corresponds to 3LO.
Section 4.9 of the existing article "Amazon Bedrock AgentCore Implementation Guide Part 2" provides an example of a 3LO implementation using
requires_access_token with USER_FEDERATION. This article addresses what the return endpoint should do after the user has provided consent in that example.The existing article "Which MCP Clients a Remote MCP Server Lets In" focuses on the inbound side, detailing which clients a remote MCP server allows. This article, conversely, addresses consent when an agent interacts with an external service.
Chapter 7 of the existing article "OWASP Top 10 for Agentic Applications Mapped to AWS Controls" addresses ASI03, Identity and Privilege Abuse, and includes OAuth tokens and delegated user sessions within that category. As an inference by this article, session binding corresponds to the control within ASI03 that binds delegated OAuth tokens to the right user. The remaining risk is how trustworthy the user that the application passes is. Within the
userId path, AgentCore Identity does not validate that value (see Section 6.3).12. Decisions This Design Leaves to You
This chapter outlines the decisions this design leaves to you.- Whether to implement your own endpoint or use the consent portal. The consent portal is designed for use with the Gateway. For 3LO scenarios that do not pass through the Gateway, you will need your own endpoint.
- Which to pass to
CompleteResourceTokenAuth:userTokenoruserId. The developer guide recommends prioritizing the JWT path if a JWT is available. - Whether to make the application session cookie readable at the session binding URL. The session binding page requires that this URL be able to read the application user's session data.
- What to do when the users do not match: take no action, or log the attempt. If logging, how will you know the originating user (see Section 7.1)?
- Whether to create a
customState, how to create it, and where to validate it. - The method for delivering the authorization URL to the user. Which channel will you use: a chat screen, an IDE, or a messaging system?
- When consent is revoked on the external service, should you initiate a new flow using
forceAuthentication? - If using the consent portal, ensure you provide appropriate names for the target and credential provider that are visible to the user. The consent portal post specifies that the consent portal URL should be sent to the user via an approved communication channel.
13. Failure Modes
This chapter lists potential failure points in the design, along with relevant documentation references.- After consent, the application calls
CompleteResourceTokenAuthwithout performing any checks. The session binding page specifies that before calling this function, the application must verify that the current user has a valid application session (Section 6.2). - The user being passed to
CompleteResourceTokenAuthis retrieved from server-side storage, using the session URI as a key. The two values being compared will always be the same (Section 4.3). - The user's ID is obtained from request parameters or values sent by the client. The workload access token page specifies that this ID should be retrieved from the authenticated principal's context (Section 6.3).
- The callback URL and the session binding URL are mixed up. The OAuth application registration for external services should use the callback URL, while the workload identity or Gateway target should use the session binding URL (Chapter 5).
- When performing local testing with
agentcore dev, the session binding endpoint is not implemented.agentcore devdoes not have a callback endpoint and does not callCompleteResourceTokenAuth(Section 5.2). customStateis used in place of session binding.customStateonly checks that the response matches the request and does not verify who consented (Section 9.2).- A consent portal is created, and the existing targets'
defaultReturnUrlis not modified. Consent is not linked to the consent portal session (Section 8.3). - Because a consent portal is being used, it is assumed that nothing is needed for authorization URLs returned when a target is called directly. The target page states that they are subject to the same session binding requirements (Section 8.4).
- Because of the change on November 13, 2026, it is assumed that providers supporting only OAuth 2.0 can be used as the primary identity provider (IdP) of the consent portal. The prerequisites page states that primary IdPs cannot be providers that do not issue ID tokens (Section 8.5).
- Given that the authorization URL has a validity period of 10 minutes, it is assumed that the risk is minimal even if another person opens it. While 10 minutes narrows the window, it cannot substitute for proper validation (Section 7.2).
14. Frequently Asked Questions About OAuth Session Binding in AgentCore Identity
This chapter concisely addresses six common questions regarding OAuth session binding within AgentCore Identity.Who verifies that the person who consented is the person using the agent?
The application and AgentCore Identity share the work. The Amazon Bedrock AgentCore Identity developer guide specifies that the application checks the user currently signed in to the application at its HTTPS endpoint, to which the user's browser returns after consent. The application then passes the user and the session URI toCompleteResourceTokenAuth. The Gateway MCP target page states that AgentCore Identity verifies whether the user passed to it is the same user who started the flow before exchanging the authorization code for an access token. As an inference by this article, the external service's authorization server does not perform this check.What is the difference between the callback URL and the session binding URL?
The callback URL points to AgentCore Identity, while the session binding URL points to the application's endpoint. AgentCore Identity issues the callback URL when a credential provider is created, and the URL is registered with the external service's OAuth application. Authorization codes are delivered to AgentCore Identity via this URL. The application provides the session binding URL and registers it inallowedResourceOauth2ReturnUrls on the workload identity. In AgentCore Gateway, it is configured on the target as the return URL. After the user provides consent, their browser is redirected to this URL.What should the application do if the users do not match?
Do not callCompleteResourceTokenAuth. The developer guide states that if the users do not match, the application should either do nothing or simply log the attempt. If CompleteResourceTokenAuth is not called, AgentCore Identity will not retrieve or store any tokens. The documentation reviewed did not specify which errors CompleteResourceTokenAuth returns when users do not match.Does the consent portal remove the need for session binding?
No. The consent portal is a mechanism where AWS manages the session binding endpoint for the AgentCore Gateway. When using the consent portal, applications do not need to maintain their own endpoints, and browsers do not hold tokens. However, the developer guide states that an authorization URL returned when a target is called directly is subject to the same session binding requirements as other authorization URLs generated by AgentCore Identity. 3LO that does not go through the gateway is outside the consent portal.Is the OAuth state parameter enough to bind consent to the right user?
It is not enough on its own. According to RFC 6749 and RFC 9700, thestate parameter binds a request to the redirect URI to the browser session that started the request. In AgentCore Identity's 3LO process, the server-side agent code initiates the flow, and what consent must be bound to is the application's user. The developer guide strongly recommends also using customState, which plays the role of state. customState and session binding are not replacements for each other; they should be used together.Which value should the application pass as the user to CompleteResourceTokenAuth?
The application should pass the user taken from the application session in the current browser toCompleteResourceTokenAuth. CompleteResourceTokenAuth accepts either the user's IdP token (userToken) or the user's ID (userId). The developer guide for Amazon Bedrock AgentCore Identity specifies that this value should be retrieved from a valid application session in the browser (e.g., a cookie or browser local storage) and not from a remote session cache. Since userId is a string that AgentCore Identity cannot verify, prioritize using the JWT if one is available.15. Summary
This article showed who verifies, in Amazon Bedrock AgentCore Identity 3LO, that the person who consented and the person using the agent are the same, as a question of where responsibility sits. The authorization URL is a standard URL that anyone can open. As an inference by this article, an external service's authorization server verifies that the person is the owner of an account on that service, but it does not know which user of the agent's application started the request that led to the consent.The mechanism that verifies this is session binding. After consent, AgentCore Identity redirects the user's browser back to the application's session binding URL. The application then extracts the user currently signed in to its own session using that browser and passes this user information, along with the session URI, to
CompleteResourceTokenAuth. AgentCore Identity verifies that the user passed is the same individual who initiated the consent flow before retrieving and storing the token. According to the Gateway MCP target page, AgentCore Identity is responsible for performing this comparison. However, the application determines one of the values being compared. Therefore, this article argues that where the application obtains this value is central to this design.The consent portal, designed for AgentCore Gateway, hosts this endpoint on the AWS side. Browsers do not hold tokens. However, an authorization URL returned when a target is called directly is subject to the same session binding requirements. In OAuth, the
state parameter is a value that binds a request to the browser's session, not a value that binds consent to a user. customState and session binding should be used together. The information presented in this article is current as of November 17, 2026.16. References
- Amazon Bedrock AgentCore Developer Guide: OAuth 2.0 authorization URL session binding
- Amazon Bedrock AgentCore Developer Guide: Configure a consent portal
- Amazon Bedrock AgentCore Developer Guide: Consent portal prerequisites
- Amazon Bedrock AgentCore Developer Guide: Configure a consent portal target
- Amazon Bedrock AgentCore Developer Guide: Consent portal execution role
- Amazon Bedrock AgentCore Developer Guide: MCP servers targets
- Amazon Bedrock AgentCore Developer Guide: Example: Authentication with an authorization code grant when invoking a gateway
- Amazon Bedrock AgentCore Developer Guide: Get workload access token
- Amazon Bedrock AgentCore Developer Guide: Security best practices for AgentCore Runtime
- Amazon Bedrock AgentCore API Reference: GetResourceOauth2Token
- Amazon Bedrock AgentCore API Reference: CompleteResourceTokenAuth
- Amazon Bedrock AgentCore API Reference: UserIdentifier
- What's New: Amazon Bedrock AgentCore Identity now offers a managed consent portal
- What's New: Amazon Bedrock AgentCore Identity now supports OAuth 2.0 discovery URLs
- AWS Machine Learning Blog: Connecting MCP servers to Amazon Bedrock AgentCore Gateway using Authorization Code flow
- AWS Machine Learning Blog: Secure AI agents with Amazon Bedrock AgentCore Identity on Amazon ECS
- AWS Machine Learning Blog: Manage end-user OAuth consent for AI agents with Amazon Bedrock AgentCore
- RFC Editor: RFC 6749 - The OAuth 2.0 Authorization Framework
- RFC Editor: RFC 9700 - Best Current Practice for OAuth 2.0 Security
- Model Context Protocol Specification (version 2026-07-28): Elicitation
References:
Tech Blog with curated related content
Written by Hidekazu Konishi