Manage end-user OAuth consent for AI agents with Amazon Bedrock AgentCore

Artificial Intelligence #

AI agents often need to access services such as GitHub and Slack on a user’s behalf. Before an agent can act, the user must authenticate with the provider and explicitly approve the requested access. The application must then securely associate the resulting OAuth grant with the user who authorized it. This process is called session binding.

Previously, customers using the AgentCore Identity (a capability of Amazon Bedrock AgentCore) three-legged OAuth (3LO) flow (also known as OAuth 2.0 authorization code flow) had to build and host their own session binding infrastructure. This included presenting the authorization URL, hosting a public HTTPS callback, authenticating the returning user, managing browser sessions, and calling CompleteResourceTokenAuth to complete the flow.

AgentCore Identity now offers a Consent portal, a managed web experience and session binding endpoint for AgentCore Gateway, a capability of Amazon Bedrock AgentCore. You create a portal for a gateway and share its URL with your users. Users authenticate with your organization’s identity provider (IdP), review the services available to the agent, and grant consent to individual providers. The portal handles the browser redirects and session binding, while AgentCore Identity stores the resulting tokens in its token vault.

This capability is particularly useful for agents accessed through IDE and Model Context Protocol (MCP) clients such as Kiro, Claude Code, Cursor, and Visual Studio Code. Users can grant consent before invoking a tool, and subsequent tool calls can use the token already stored for that user. In this post, we use a software development assistant as an example. We walk through the administrator and end-user experiences on the AWS Management Console and browser, and show how to review the resulting activity in AWS CloudTrail.

Example scenario: Give a development assistant access to GitHub #

Consider a company named Example Corp that provides its developers with an AI coding assistant through an AgentCore Gateway. The assistant has two targets:

• A GitHub target that can list repositories and create issues.
• A Slack target that can list public channels and post messages.

Example Corp uses its corporate IdP to authenticate employees. The administrator wants each GitHub and Slack OAuth grant to remain associated with the employee who approved it. Developers can connect either provider independently and return to their IDE without repeated prompts.

The walkthrough follows these two roles:

• Administrator: Configures the corporate IdP, GitHub and Slack gateway targets, execution role, and Consent portal, and then sends the portal URL to developers.
• End user: Opens the URL, signs in with the corporate IdP, connects GitHub when needed, and can grant Slack access separately.

Prerequisites #

Before starting the walkthrough, Example Corp needs:

• An AWS account with access to Amazon Bedrock AgentCore .
• An AgentCore Gateway configured withJWT inbound authorization .
• An IDE or MCP client configured to connect to the same AgentCore Gateway that will be attached to the Consent portal.
• Administrative access to the corporate IdP.
• A registered GitHub OAuth App andSlack app for a development or test workspace.
• Permission to register the AgentCore Identity callback URL in each provider application.

Getting started #

The following steps show what the Example Corp administrator configures and what a developer experiences after receiving the portal URL.

Steps for administrator

The administrator completes Steps 1–6 to configure the identity provider, gateway targets, execution role, and Consent portal.

Step 1: Prepare the corporate IdP and gateway connections

Administrator IAM policy

Attach this policy to the administrator identity that performs Steps 1–3. Replace the account ID.

The AWS Identity and Access Management (IAM) statement covers the Create default role option on the console, which creates a service role named AmazonBedrockAgentCoreConsentPortalDefaultServiceRole-<suffix>. If you supply your own role instead, scope iam:PassRole to that role ARN.

Step 2: Configure the corporate IdP application

1. In the corporate IdP, create an OpenID Connect (OIDC) web application for the Consent portal.
2. Enable the authorization code grant and generate a client ID and client secret.
3. Configure the login scopes, at minimum openid .
4. Record the OpenID Connect (OIDC) discovery URL. The portal uses the authorization endpoint, token endpoint, and signing keys from this document.
5. Add a temporary callback URL. You replace it in Step 6, after the portal URL exists.

The IdP must issue a JSON Web Token (JWT) access token that the portal can validate. For example, with Okta, use a custom authorization server with an access policy that permits the application and the authorization code grant. With Auth0, configure an audience when needed so the IdP returns a signed JWT access token instead of an opaque token.

