From b8d7a0e861d0c3df05b4ad85e7dc7465435fd398 Mon Sep 17 00:00:00 2001 From: Fabian Aguilar Gomez Date: Wed, 22 May 2024 13:56:05 -0500 Subject: [PATCH 1/6] Update README.md --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index ec1f85b..70fb16e 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,13 @@ There are a few important considerations to be aware of: 5. If your Pages site is using GitHub Actions as the source, while not required we highly recommend you also [protect your environment][environment-protection] (we will configure it by default for you). +### OICD +When we invoke a job using GitHub Actions the job requests an OICD token from GitHub's OICD provider which responds with a JSON web token (JWT), each token is unique to each workflow job [learn more about OICD tokens](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). + +OICD tokens are minted in the in the context of an Action job which help form a trust relationship between GitHub and a third-party (e.g. AWS or Azure) to determine if there's anything to be done. Hence, there is no "permissions" associated with the token itself. For GitHub Pages use cases we allow `id-token: write` to allow the `GITHUB-TOKEN` to make API calls to generate an OICD for us which +results in the former statement. + +A common misconception is that the OICD tokens we generate are "dangerous" this is not the case! What **can be** is what we allow a third-party to do with the OICD token that was minted for us! Another common issue is accessing the REST endpoints from Actions. The GitHub Pages calls to our endpoints from a job perspective are **only** accessible from the Actions API as of today. ## Compatibility This action is primarily designed for use with GitHub.com's Actions workflows and Pages deployments. However, certain releases should also be compatible with GitHub Enterprise Server (GHES) `3.7` and above. From b352a2114c29b620ffeb0845bcdea21b475948ab Mon Sep 17 00:00:00 2001 From: Fabian Aguilar Gomez Date: Thu, 23 May 2024 19:28:52 +0000 Subject: [PATCH 2/6] update readme --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 70fb16e..5e964e2 100644 --- a/README.md +++ b/README.md @@ -83,13 +83,13 @@ There are a few important considerations to be aware of: 5. If your Pages site is using GitHub Actions as the source, while not required we highly recommend you also [protect your environment][environment-protection] (we will configure it by default for you). -### OICD -When we invoke a job using GitHub Actions the job requests an OICD token from GitHub's OICD provider which responds with a JSON web token (JWT), each token is unique to each workflow job [learn more about OICD tokens](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). +### OIDC +When we invoke a job using GitHub Actions the job requests an OIDC token from GitHub's OIDC provider which responds with a JSON web token (JWT). Each token is unique to each workflow job [learn more about OIDC tokens](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). -OICD tokens are minted in the in the context of an Action job which help form a trust relationship between GitHub and a third-party (e.g. AWS or Azure) to determine if there's anything to be done. Hence, there is no "permissions" associated with the token itself. For GitHub Pages use cases we allow `id-token: write` to allow the `GITHUB-TOKEN` to make API calls to generate an OICD for us which +OIDC tokens are minted within the context of a single job, and are used to form a trust relationship which validates properties of the workflow run against a third-party (e.g. cloud providers such as AWS or Azure). In the context of GitHub Pages, this is most relevant to ensure a workflow respects branch protection settings. To do this, the OIDC token includes a claim about which branch/ref is executing the workflow. The token is passed to the pages deployment API as part of the request payload, where it's decoded internally to validate the claims and verify if that workflow is allowed to deploy to pages. results in the former statement. -A common misconception is that the OICD tokens we generate are "dangerous" this is not the case! What **can be** is what we allow a third-party to do with the OICD token that was minted for us! Another common issue is accessing the REST endpoints from Actions. The GitHub Pages calls to our endpoints from a job perspective are **only** accessible from the Actions API as of today. +A common misconception is that the OICD tokens we generate are "dangerous" this is not the case. What **can be** is what we allow a third-party to do with the OICD token that was minted for us. Another common issue is accessing the REST endpoints from Actions. The GitHub Pages calls to our endpoints from a job perspective are **only** accessible from the Actions API as of today. ## Compatibility This action is primarily designed for use with GitHub.com's Actions workflows and Pages deployments. However, certain releases should also be compatible with GitHub Enterprise Server (GHES) `3.7` and above. From 2e8b6c71919ad5efe8c4001f8bcdec18b04e97db Mon Sep 17 00:00:00 2001 From: Fabian Aguilar Gomez Date: Thu, 23 May 2024 14:41:32 -0500 Subject: [PATCH 3/6] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5e964e2..395df0b 100644 --- a/README.md +++ b/README.md @@ -89,8 +89,8 @@ When we invoke a job using GitHub Actions the job requests an OIDC token from Gi OIDC tokens are minted within the context of a single job, and are used to form a trust relationship which validates properties of the workflow run against a third-party (e.g. cloud providers such as AWS or Azure). In the context of GitHub Pages, this is most relevant to ensure a workflow respects branch protection settings. To do this, the OIDC token includes a claim about which branch/ref is executing the workflow. The token is passed to the pages deployment API as part of the request payload, where it's decoded internally to validate the claims and verify if that workflow is allowed to deploy to pages. results in the former statement. -A common misconception is that the OICD tokens we generate are "dangerous" this is not the case. What **can be** is what we allow a third-party to do with the OICD token that was minted for us. Another common issue is accessing the REST endpoints from Actions. The GitHub Pages calls to our endpoints from a job perspective are **only** accessible from the Actions API as of today. -## Compatibility +A common question regarding OIDC tokens is the use of `pages:write` and `id-token:write`. Ideally, the `GITHUB_TOKEN` would contain both but currently our API for tokens does not operate this way hence the need for +setting both to `write`. We also encode the JWT token to ensure it can not be tampered with specially considering we support indvidual versioning for the `deploy-pages` action. This action is primarily designed for use with GitHub.com's Actions workflows and Pages deployments. However, certain releases should also be compatible with GitHub Enterprise Server (GHES) `3.7` and above. From 32d96c30ca3aa69911daf9849867f2a69dce5569 Mon Sep 17 00:00:00 2001 From: Fabian Aguilar Gomez Date: Tue, 28 May 2024 18:20:19 +0000 Subject: [PATCH 4/6] add recommendations --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 395df0b..18a0163 100644 --- a/README.md +++ b/README.md @@ -87,12 +87,10 @@ There are a few important considerations to be aware of: When we invoke a job using GitHub Actions the job requests an OIDC token from GitHub's OIDC provider which responds with a JSON web token (JWT). Each token is unique to each workflow job [learn more about OIDC tokens](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). OIDC tokens are minted within the context of a single job, and are used to form a trust relationship which validates properties of the workflow run against a third-party (e.g. cloud providers such as AWS or Azure). In the context of GitHub Pages, this is most relevant to ensure a workflow respects branch protection settings. To do this, the OIDC token includes a claim about which branch/ref is executing the workflow. The token is passed to the pages deployment API as part of the request payload, where it's decoded internally to validate the claims and verify if that workflow is allowed to deploy to pages. -results in the former statement. - A common question regarding OIDC tokens is the use of `pages:write` and `id-token:write`. Ideally, the `GITHUB_TOKEN` would contain both but currently our API for tokens does not operate this way hence the need for -setting both to `write`. We also encode the JWT token to ensure it can not be tampered with specially considering we support indvidual versioning for the `deploy-pages` action. +A common question regarding OIDC tokens is the need to use both `pages:write` and `id-token:write`. The pages permission relates to the `GITHUB_TOKEN` by giving it the permissions to create pages deployments when calling the GitHub API. The id-token permission is necessary to request the OIDC JWT token. For more information on the id-token, check the docs on [adding permissions settings](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers#adding-permissions-settings) +A common question regarding OIDC tokens is the need to use both `pages:write` and `id-token:write`. The pages permission relates to the `GITHUB_TOKEN` by giving it the permissions to create pages deployments when calling the GitHub API. The id-token permission is necessary to request the OIDC JWT token. For more information on the id-token, check the docs on [adding permissions settings](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers#adding-permissions-settings) -This action is primarily designed for use with GitHub.com's Actions workflows and Pages deployments. However, certain releases should also be compatible with GitHub Enterprise Server (GHES) `3.7` and above. | Release | GHES Compatibility | |:---|:---| From 4072571698f61791dff2a7a3744c98eb60999be2 Mon Sep 17 00:00:00 2001 From: Fabian Aguilar Gomez Date: Fri, 31 May 2024 14:38:24 -0500 Subject: [PATCH 5/6] Update README.md --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 18a0163..f1bef0a 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,9 @@ A common question regarding OIDC tokens is the use of `pages:write` and `id-toke A common question regarding OIDC tokens is the need to use both `pages:write` and `id-token:write`. The pages permission relates to the `GITHUB_TOKEN` by giving it the permissions to create pages deployments when calling the GitHub API. The id-token permission is necessary to request the OIDC JWT token. For more information on the id-token, check the docs on [adding permissions settings](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers#adding-permissions-settings) A common question regarding OIDC tokens is the need to use both `pages:write` and `id-token:write`. The pages permission relates to the `GITHUB_TOKEN` by giving it the permissions to create pages deployments when calling the GitHub API. The id-token permission is necessary to request the OIDC JWT token. For more information on the id-token, check the docs on [adding permissions settings](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers#adding-permissions-settings) +## Compatibility + +This action is primarily designed for use with GitHub.com's Actions workflows and Pages deployments. However, certain releases should also be compatible with GitHub Enterprise Server (GHES) `3.7` and above. | Release | GHES Compatibility | |:---|:---| From b2d396ab1683fc4780f774f4bcb8905f1feda3b6 Mon Sep 17 00:00:00 2001 From: Fabian Aguilar Gomez Date: Fri, 31 May 2024 14:40:24 -0500 Subject: [PATCH 6/6] Update README.md Co-authored-by: Mingzi --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f1bef0a..9ab1e63 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ There are a few important considerations to be aware of: 5. If your Pages site is using GitHub Actions as the source, while not required we highly recommend you also [protect your environment][environment-protection] (we will configure it by default for you). -### OIDC +## OIDC When we invoke a job using GitHub Actions the job requests an OIDC token from GitHub's OIDC provider which responds with a JSON web token (JWT). Each token is unique to each workflow job [learn more about OIDC tokens](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). OIDC tokens are minted within the context of a single job, and are used to form a trust relationship which validates properties of the workflow run against a third-party (e.g. cloud providers such as AWS or Azure). In the context of GitHub Pages, this is most relevant to ensure a workflow respects branch protection settings. To do this, the OIDC token includes a claim about which branch/ref is executing the workflow. The token is passed to the pages deployment API as part of the request payload, where it's decoded internally to validate the claims and verify if that workflow is allowed to deploy to pages.