feat(agentcore): add identity L2 constructs

[krokoko]

Issue # (if applicable)

Add L2 CDK constructs for:

• https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrockagentcore-oauth2credentialprovider.html
• https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrockagentcore-apikeycredentialprovider.html
• https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrockagentcore-workloadidentity.html

to the agentcore package. Update also the gateway construct to support the credentials providers when configuring outbound auth for a target

Reason for this change

Feature gap

Description of changes

• Updated the existing gateway construct
• Added a new folder with the new L2 constructs for identity
• BREAKING CHANGE: ICredentialProviderConfig.grantNeededPermissionsToRole parameter renamed from role (IRole) to gateway (IGateway) so the implementation can derive scoped resource ARNs (e.g. workload identity wildcards keyed on gateway name) and attach policies to the gateway's execution role in a single call, rather than requiring callers to pass both separately.

Describe any new or updated permissions being added

Exposed the permissions specific to the identity providers

Description of how you validated changes

• added unit tests
• added integration tests
• deployed couple of examples:

Examples:

1. Created a cdk stack linking against the custom package

With:

const apiKeyProvider = new agentcore.ApiKeyCredentialProvider(this, 'ApiKeyIdentityTestScoped', {
      apiKeyCredentialProviderName: 'test-scoped-api-key-provider',
      apiKey: cdk.SecretValue.unsafePlainText('integ-placeholder-api-key'),
      tags: { integ: 'gateway-identity-outbound' },
    });

    const oauthProvider = agentcore.OAuth2CredentialProvider.usingGithub(this, 'OAuthIdentityTestScoped', {
      oAuth2CredentialProviderName: 'test-scoped-oauth-provider',
      clientId: 'integ-github-client-id',
      clientSecret: cdk.SecretValue.unsafePlainText('integ-github-client-secret'),
      tags: { integ: 'gateway-identity-outbound' },
    });

    const workloadIdentity = new agentcore.WorkloadIdentity(this, 'WorkloadIdentityTestScoped', {
      workloadIdentityName: 'test-scoped-workload-identity',
      tags: { integ: 'workload-identity-outbound' },
    });

The following resources are deployed:

2. Creating a workload identity

new agentcore.WorkloadIdentity(this, 'WorkloadIdentity', {
      workloadIdentityName: 'integ-workload-identity-outbound',
      tags: { integ: 'workload-identity-outbound' },
    });

3. Deploying a gateway with target

const gateway = new agentcore.Gateway(this, 'Gateway', {
      gatewayName: 'integ-gateway-identity-outbound',
      description: 'Gateway with OpenAPI targets wired to Token Vault L2 identities',
      // Inbound IAM avoids default Cognito domain (global uniqueness); this integ focuses on outbound Token Vault auth.
      authorizerConfiguration: agentcore.GatewayAuthorizer.usingAwsIam(),
    });

    const openApiSchema = agentcore.ApiSchema.fromInline(
      JSON.stringify({
        openapi: '3.0.0',
        info: { title: 'GatewayIdentityOutboundInteg', version: '1.0.0' },
        servers: [{ url: 'https://example.com' }],
        paths: {
          '/ping': {
            get: {
              operationId: 'ping',
              responses: { 200: { description: 'ok' } },
            },
          },
        },
      }),
    );

    const apiKeyProvider = new agentcore.ApiKeyCredentialProvider(this, 'ApiKeyIdentity', {
      apiKeyCredentialProviderName: 'integ-gw-outbound-apikey',
      apiKey: cdk.SecretValue.unsafePlainText('integ-placeholder-api-key'),
      tags: { integ: 'gateway-identity-outbound' },
    });

    gateway.addOpenApiTarget('OpenApiApiKeyTarget', {
      gatewayTargetName: 'integ-openapi-api-key',
      description: 'OpenAPI target with API key Token Vault identity',
      apiSchema: openApiSchema,
      credentialProviderConfigurations: [agentcore.GatewayCredentialProvider.fromApiKeyIdentity(apiKeyProvider)],
    });

Deploys correctly

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

---

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results	144 ran	144 passed

Test	Result
No test annotations available

• View Security Guardian Results

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

---

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results with resolved templates	144 ran	144 passed

Test	Result
No test annotations available

• View Security Guardian Results with resolved templates

[aws-cdk-automation]

This PR cannot be merged because it has conflicts. Please resolve them. The PR will be considered stale and closed if it remains in an unmergeable state.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-05-06 10:27 UTC · Rule: default-squash
• 🚫 Left the queue — 2026-05-06 10:54 UTC · at a8fe50443cf7b5ff34aab3d20e0bcaa5a5eb4da7

This pull request spent 26 minutes 41 seconds in the queue, with no time running CI.

Reason

The pull request can't be updated

For security reasons, Mergify can't update this pull request. Try updating locally.
GitHub response: refusing to allow a GitHub App to create or update workflow .github/workflows/pr-issue-check.yml without workflows permission

Hint

You should update or rebase your pull request manually. If you do, this pull request will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

Pull request has been modified.

[alvazjor]

@Mergifyio queue

[mergify]

Merge Queue Status

🛑 Queue command has been cancelled

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[alvazjor]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-05-07 16:19 UTC · Rule: priority-squash
• ✅ Checks skipped · PR is already up-to-date
• ✅ Merged — 2026-05-07 16:19 UTC · at 732a5084cfed751003f91d0f24ab59e68237cd42 · squash

This pull request spent 27 seconds in the queue, including 3 seconds running CI.

Required conditions to merge

• #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  • feat(agentcore): add identity L2 constructs #37610
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • feat(agentcore): add identity L2 constructs #37610
• any of [🛡 GitHub branch protection]:
  • check-success = validate-pr
  • check-neutral = validate-pr
  • check-skipped = validate-pr
• any of [🛡 GitHub branch protection]:
  • check-success = build
  • check-neutral = build
  • check-skipped = build

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.