AgentCore Identity's Consent Portal: How AWS Manages OAuth Delegation When Agents Act on Behalf of Users

AWS just shipped a managed consent portal for AgentCore Gateway. The feature solves a hard problem: when an agent needs to act on behalf of an end user (filing a GitHub issue, posting to Slack), you need three-legged OAuth (3LO), session binding, and an audit trail. Most teams build this once, badly, then maintain it forever. AWS is offering it as managed infrastructure.

This matters because multi-tenant agent platforms need user delegation at scale. The alternative is storing long-lived tokens in your own database, rotating them manually, and hoping your session management doesn't leak credentials across users.

What AgentCore Identity's Consent Portal Does

The consent portal is a managed web experience that handles OAuth flows for agents. When an agent needs to call an external API on behalf of a user, the portal:

• Redirects the user to the third-party OAuth provider (GitHub, Slack, etc.)
• Captures the authorization code after user consent
• Exchanges the code for an access token
• Binds that token to a specific agent session via a session binding endpoint
• Returns control to the agent with a scoped credential

The key primitive is session binding. The portal ties each OAuth token to a specific agent execution context. When the agent makes subsequent API calls, AgentCore Gateway injects the correct token based on session identity. The agent never sees the raw token.

Architecture: Session Binding and 3LO Target Configuration

AgentCore Identity introduces two new resources:

1. Consent portal: A managed web UI with a unique URL per AWS account. You configure branding, redirect URIs, and supported OAuth providers.
2. 3LO targets: Configuration objects that define how to connect to each external service (client ID, client secret, scopes, authorization endpoint, token endpoint).

When you provision a 3LO target, you register it with the consent portal. The portal uses this configuration to orchestrate the OAuth flow. Each target maps to one external service. If you need GitHub and Slack, you create two 3LO targets.

Session binding happens at the AgentCore Gateway layer. When an agent invokes a tool that requires user credentials, the gateway checks for a bound session. If none exists, it redirects the user to the consent portal. After consent, the gateway stores the token in a session-scoped credential store. Subsequent tool calls within the same session reuse the token without re-prompting.

Flow Diagram

User invokes agent
  ↓
Agent calls tool requiring OAuth (e.g., "create GitHub issue")
  ↓
Gateway checks session for bound token
  ↓
No token found → redirect to consent portal
  ↓
User authenticates with GitHub
  ↓
GitHub returns authorization code to portal
  ↓
Portal exchanges code for access token
  ↓
Portal binds token to session ID
  ↓
Gateway injects token into tool call
  ↓
Tool executes with user's delegated authority

The session binding endpoint is a REST API. You can call it directly if you're building a custom consent flow, but most teams will use the managed portal.

Configuration Example: GitHub 3LO Target

Here's what a 3LO target configuration looks like for GitHub:

{
  "targetName": "github-integration",
  "authorizationEndpoint": "https://github.com/login/oauth/authorize",
  "tokenEndpoint": "https://github.com/login/oauth/access_token",
  "clientId": "Iv1.abc123def456",
  "clientSecret": "stored-in-secrets-manager-arn",
  "scopes": ["repo", "user"],
  "redirectUri": "https://consent-portal.agentcore.aws.amazon.com/callback"
}

The clientSecret is stored in AWS Secrets Manager. AgentCore Gateway fetches it at runtime. You never pass secrets through the API.

The scopes array defines what permissions the agent requests. GitHub's OAuth flow shows these to the user during consent. If you request repo and user, the user sees "This agent wants to access your repositories and profile."

CloudTrail Audit Trails for Delegated Actions

Every action an agent takes under delegated authority generates a CloudTrail event. The event includes:

• Session ID
• User identity (IAM principal or federated identity)
• Agent ID
• Tool name
• External API endpoint called
• Timestamp

This gives you a complete audit trail. If an agent files a GitHub issue on behalf of a user, you can trace the action back to the specific user session, the agent that executed it, and the OAuth token used.

CloudTrail events use the agentcore.amazonaws.com event source. You can filter by eventName to find consent grants (GrantConsent), token exchanges (ExchangeToken), and tool invocations (InvokeTool).

Example CloudTrail Event

{
  "eventVersion": "1.08",
  "eventTime": "2026-09-14T20:45:12Z",
  "eventSource": "agentcore.amazonaws.com",
  "eventName": "InvokeTool",
  "userIdentity": {
    "type": "AssumedRole",
    "principalId": "AIDAI23EXAMPLE",
    "arn": "arn:aws:sts::123456789012:assumed-role/AgentExecutionRole/session-abc123"
  },
  "requestParameters": {
    "agentId": "agent-xyz789",
    "toolName": "create-github-issue",
    "sessionId": "session-abc123",
    "targetName": "github-integration"
  },
  "responseElements": {
    "statusCode": 201,
    "externalApiEndpoint": "https://api.github.com/repos/owner/repo/issues"
  }
}

