Docs: Subject exceeds the 127 byte limit mitigation strategy

[reakaleek]

TL;DR

The troubleshooting guide suggests that you can only use shorter repo or branch names to overcome the 127-byte limit issue.

But you can also adjust the attribute mapping and shorten the subject.

Detailed design

You can overcome the 127 byte limit by shortening the google.subject in the attribute mapping.

gcloud iam workload-identity-pools providers create-oidc "my-repo" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --workload-identity-pool="github" \
  --display-name="My GitHub repo Provider" \
-  --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
+  --attribute-mapping="google.subject=assertion.sub.split(':')[1],attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --attribute-condition="assertion.repository_owner == '${GITHUB_ORG}'" \
  --issuer-uri="https://token.actions.githubusercontent.com"

Hence, in cases where the sub claim is repo:<orgName/repoName>:pull_request it will be change to <orgName/repoName>, which will shorten the google.subject to some degree.

Update documentation accordingly.

Additional information

No response

[github-actions]

Hi there @reakaleek 👋!

Thank you for opening an issue. Our team will triage this as soon as we can. Please take a moment to review the troubleshooting steps which lists common error messages and their resolution steps.

[sethvargo]

Sure, but that same value (<orgName/repoName>) is available via assertion.repository without any string manipulation. It also greatly reduces the subject granularity, which would not be advised. As such, I'm not comfortable with even documenting this option, since unfamiliar users could too-easily misconfigure access.

[reakaleek]

@sethvargo thank you for the feedback.

Would you mind explaining why a reduced subject granularity is not advised?

Context:

Due to the quirks of AWS OIDC authentication, we had to modify the sub claim for the GH repository to include more attributes.
This broke the google auth because of the 127 byte limit.

So, do you think it's okay to shorten the google.subject if we still use other attributes in the condition?

I want to understand the implications of this and if I should reconsider my approach.

[sethvargo]

The subject (sub) is an unique identifier of the user, device, or application, idempotently consistent for the same inputs. “sub” is a standard claim representing the entity to which the token is issued. If you change the subject to be overly broad, it no longer uniquely represents the invocation, which can lead to easy misconfigurations downstream that grant overzealous permissions to a broad set of workflows and repositories.