awslabs / awslabs/agentcore-samples
Sample: managed consent dashboard for gateway targets using the authorization code flow
- Dominant language
- Python
- Stars
- 3.4k
- Forks
- 1.3k
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 30
Description
AgentCore offers a **managed consent dashboard** (consent portal): an AWS-hosted page where each end user connects their own third-party account before an agent acts on their behalf.
A deployed agent cannot complete an OAuth 2.0 authorization code flow (3LO) by itself — that flow needs a browser, a consent screen, and somewhere to receive the redirect. The consent portal supplies all three, which makes it the missing piece for any gateway target whose outbound auth is `AUTHORIZATION_CODE`.
### Proposal
Add `01-features/05-authenticate-and-authorize/07-consent-portal-auth-code-flow-targets/` — a complete, deployable path from a signed-in end user to a third-party API called with that user’s own authorization:
```
user -> FastAPI BFF -> Strands agent on AgentCore Runtime -> AgentCore Gateway
-> GitHub MCP server (AUTHORIZATION_CODE target)
```
- Users grant GitHub access on the consent portal, **out of band**; the agent never handles a GitHub credential, and there is no consent UI or callback server to write.
- **Entra ID and Okta** both supported from one deploy path, selected by a required `--entra` / `--okta` profile flag.
- **Passthrough** on the agent→gateway hop (runtime and gateway share issuer and audience), keeping the sample focused on consent rather than token exchange. Deliberately not an OBO sample.
- Schema-upfront MCP target, so `tools/list` works before consent and only `tools/call` needs the user token.
- Graceful unconsented path: the gateway returns a `-32042` URL-mode elicitation, and the agent turns it into a plain instruction naming the portal.
- Optional Lambda RESPONSE interceptor for adopters who want every MCP client steered to the portal rather than relying on agent-side handling.
- Idempotent numbered deploy scripts and a teardown that verifies what it deleted.
### Why it warrants its own sample
The API calls are straightforward; the difficulty is in invariants that fail late and quietly. Three callback URLs that are not interchangeable. A gateway authorizer and a portal IdP provider that must reference byte-identical discovery URLs. Entra’s pairwise `sub`, which forces both sign-ins to share one audience. Okta needing a custom authorization server. Each is documented alongside the symptom it produces, so the sample doubles as a troubleshooting reference.
Happy to take review feedback on scope or placement.
Contributor guide
Research direction
Start with the proposed 01-features/05-authenticate-and-authorize/07-consent-portal-auth-code-flow-targets/ path and trace the FastAPI BFF, Strands agent, AgentCore Runtime, and AgentCore Gateway flow. Review the deploy scripts, teardown verification, and Entra ID/Okta profiles first. Done means a deployable sample supports both profiles, handles consent and the unconsented -32042 path, and verifies cleanup.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, fastapi, github, python
- Domain
- api, authentication, backend, cloud
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100