Add IAP authentication design decision document

[jimdaga]

Summary

• Adds IAP (Identity-Aware Proxy) authentication design decision document covering multi-project OAuth architecture for GCP HCP

Context

This PR recreates the content from the original PR openshift-online/gcp-hcp#58, which was lost when the repository was converted from private to public. The original branch and file content have been preserved from the archived repo.

Jira: GCP-138

Test plan

• Verify design-decisions/iap-authentication.md renders correctly
• Confirm file content matches the original PR

🤖 Generated with Claude Code

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jimdaga

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [jimdaga]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

 _______________________________________________________________
< Making your code shine like the top of the Chrysler Building. >
 ---------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

_{✏️ Tip: You can disable in-progress messages and the fortune message in your review settings.}

Walkthrough

A new design decision document is added that outlines the strategy for protecting internal tooling using Google Cloud Identity-Aware Proxy (IAP) with OAuth authentication, TLS certification, JWT validation, and IAM-based access control across multiple environments and services.

Changes

Cohort / File(s)	Summary
IAP Authentication Design Decision design-decisions/iap-authentication.md	New design decision document covering IAP authentication architecture, including OAuth brand strategy, certificate management via shared gateway, JWT validation approach, credential distribution, secret rotation plan, deployment patterns with ArgoCD, and related operational/security considerations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a design decision document for IAP authentication.
Description check	✅ Passed	The description is directly related to the changeset, providing context about the IAP authentication document, its origin from a previous PR, and the Jira reference.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

🤖 Fix all issues with AI agents

In `@design-decisions/iap-authentication.md`:
- Around line 411-414: The statement "Applications can fall back to admin
password if IAP fails" introduces an ungoverned authentication bypass; either
remove this fallback entirely or replace it with a defined, controlled
break-glass procedure: specify a named mechanism (e.g.,
"BreakGlassAdminAccess"), require separate credentials stored and rotated via
vault, ensure the path is disabled by default, require multi-person approval and
time-bound enablement, enforce full audit logging and alerting, and document
recovery/rotation steps; update the bullet under "Degradation" accordingly to
reference the controlled break-glass mechanism if retained.
- Around line 28-29: Update the "**API Deprecation**" bullet in
design-decisions/iap-authentication.md to cite the official Google deprecation
notice for the IAP OAuth Admin API shutdown (March 19, 2026); add the URL
https://cloud.google.com/docs/deprecations (or the specific Google doc) after
the sentence about the shutdown date so the claim is backed by the authoritative
source and ensure the date "March 19, 2026" remains unchanged.
- Around line 411-412: Remove the incorrect standalone SLA claim by deleting or
editing the bullet line that reads "**SLA**: Google Cloud IAP is part of GCP's
99.95% SLA" in the iap-authentication.md content and replace it with an accurate
statement that IAP does not have its own SLA and that its availability is
governed by the SLAs of underlying Google Cloud services (e.g., load balancer,
compute); keep the "Failover" line but ensure the updated text clarifies
dependency on underlying service SLAs rather than asserting a specific IAP SLA.
- Around line 243-255: Rename the strategy label from "Issuer-only validation"
to something like "Issuer and audience validation" and add explicit audience
(aud) claim checking to the IAP JWT validation steps: when reading the token
from header X-Goog-IAP-JWT-Assertion, continue to validate signature against
JWKS URL https://www.gstatic.com/iap/verify/public_key-jwk and issuer claim
https://cloud.google.com/iap, and also verify the aud claim exactly matches the
protected resource identifier pattern (e.g.
/projects/PROJECT_NUMBER/apps/PROJECT_ID for App Engine or
/projects/PROJECT_NUMBER/global/backendServices/SERVICE_ID for Compute/GKE);
keep existing expiration (exp) and IAM policy checks. Ensure documentation
references the X-Goog-IAP-JWT-Assertion header, issuer URL, JWKS URL, and the
exact aud formats so implementers perform precise audience matching.
- Around line 372-383: Update the "Latency" and "Cost" claims in the IAP design
doc to either cite official GCP sources or mark them explicitly as estimates:
replace the "~10-50ms" latency claim under the "Latency" bullet with a phrasing
that notes it is an estimate (e.g., "approximate; varies by region/policy") or
add a cited link to Google/IAP performance documentation, and change the
"<$1/month" line under "Minimal Overhead" to state it's an estimate with a note
about usage-dependence and optionally link to Cloud Logging and Secret Manager
pricing pages; ensure the bullets for Latency and Minimal Overhead include the
word "estimate" or a citation to make provenance clear.

[billmvt]

Practically speaking, this should mean:

1. one-time manual setup on each of {Int, Stage, Prod} Environments
2. periodic key rotation (e.g. quarterly, TBD) across each of these three environments

correct? Any other one-time or recurring manual work we'll incur?

The other solutions considered are at least an order of magnitude more work; I'm not questioning using IAP overall, just want to ensure I understand the toil we're signing up for with this decision.