awslabs / awslabs/agentcore-samples
Add Private VPC Keycloak IdP sample with privateEndpoint for Runtime and Gateway
- Dominant language
- Python
- Stars
- 3.4k
- Forks
- 1.3k
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 30
Description
Proposal
Add two tutorials demonstrating inbound JWT authorization from a private VPC-hosted Keycloak instance using the new privateEndpoint feature (VPC Lattice managed connectivity, launched April 2026).
This fills a gap in the current identity samples — all existing inbound auth examples use publicly accessible IdPs (Cognito, Entra ID). Many enterprise customers run private IdPs (Keycloak, PingFederate) inside their VPC that are not internet-accessible.
Proposed Samples
- 13-Private-IdP-Keycloak-Runtime
- Private Keycloak → privateEndpoint → AgentCore Runtime
- Inbound JWT auth for agent invocations
- Demonstrates customJWTAuthorizer with managedVpcResource
- 14-Private-IdP-Keycloak-Gateway
- Private Keycloak → privateEndpoint → AgentCore Gateway
- Inbound JWT auth for MCP tool calls
- Includes Lambda-backed gateway target with tool schema
- shared-keycloak-infra/
- CloudFormation template: EC2 (Keycloak 26) + internal ALB + ACM cert + Route53
- Python setup script: configures realm + client via Keycloak Admin REST API
Architecture
`Caller → Get JWT from private Keycloak → Call AgentCore Runtime/Gateway with Bearer token → AgentCore Identity validates JWT via: VPC Lattice → Internal ALB (ACM cert) → Keycloak JWKS endpoint`
Key Features Demonstrated
- privateEndpoint.managedVpcResource configuration
- Internal ALB with ACM certificate (publicly trusted cert, private network)
- Keycloak client_credentials grant
- allowedClients / allowedAudience configuration
- Lambda gateway target with inline tool schema
Related
- PR #1436 (Entra ID OBO tutorial) — similar structure, different IdP
- Connect to private identity providers docs: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-private-idp.html
Validated
- End-to-end tested in a live AWS account with Keycloak 26, VPC Lattice, and both Runtime and Gateway in READY state with successful tools/list and tools/call invocations.
Contributor guide
Research direction
Start by comparing the existing identity samples with the proposed 13-Private-IdP-Keycloak-Runtime and 14-Private-IdP-Keycloak-Gateway tutorials. Read the shared-keycloak-infra CloudFormation template and Python setup script, then follow the privateEndpoint, managedVpcResource, customJWTAuthorizer, and Lambda gateway configuration. Done means both samples validate JWTs through private Keycloak and successfully support the described Runtime and Gateway calls.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, python
- Domain
- authentication, cloud, infrastructure
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100