You can pipe these events to EventBridge for real-time alerting or to S3 for long-term compliance storage.

Security Boundaries and Token Isolation

The session binding model enforces strict token isolation. Each session gets its own credential store. If two users invoke the same agent concurrently, their OAuth tokens never mix.

AgentCore Gateway uses session IDs as the isolation boundary. Session IDs are opaque UUIDs generated by the gateway. They're tied to the user's IAM identity or federated identity. If a user's IAM session expires, the agent session expires too.

Tokens are stored encrypted at rest in DynamoDB. The encryption key is managed by AWS KMS. You can bring your own KMS key if you need customer-managed encryption.

Token refresh happens automatically. If a 3LO target supports refresh tokens, AgentCore Gateway refreshes expired access tokens without re-prompting the user. The refresh logic runs in the background. Agents see no interruption.

Trade-offs: Managed vs. Custom Consent Flows

Dimension	Managed Consent Portal	Custom Consent Flow
Time to ship	Minutes (provision portal, configure 3LO targets)	Weeks (build OAuth flow, session management, token storage)
Token storage	Encrypted DynamoDB managed by AWS	Your database, your encryption, your key rotation
Audit trail	CloudTrail events out of the box	Custom logging, custom compliance mapping
Session binding	Automatic via gateway	Manual correlation between user sessions and agent executions
Token refresh	Automatic for refresh-enabled 3LO targets	Manual refresh logic, manual error handling
Branding	Limited (logo, colors via portal config)	Full control over consent UI
Multi-region	Portal is regional, must provision per region	Deploy wherever you want

The managed portal trades customization for speed. If you need a fully branded consent experience or want to run OAuth flows outside AWS, you'll build custom. If you want to ship fast and offload token lifecycle management, the managed portal is faster.

Failure Modes and Observability

Three common failure modes:

1. User denies consent: The agent receives a ConsentDenied error. You need to handle this gracefully in your agent logic. Most teams show a message like "I need permission to access GitHub. Please grant consent and try again."

2. Token expires mid-execution: If the agent is long-running and the access token expires, the gateway attempts a refresh. If refresh fails (user revoked access, refresh token expired), the agent gets a TokenExpired error. You need retry logic or a fallback to re-prompt for consent.

3. 3LO target misconfiguration: If the client ID, client secret, or redirect URI is wrong, the OAuth flow fails at the provider level. The user sees a generic error from GitHub or Slack. CloudTrail logs the failure with eventName: OAuthFlowFailed. Check your 3LO target config.

AgentCore Gateway exposes metrics in CloudWatch:

• ConsentGranted: Count of successful consent flows
• TokenExchangeFailed: Count of failed token exchanges
• ToolInvocationWithDelegatedAuth: Count of tool calls using delegated tokens
• SessionBindingErrors: Count of session binding failures

Set alarms on TokenExchangeFailed and SessionBindingErrors. These indicate configuration problems or provider outages.

When to Use the Managed Consent Portal

Use it if:

• You're building a multi-tenant agent platform and need user delegation at scale
• You want to offload OAuth flow implementation and token lifecycle management
• You need CloudTrail audit trails for compliance (SOC 2, HIPAA, etc.)
• You're okay with AWS-managed token storage and encryption

Avoid it if:

• You need full control over the consent UI (branding, custom flows, A/B testing)
• You're running agents outside AWS and can't route traffic through AgentCore Gateway
• You need to support OAuth providers that aren't GitHub or Slack (AWS will add more, but the list is short today)
• You have existing OAuth infrastructure and don't want to migrate

Technical Verdict

The managed consent portal is infrastructure you don't want to build. OAuth delegation for agents is hard: session binding, token refresh, audit trails, and multi-tenant isolation are all sharp edges. AWS is offering a managed solution that handles the plumbing.

The trade-off is flexibility. You get limited branding, a fixed set of supported providers, and regional deployment constraints. If you need custom consent flows or exotic OAuth providers, you'll build your own. But for most teams shipping agent platforms, the managed portal is faster and safer than rolling your own.

The CloudTrail integration is the killer feature. Compliance teams need audit trails for delegated actions. The managed portal gives you that out of the box. If you're building in a regulated industry, this alone justifies using the managed solution.

Source Links

• AWS Blog: Manage end-user OAuth consent for AI agents with Amazon Bedrock AgentCore

Comments

[Jo Do]

Session binding solves token selection, but it should not be treated as standing permission for every later tool call. The bound credential needs to travel with the grant's audience, purpose, scopes, expiry, and the user-visible action that was approved. Otherwise the system can choose the correct user's token and still use it for the wrong repository, channel, or intent.