Enforce OIDC for VCS CI/CD Connections to AWS
Specification & Description
Mandate the use of OIDC federation for all CI/CD pipeline connections from GitHub, GitLab or any other version control system (VCS) to central AWS accounts, eliminating long-lived IAM access keys from VCS secrets entirely.
Technical Specifications
CI/CD pipelines that deploy to or read from central landing zone accounts must authenticate via OIDC rather than static IAM access keys. In the OIDC flow, the VCS provider issues a short-lived JWT to the pipeline job, which exchanges it for temporary STS credentials by assuming an IAM role. The IAM role trust policy must include a condition on the sub claim to restrict which repositories and branches can assume the role - without this condition, any repository in the same GitHub organization or GitLab instance can assume the role. The SCP in enforcement_reference denies iam:CreateAccessKey for any principal that is not an explicitly approved role, preventing pipelines from creating new static credentials as a bypass. Existing access keys stored as VCS secrets must be audited and rotated to OIDC before the SCP Deny takes effect.
Security Rationale
Long-lived IAM access keys stored as VCS secrets are the most common source of AWS credential leaks. They appear in logs, get committed to repositories, are copied between environments, and persist long after the pipeline that needed them is decommissioned. OIDC credentials are valid for 15 minutes by default, are never stored, and are scoped to the specific job that requested them. A leaked OIDC token is worthless seconds after the job completes.
Policy Exceptions (2)
Legacy pipeline tooling that does not support OIDC token exchange may retain a time-limited IAM access key while a migration plan is in progress. The key must have no console access, must be rotated every 90 days, must be scoped to the minimum required permissions, and the exception must be renewed quarterly with documented progress toward OIDC migration.
Self-hosted GitLab instances use a different OIDC URL than gitlab.com. The OIDC provider URL must match the self-hosted instance URL exactly. The thumbprint must be retrieved from the instance's OIDC discovery endpoint and verified independently.
Operational & Implementation Notes
The sub claim is the critical security boundary in OIDC role trust policies. A trust policy that conditions only on aud (audience) allows any repository in the same GitHub organization or GitLab instance to assume the role - this is a common misconfiguration. Always scope sub to the specific repository and branch or environment. Use StringLike with a wildcard only when multiple repositories in the same org legitimately need the same role. For self-hosted GitLab, thumbprint validation is required and the correct value must be retrieved from the instance.