Make GitHub Actions OIDC trust depend on the claims you can enforce

GitHub Actions can leverage OpenID Connect (OIDC) tokens to obtain cloud access without storing long-lived secrets in repositories. The security relies on a trust policy determined outside GitHub, which specifies which token subjects and audiences are authorized to assume particular roles. The subject claim in an OIDC token can identify the repository and context, and organizations can customize this to require specific claims.

Different types of workflows, such as pull request, branch, environment jobs, and reusable workflows, can generate varying context for the subject claim. It is crucial to thoroughly review the actual claim for each trusted path.

GitHub provides an OIDC debugger action to visualize claims before integrating a cloud provider. A weak trust policy that relies on broad patterns may inadvertently include workflows the role owner did not intend. When testing the trust policy, it is essential to use a non-production role and evaluate the actual claim for each trusted path. The cloud trust policy should encompass the issuer, audience, subject, and any provider-specific conditions that distinguish the intended workflow.

To enhance security, the cloud trust policy should combine the issuer, audience, subject, and any provider-specific conditions. It is advisable to use repository owners and identities rather than just human-readable names, especially when immutable repository identifiers are supported. Incorporating environment protection rules when a workflow utilizes an environment can provide stronger trust conditions.

Separate deployment roles by environment and purpose, ensuring that a production deployment role is not assumable by every branch or pull request workflow. Similarly, a read-only inventory job should not receive a role with infrastructure-changing capabilities.

The cloud provider's session policy can further narrow the token exchange. As workflows may change, it is vital to review actions receiving the OIDC token and treat such changes as security-sensitive. Ensure actions are pinned to reviewed versions, limit workflow permissions, and avoid passing unnecessary tokens to steps that do not require them.

Although the OIDC token is short-lived, the resulting cloud session could outlive the job, making it essential to log the assumed role and the token claims accepted by the provider. Avoid logging the token itself and set up alerts for new subjects assuming sensitive roles, unexpected audiences, or roles assumed from typically non-cloud-access workflows.

Rigorous testing should be conducted to ensure that attempts from untrusted branches, workflows lacking required environments, different reusable workflows, and tokens with incorrect audiences all fail. Subsequently, confirm that the intended workflow results in a cloud session with only the necessary permissions.