Step 3: Create the IdP credential provider

The portal reads the IdP client ID and client secret from an OAuth2 credential provider.

1. Open the Amazon Bedrock AgentCore console.
2. Under Build , chooseIdentity .
3. In Outbound Auth , chooseAdd Outbound Auth , and then chooseAdd OAuth client .
4. Enter a name, such as gateway-demo-idp .
5. Enter the client ID and client secret from the corporate IdP application, and provide the OIDC discovery configuration.
6. Choose Add OAuth client .

Step 4: Verify outbound prerequisites

Before creating the Consent portal, confirm:

• The GitHub and Slack OAuth applications are registered, and their client secrets are stored in AWS Secrets Manager.
• AgentCore Identity has separate outbound OAuth credential providers for GitHub and Slack, and each generated callback URL is registered with the matching provider application.
• The GitHub and Slack gateway targets use the authorization code grant, request only the required scopes, and have a Ready status.
• The Consent portal execution role selected in Step 5 can read any customer-managed secrets referenced by the outbound credential providers.

After the portal URL is assigned, configure each target’s default return URL in Step 6.

Step 5: Create the Consent portal

On the Identity page, the Consent portals section lists the portals in the account and AWS Region.

1. In Consent portals , chooseCreate portal .
2. Under Consent portal details , forName , enter a name such asconsent-portal-heqk0 . Names accept 1–50 characters, using letters, numbers, hyphens, and underscores.
3. Optionally enter a Description of up to 512 characters.
4. For Gateway , select the development assistant’s gateway. The gateway name is visible to end users in the Consent portal, so choose a clear, recognizable name. One Consent portal is allowed per gateway, and the gateway can’t be changed after creation.
5. Under IdP credential configurations , forIdP Credential Provider , select the OAuth2 credential provider created in Step 3.
6. Under Scopes , keep the requiredopenid scope. Additional scopes are optional. ChooseAdd scope only when your IdP or application requires them.
7. For Audience – optional , keepNone unless your gateway specifies audiences. The value is validated against the audiences configured on the AgentCore Gateway.
8. Expand Permissions . ForIAM permissions , chooseCreate default role to have the console create a service role with the required permissions, or chooseUse another role to select an existing role.
9. Choose Create portal .

When provisioning finishes, the status changes to Active, the Consent portal URL appears, and a Launch Consent portal button opens it in a new tab. The URL follows the pattern https://<gateway-name>.consent-portal.bedrock-agentcore.<region>.amazonaws.com.

Step 6: Register callback URLs and send the portal URL

1. Copy the consent portal URL from the portal details page.
2. In the corporate IdP application, for example, Amazon Cognito, Okta, or Auth0, replace the temporary callback with <portal-url>/callback . Don’t add a trailing slash. This isn’t the GitHub or Slack application callback. Those applications use the unique AgentCore IdentitycallbackUrl .
3. For each 3LO gateway target, set the default return URL to <portal-url>/connect/callback .
4. Confirm that each outbound provider application contains the AgentCore Identity callback URL returned when its OAuth credential provider was created.
5. Test the portal URL in a browser.
6. Send the portal URL to the development team through an approved communication channel.

Callback URL reference

| URL | Where it is configured | Purpose | | <portal-url>/callback | Corporate IdP application | Returns the user after portal login | | <portal-url>/connect/callback | Gateway target as the default return URL | Returns the user to the managed session binding endpoint | | AgentCore Identity callbackUrl | Outbound provider application | Sends the provider’s authorization code to AgentCore Identity |

After completing the provider callbacks and gateway targets, verify the final administrator configuration before sharing the portal URL.

Steps for end user

The end user completes Step 7 to sign in and connect providers after receiving the portal URL.

Step 7: Sign in and connect providers

