Clarify Open ID Connect in AWS documentation

[iainelder]

Describe the issue

Today is my first time working with OIDC to deploy to AWS from GitHub. I ran into #672. It was closed without a clear repro, so I thought I should explain how I got here.

I had followed the OpenID Connect in AWS documentation and then later I added an environment to my workflow.

I adapted the example trust policy:

"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

That policy works until I add an environment to my workflow. Then it mysteriously fails, as documented in #672.

I wish I had read this repo's README full first.

Compare the policy above to the one in this repo's README:

            Condition:
              StringEquals:
                token.actions.githubusercontent.com:aud: !Ref OIDCAudience
              StringLike:
                token.actions.githubusercontent.com:sub: !Sub repo:${GitHubOrg}/${RepositoryName}:*

The README goes on to say:

The subject can be scoped to a GitHub organization and repository as shown in the CloudFormation template. Additional claim conditions can be added for higher specificity as explained in the GitHub documentation.

I think the policy in the README is better for first time users because it locks down the sub to a specific repo without later creating any surprising conflicts because of changes to branch names, environment names, or whatever else may cause GitHub to change the sub value.

So, could you reword that other documentation to include that information that helped a first-timer?

[iainelder]

It just ocurred to me that the documentation that tripped me up is stored in another repo:

https://github.com/github/docs/blob/main/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md

Should I create an issue over there instead, or do you also own those pages?

[iainelder]

This might be in the scope of #746 .

[peterwoodworth]

We don't own that page @iainelder, best place for that will be the repo that contains that page.

And yes, #746 will make this as clear as possible in our readme, I think this overlaps with that issue. Thanks for letting us know 🙂

[github-actions]

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.