docs(identity): worked identity/auth examples + pluggable-auth ADR-016

[theagenticguy]

Summary

Draft for review. Opened as a draft for @theagenticguy to review before it goes ready. Drafted by Bonk.

Two documentation artifacts on identity and authentication, docs + design only:

1. docs/design/IDENTITY_AND_AUTH.md — worked examples that map ABCA's integration shapes onto the Amazon Bedrock AgentCore Identity primitives (workload identity, the token vault, the three outbound flows). Five worked use-cases, each with the wire-level flow:

   • A — user-initiated 3LO (GitHub PR assistant), USER_FEDERATION.
   • B — M2M scheduled job with no user, client_credentials under a manual workload identity.
   • C — OBO token exchange (Microsoft Graph), ON_BEHALF_OF_TOKEN_EXCHANGE, with the RFC 8693 vs RFC 7523 mapping and the delegation-vs-impersonation act-claim point.
   • D — ticket-label → async agent (Jira/Atlassian), with the principal-per-hop table, the "webhook authenticates the tenant, not the user" caveat, and the InvokeAgentRuntimeForUser IAM gate. This is the generalized shape of the GitHub-issue-label trigger discussed in the team channel.
   • E — raw boto3 without the @requires_access_token helper (ECS Fargate vs AgentCore Runtime, side by side).
   • Plus the Linear before/after, the seams table, the gotchas, the pricing surface, and the decision tree.

2. docs/decisions/ADR-016-pluggable-identity-and-auth.md — the two-seam pluggable-auth decision: an OIDC-inbound descriptor (swap Cognito for Okta / Entra / Keycloak without handler changes) and an OAuth2-outbound resolver (unify the per-integration token resolvers behind one contract that selects USER_FEDERATION / M2M / OBO). AgentCore Identity sits behind the seam as one implementation, not the only path.

The ADR records the decision behind RFC #249. It is the credential-plane analog of ADR-014's provider-neutral VcsProvider seam.

In scope (this PR)

• The worked-examples design doc and ADR-016, plus their generated Astro mirror pages (yarn run sync) and a one-line Architecture sidebar entry.
• A cross-reference from SECURITY.md (the shared-PAT limitation) to the new design doc and ADR.

Out of scope (follow-up on #249)

• The descriptor and resolver implementation code.
• The RFC-249 Phase-0 spike script (re-validate USER_FEDERATION / OBO against the live service, record go/no-go).
• Trace/log attribution mechanics (owned by feat(observability): end-to-end task attribution and cross-plane trace correlation #245) and Bedrock billing attribution (feat: Bedrock cost attribution — session tags, request metadata, and operator FinOps guidance #215).

No live AWS / GitHub / Cognito provisioning happens here — this is documentation.

Notes for review

• ADR number: chosen as 016 because ADR-015 is claimed by the open Jira PR feat(jira): Jira Cloud integration -- parity with Linear (#288) #302. Numbers are never reused (per docs/decisions/README.md); if a lower number frees before merge, renumber and coordinate with feat(jira): Jira Cloud integration -- parity with Linear (#288) #302 and the governance: define security & quality finding triage process (candidate ADR-014); #276 = first CodeQL instance #277 ADR-014 governance discussion.
• Linear vendor fact, verified: there is no built-in LinearOauth2 in the credentialProviderVendor enum (checked against the bedrock-agentcore-control service model, API version 2023-06-05, and the public CreateOauth2CredentialProvider API reference — zero drift across all 25 enum values). Linear is wired as CustomOauth2, matching the actor=app flow the shipped linear-oauth-resolver.ts already runs.
• The Astro mirror pages are committed because docs.yml runs yarn run build (= npm run sync && astro build), and the sidebar entry needs its generated page to pass astro check.

Refs #249, #245, #215, #237. Related: PR #302 (Jira), ADR-014.