1. Open the portal URL in a browser.
2. Choose Sign in . The browser redirects to the Example Corp IdP.
3. Authenticate with the corporate identity. The portal then uses its IAM execution role to retrieve the gateway’s configured targets and their connection state.
4. On the Connections page, review the GitHub and Slack OAuth clients and their target status.
5. Choose Connect for GitHub.
6. Review the scopes on GitHub’s consent page and approve access.
7. After the browser returns to the portal, verify that GitHub shows Connected while Slack remainsNot connected . This demonstrates that grants are independent for each provider.
8. If the agent needs Slack, choose Connect for Slack, select the workspace, review the requested permissions, and approve the app. Otherwise, leave Slack unconnected until it is needed.
9. Return to the IDE or MCP client configured to use the same AgentCore Gateway attached to the Consent portal, and retry the applicable GitHub or Slack tool call through that gateway.

The following screenshots capture useful checkpoints for the walkthrough.

Behind the scenes #

1. The portal validates the IdP response and establishes an encrypted browser session.
2. The portal uses its execution role to list the attached gateway’s 3LO targets.
3. When the user chooses Connect , the portal callsGetResourceOauth2Token and receives an authorization URL and session URI.
4. After the provider returns the authorization code to AgentCore Identity, the browser returns to the portal’s managed session binding endpoint.
5. The portal calls CompleteResourceTokenAuth with the authenticated user context.
6. When the provider returns a refresh token, AgentCore Identity stores it and automatically uses it to obtain a new access token after the current access token expires. Sometimes no valid refresh token is available, because the provider didn’t issue one or it has expired or been revoked. In that case, the user must return to the Consent portal and reauthorize when the access token can no longer be used. Configure the provider to issue refresh tokens where supported. For example, enable user-to-server token expiration for GitHub or token rotation for Slack.

The next time the developer opens the portal, connected providers remain visible. The developer doesn’t need to approve a provider again unless the grant is revoked, expires, or requires renewed consent. The developer can also choose Disconnect and later connect the provider again.

Review consent activity in AWS CloudTrail #

Amazon Bedrock AgentCore records consent operations in AWS CloudTrail. In CloudTrail event history, filter Event source by bedrock-agentcore.amazonaws.com, then review:

• GetResourceOauth2Token when the portal starts OAuth authorization for a provider.
• CompleteResourceTokenAuth when session binding is completed.
• GetWorkloadAccessTokenForJWT when the portal obtains gateway access for the authenticated user.

A GetResourceOauth2Token event identifies the credential provider, requested scopes, OAuth flow, portal execution role, and Region. Sensitive token and state values are redacted.

For failures, use errorCode and errorMessage with the event time, assumed role, Region, credential provider, and requested scopes to identify the cause.

Clean up #

When you no longer need the resources:

1. Open the Amazon Bedrock AgentCore console and delete the Consent portal.
2. Remove the portal callback URLs from the corporate IdP application and gateway targets.
3. Delete the gateway targets that reference the outbound credential providers.
4. Delete the outbound OAuth credential providers and corporate IdP credential provider if they aren’t used elsewhere.
5. Delete the portal execution role if no other resource uses it.

Note: Delete the gateway target before deleting its outbound credential provider. A credential provider still referenced by a target can’t be deleted.

Conclusion #

The Amazon Bedrock AgentCore Consent portal gives administrators a managed way to configure end-user OAuth consent for an AgentCore Gateway. Administrators connect the corporate IdP, execution role, gateway, and outbound providers, and then share one URL. End users authenticate, review available providers, and grant consent individually. The portal handles the browser flow and managed session binding, while AgentCore Identity protects the resulting user tokens in the token vault.

For end-to-end examples using Microsoft Entra ID and Okta, see the following Amazon Bedrock AgentCore samples on GitHub:

- [Consent portal with authorization code flow targets](https://github.com/awslabs/agentcore-samples/tree/main/01-features/05-authenticate-and-authorize/07-consent-portal-auth-code-flow-targets)

• AgentCore Gateway target using the OAuth authorization code flow

To learn more, see Amazon Bedrock AgentCore.

source & further reading

aws.amazon.com — original article How Ninth Wave built AI-powered open finance onboarding on Amazon Bedrock AWS Weekly Roundup: OpenAI GPT-6 Astra on Amazon Bedrock, Amazon Quick desktop GA, Kiro for students, and more (September 14, 2026) The generative AI customization spectrum: From prompt engineering to custom models on AWS