awslabs / awslabs/agentcore-samples

Add Private VPC Keycloak IdP sample with privateEndpoint for Runtime and Gateway

Open
#1,447 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.