Document id-token permission

[danielcompton]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/security-guides/automatic-token-authentication

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

I'm looking into setting up OIDC authentication with GitHub Actions and am wanting to understand how the id-token permission works. I couldn't find much documentation about it, other than documentation saying to set it to write, e.g. https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services#adding-permissions-settings.

The automatic token authentication article talks about id-token and that the "Maximum access by forked repos" is read. What does it mean to have read access to the id-token? What is the minimum permissions needed to use OIDC?

Specifically, can a PR opened by Dependabot obtain OIDC credentials?

Additional information

No response

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[ramyaparimi]

@danielcompton
Thanks so much for opening an issue! I'll triage this for the team to take a look 👀

[N-Usha]

To generate an OIDC id-token from a GitHub workflow it requires write permissions on id-token bit. When we add this permission to workflow it will set the following two env variables (url and token) in runner machine, which will be used by Actions/scripts to generate id token:
ACTIONS_ID_TOKEN_REQUEST_URL, ACTIONS_ID_TOKEN_REQUEST_TOKEN

Thanks @danielcompton for reporting this. We will add the above context to our docs to make this more clear.

[danielcompton]

Thanks @N-Usha! What does it mean to have id-token: read then?

[N-Usha]

It just means that OIDC tokens cant be generated in that workflow. And we made that as the default as we wanted to make OIDC an opt-in feature where workflows which need OIDC to get used for authentication purposes need to explicitly set the bit to write to use the feature within a Job or across all Jobs within the workflow run.

[danielcompton]

Thanks for the clarification. Sorry to belabour the point, but what is the difference then between id-token: read and id-token: none?

[danielcompton]

Thanks @lucascosti, it's still not clear to me what the difference is between id-token: read and id-token: none? Are you able to help clarify that?

[lucascosti]

Thanks @lucascosti, it's still not clear to me what the difference is between id-token: read and id-token: none? Are you able to help clarify that?

Sorry, @danielcompton; I have a guess, but rather than potentially give out the wrong info, I'll let @N-Usha clarify 🙂

[danielcompton]

@N-Usha would you be able to help clarify what the difference is between id-token: read and id-token: none?

[danielcompton]

@N-Usha are you able to help with this? I'm still not sure what the security differences are between a workflow having id-token: read and id-token: none.

[N-Usha]

Apologies for delayed response on this.

@danielcompton - There is no difference between a workflow having id-token: read and id-token: none.
We have clarified this in docs recently:

The job or workflow run requires a permissions setting with id-token: write. You won't be able to request the OIDC JWT ID token if the permissions setting for id-token is set to read or none.

Please confirm if that clarifies your query. Thanks

[danielcompton]

Thanks @N-Usha that's exactly what I was after!

[jmandel]

This is a closed issue, but I'm struggling to understand what the word "write" means here. Why is the permission called "write"? Is something being written? If so, what and by whom? Or is the permission called "write" for some other reason (e.g., something historical, referential, or arcane)? It'd be great to explain this just a tiny bit more.

[ssbarnea]

I am quire curious how it comes that this is closed when this tag has zero documentation.

[cmwilson21]

@ssbarnea @jmandel - 👋 Hey there! Would either of you mind opening a new issue detailing your request? With a fresh issue, we can take it through the review process.

Thank you! ✨

[jmandel]

#25952

[vincerubinetti]

Fwiw I couldn't even figure out that this permission scope had something to do with OIDC. Had to google it and find this issue.