Add details on claim verification for protected branches

[sidsenkumar11]

The Google documentation only suggests verifying the repository_owner claim, which is insufficient for most use cases. Adding notes from this blog post to show how to use other claims to protect cloud resources from potentially malicious untrusted code.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[technologik]

This looks great Sid! Thanks for putting it together.

[technologik]

Suggestion: Have one more section for creating attributes based on Github Environments.

Environments are a Github Enterprise feature, so not everyone may have access, but using environments make it marginally easier to categorize branches within an attribute. For example in a github action workflow you can set an if conditional like so:

if: github.ref_protected == true && github.event_name == 'push'

Which you'll note encapsulates all protected branches (not just main). If the repo only has a single protected repository, it's equivalent to your section on Attribute Conditions for Protected Main Branch, but in your section you have to individually set attribute.ref to the branch. Whereas if you use the sub claim of the attribute which references a Github Environment, you can have the environment be a superset of all protected branches. And would look something like this:

attribute.sub == "repo:octo-org/octo-repo:environment:Production"

[sidsenkumar11]

One thing I'm not 100% sure about is why we need to add the if condition to the workflow. The claim verification is done on the cloud provider's side, right? Even if random, unprotected branches triggered the workflow, they wouldn't be able to access the cloud provider's resources.

[sethvargo]

Please wrap at the column as shown elsewhere in this file.

[sethvargo]

Branch Protection is deprecated and GitHub recommends rulesets now. That being said, I don't think the auth GitHub Action should be responsible for re-iterating GitHub security best practices.

I'm amenable to documenting "pull_request" vs "pull_request_target" things, but I don't want to become a documentation hub for GitHub repo security best practices. Perhaps we can link to GitHub documentation instead?

[sethvargo]

There are many valid business reasons why you might have a single Workload Identity Pool and Provider for all repositories in an organization.

[sethvargo]

Suggested change

	Once the GitHub assertions have been mapped to Google STS token attributes, you can create attribute conditions to verify that the caller is coming from a trusted source. For example, the following conditions verify that the GitHub OIDC token was generated after a push to the `main` branch of the `octo-org/octo-repo` repository.
	Once the GitHub assertions have been mapped to Google STS token attributes, you can create attribute conditions on any of the mapped attributes to verify that the caller is coming from a trusted source. For example, the following conditions verify that the GitHub OIDC token was generated after a push to the `main` branch of the `octo-org/octo-repo` repository.

[sethvargo]

This is a business-specific organization decision that does not match how all businesses use and organize their GitHub repositories. I'm 👎 on including it.

[sethvargo]

This generally won't work, because GitHub doesn't inject secrets into PRs from forks (and therefore there's no OIDC token).