Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Suggested improvements to explanation of id-token: write #32320

Closed
1 task done
simonw opened this issue Apr 1, 2024 · 10 comments
Closed
1 task done

Suggested improvements to explanation of id-token: write #32320

simonw opened this issue Apr 1, 2024 · 10 comments
Labels
actions This issue or pull request should be reviewed by the docs actions team content This issue or pull request belongs to the Docs Content team more-information-needed More information is needed to complete review SME reviewed An SME has reviewed this issue/PR stale There is no recent activity on this issue or pull request test-create-tracking-issue Creates and links an SME review tracking issue internally

Comments

@simonw
Copy link
Contributor

simonw commented Apr 1, 2024

Code of Conduct

What article on docs.github.com is affected?

The explanation of what id-token: read/write/none means in a GitHub Actions workflow is still really confusing. Previous issues about this include:

I guess the most relevant article is this one: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#adding-permissions-settings

What part(s) of the article would you like to see updated?

Here's my understanding of this feature. Feel free to use any of this copy, or correct me if I got something wrong!


The id-token: write permission provides a workflow the ability to interact with external services that use OpenID Connect (OIDC).

The write value can be better interpreted as meaning "enabled" - no writes occur with this permission, and it does not imply that the workflow has the ability to write to anything within GitHub.

Instead, this permission allows the workflow to request an access token from an OIDC supporting external service, such as PyPI or AWS or Google Cloud.

When the GitHub Action workflow runs it will request a token from the relevant service. That service will be able to identify the workflow and repository that is making the request and will only return a token for workflows that it has been configured to allow.

A value of id-token: read is treated the same as id-token: none (the default) - workflows without id-token: write will be unable to request tokens from external services using OIDC.

Additional information

No response

@simonw simonw added the content This issue or pull request belongs to the Docs Content team label Apr 1, 2024
@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Apr 1, 2024
@simonw
Copy link
Contributor Author

simonw commented Apr 1, 2024

The table on this page also mentions id-token, and references read permissions: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token

CleanShot 2024-04-01 at 09 28 20@2x

I don't understand the relevance of read here.

@nguyenalex836 nguyenalex836 added actions This issue or pull request should be reviewed by the docs actions team waiting for review Issue/PR is waiting for a writer's review and removed triage Do not begin working on this issue until triaged by the team labels Apr 1, 2024
@nguyenalex836
Copy link
Contributor

@simonw Thank you for opening this issue! I'll get this triaged for review ✨

@nguyenalex836 nguyenalex836 added the needs SME This proposal needs review from a subject matter expert label Apr 5, 2024
Copy link
Contributor

github-actions bot commented Apr 5, 2024

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

@nguyenalex836
Copy link
Contributor

@simonw Hello! 👋 Thank you for your patience while our team reviewed this issue! After discussing this issue with our technical writing team, we are going to loop in one of our Actions SMEs, given the complexity of this topic.

We'll provide another update once the Actions SME has reviewed 💛

@nguyenalex836 nguyenalex836 added the test-create-tracking-issue Creates and links an SME review tracking issue internally label Apr 5, 2024
@nguyenalex836
Copy link
Contributor

@simonw Hi again! 👋 Thank you again for your patience while our Actions SME team reviewed. They wanted to ensure you had a chance to view this portion of the documentation regarding permissioning, and wanted to offer some additional context -

For reusable workflows outside the org and also for pull requests from public forked repos , default value issued to id-token is "read" to be safe and restrictive. Users could change it to "write" if they want to explicitly grant permissions for the workflow to request an OIDC JWT.

Does this help clarify some of the confusion regarding id-token: read/write/none?

@nguyenalex836 nguyenalex836 added SME reviewed An SME has reviewed this issue/PR more-information-needed More information is needed to complete review and removed needs SME This proposal needs review from a subject matter expert waiting for review Issue/PR is waiting for a writer's review labels Apr 18, 2024
@github-actions github-actions bot added the stale There is no recent activity on this issue or pull request label May 2, 2024
Copy link
Contributor

github-actions bot commented May 2, 2024

This issue has been automatically closed because there has been no response to our request for more information from the original author. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. See this blog post on bug reports and the importance of repro steps for more information about the kind of information that may be helpful.

@github-actions github-actions bot closed this as not planned Won't fix, can't repro, duplicate, stale May 2, 2024
@danielcompton
Copy link
Contributor

@nguyenalex836 I can't speak for @simonw but for me that doesn't really make sense, or at least doesn't fully explain what id-token: read means.

@nguyenalex836
Copy link
Contributor

@danielcompton Thank you for letting me know! 💛 Would you be open to raising a new, separate issue that includes the specific points that you are looking for clarity on regarding id-token: read?

@janbrasna
Copy link
Contributor

I don't think this topic needs a new issue every single time a stale bot closes out the previous one;) I'm afraid it needs a better documentation explaining what the actual permission setting is and what it is for (not the whole OIDC workflow, that one clearly states when you need the permission, own-org vs. outside-org reusables etc. — but what the actual values for that permission mean, and if/when/how they can be set). Ex without the great writeup about OIDC use for deploy-pages I could have only guessed why such permission is necessary to grant, without any more explanation than to just blindly follow the boilerplate.

(In case of deploy-pages, the token here contains more info about the source event/repo protections wrt the environment to be deployed to, in a standardized way, that's not implicit on GITHUB_TOKEN, and GH apparently chose to consume their own OIDC mechanism instead of getting that info via GH API using the default token scope I guess…)

Connecting to cloud providers like AWS or GCP is pretty well documented here, but the issues cropping up repeatedly are about the lack of documentation for:

  1. why GH itself needs the permission (and OIDC flow to start with) for Pages deployment (only mentioned by the authors above),
  2. what does the "read" permission really mean, and why it can't be set, even though it's supposedly a valid value being used by default in some scenarios (and if that's a maximum permission for PRs from forks, what that means in real life, compared to "none").

I see it being rather unpopular topic with how often it ends up closed out by stale bot, but perhaps it's too obvious for engineers architecting the functionality, but without any visibility into how that values are then used for what in GHA code, we the end users are then left in the dark to just blindly trust the actions' instructions, or keep running in circles between unresolved issues trying to asses the potential impact this setting could have if not used correctly.

But if you really want, there's another confused consumer:

@nguyenalex836
Copy link
Contributor

@janbrasna Thank you for the incredibly thoughtful comment! This is certainly a nuanced topic, but just to get us all on the same page, the next development / response on the id-token: front will be documented on the issue you linked above once our team has had a chance to discuss this further 💛 #33483

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
actions This issue or pull request should be reviewed by the docs actions team content This issue or pull request belongs to the Docs Content team more-information-needed More information is needed to complete review SME reviewed An SME has reviewed this issue/PR stale There is no recent activity on this issue or pull request test-create-tracking-issue Creates and links an SME review tracking issue internally
Projects
None yet
Development

No branches or pull requests

6 participants
@simonw @danielcompton @janbrasna @nguyenalex836 and others