From f18b6aaf70b729dcbca581dbe433528d79ef590c Mon Sep 17 00:00:00 2001 From: hubwriter Date: Fri, 8 Sep 2023 09:37:10 +0100 Subject: [PATCH] Actions: mention the issuer claim in GHES version of "Configuring OpenID Connect in Azure" article (#40973) Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com> --- .../about-security-hardening-with-openid-connect.md | 4 ++-- .../configuring-openid-connect-in-amazon-web-services.md | 8 +++++++- .../configuring-openid-connect-in-azure.md | 2 ++ .../using-openid-connect-with-reusable-workflows.md | 2 +- .../authenticating-to-the-github-api.md | 2 +- .../adding-a-workflow-status-badge.md | 4 ++-- .../security-hardening-for-github-actions.md | 2 +- .../troubleshooting-github-actions-for-your-enterprise.md | 2 +- data/reusables/actions/allow-specific-actions-intro.md | 4 ++-- data/reusables/actions/enterprise-oidc-prereqs.md | 4 ++-- data/reusables/actions/oidc-endpoints.md | 4 ++-- 11 files changed, 23 insertions(+), 15 deletions(-) diff --git a/content/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md b/content/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md index 4f53ecab0e..1177b3b209 100644 --- a/content/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md +++ b/content/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md @@ -153,13 +153,13 @@ The token also includes custom claims provided by {% data variables.product.prod ### Defining trust conditions on cloud roles using OIDC claims -With OIDC, a {% data variables.product.prodname_actions %} workflow requires a token in order to access resources in your cloud provider. The workflow requests an access token from your cloud provider, which checks the details presented by the JWT. If the trust configuration in the JWT is a match, your cloud provider responds by issuing a temporary token to the workflow, which can then be used to access resources in your cloud provider. You can configure your cloud provider to only respond to requests that originate from a specific organization's repository; you can also specify additional conditions, described below. +With OIDC, a {% data variables.product.prodname_actions %} workflow requires a token in order to access resources in your cloud provider. The workflow requests an access token from your cloud provider, which checks the details presented by the JWT. If the trust configuration in the JWT is a match, your cloud provider responds by issuing a temporary token to the workflow, which can then be used to access resources in your cloud provider. You can configure your cloud provider to only respond to requests that originate from a specific organization's repository. You can also specify additional conditions, described below. Audience and Subject claims are typically used in combination while setting conditions on the cloud role/resources to scope its access to the GitHub workflows. - **Audience**: By default, this value uses the URL of the organization or repository owner. This can be used to set a condition that only the workflows in the specific organization can access the cloud role. - **Subject**: By default, has a predefined format and is a concatenation of some of the key metadata about the workflow, such as the {% data variables.product.prodname_dotcom %} organization, repository, branch, or associated [`job`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) environment. See "[Example subject claims](#example-subject-claims)" to see how the subject claim is assembled from concatenated metadata. -If you need more granular trust conditions, you can customize the issuer (`iss`) and subject (`sub`) claims that are included with the JWT. For more information, see "[Customizing the token claims](#customizing-the-token-claims)". +If you need more granular trust conditions, you can customize the {% ifversion ghec %}issuer (`iss`) and {% endif %}subject (`sub`) claim{% ifversion ghec %}s that are{% else %} that's{% endif %} included with the JWT. For more information, see "[Customizing the token claims](#customizing-the-token-claims)". There are also many additional claims supported in the OIDC token that can be used for setting these conditions. In addition, your cloud provider could allow you to assign a role to the access tokens, letting you specify even more granular permissions. diff --git a/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md b/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md index 920e0f9fe5..0eae242153 100644 --- a/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md +++ b/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md @@ -44,7 +44,13 @@ To add the {% data variables.product.prodname_dotcom %} OIDC provider to IAM, se ### Configuring the role and trust policy -To configure the role and trust in IAM, see the AWS documentation for ["Assuming a Role"](https://github.com/aws-actions/configure-aws-credentials#assuming-a-role) and ["Creating a role for web identity or OpenID connect federation"](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html). +To configure the role and trust in IAM, see the AWS documentation "[Configure AWS Credentials for GitHub Actions](https://github.com/aws-actions/configure-aws-credentials#configure-aws-credentials-for-github-actions)" and "[Configuring a role for GitHub OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html#idp_oidc_Create_GitHub)." + +{% note %} + +**Note**: AWS Identity and Access Management (IAM) recommends that users evaluate the IAM condition key, `token.actions.githubusercontent.com:sub`, in the trust policy of any role that trusts {% data variables.product.prodname_dotcom %}’s OIDC identity provider (IdP). Evaluating this condition key in the role trust policy limits which {% data variables.product.prodname_dotcom %} actions are able to assume the role. + +{% endnote %} Edit the trust policy to add the `sub` field to the validation conditions. For example: diff --git a/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure.md b/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure.md index 1be3ab47e2..72e2d21ab1 100644 --- a/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure.md +++ b/content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure.md @@ -33,6 +33,8 @@ This guide gives an overview of how to configure Azure to trust {% data variable **Note:** Azure Active Directory (Azure AD) does not have fixed IP ranges defined for these endpoints. {% endnote %} + +- Make sure that the value of the issuer claim that's included with the JSON Web Token (JWT) is set to a publicly routable URL. For more information, see "[AUTOTITLE](/enterprise-server@latest/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)." {% endif %} ## Adding the Federated Credentials to Azure diff --git a/content/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows.md b/content/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows.md index d495d13aef..3ffb69c712 100644 --- a/content/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows.md +++ b/content/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows.md @@ -31,7 +31,7 @@ When combined with OpenID Connect (OIDC), reusable workflows let you enforce con - For clouds that only support the standard claims (audience (`aud`) and subject (`sub`)), you can use the API to customize the `sub` claim to include `job_workflow_ref`. For more information, see "[AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-token-claims)". Support for custom claims is currently available for Google Cloud Platform and HashiCorp Vault. - **Customizing the token claims**: - - You can configure more granular trust conditions by customizing the issuer (`iss`) and subject (`sub`) claims included with the JWT. For more information, see "[AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-token-claims)". + - You can configure more granular trust conditions by customizing the {% ifversion ghec %}issuer (`iss`) and {% endif %}subject (`sub`) claim{% ifversion ghec %}s that are{% else %} that's{% endif %} included with the JWT. For more information, see "[AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-token-claims)". ## How the token works with reusable workflows diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api.md index 49d4f29c8f..20ec244f9c 100644 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api.md +++ b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api.md @@ -70,7 +70,7 @@ ARC can use {% data variables.product.pat_v1_plural %} to register self-hosted r ```bash copy kubectl create secret generic pre-defined-secret \ --namespace=my_namespace \ - --from-literal=github_token='' + --from-literal=github_token='YOUR-PAT' ``` 1. In your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file, pass the secret name as a reference. diff --git a/content/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge.md b/content/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge.md index 28cc64aa34..5cd7bd0211 100644 --- a/content/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge.md +++ b/content/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge.md @@ -28,7 +28,7 @@ To add a workflow status badge to your `README.md` file, first find the URL for You can build the URL for a workflow status badge using the name of the workflow file: ```text -{% ifversion fpt or ghec %}https://github.com{% else %}{% endif %}///actions/workflows//badge.svg +{% ifversion fpt or ghec %}https://github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg ``` To display the workflow status badge in your `README.md` file, use the Markdown markup for embedding images. For more information about image markup in Markdown, see "[AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#images)." @@ -41,7 +41,7 @@ For example, add the following Markdown to your `README.md` file to add a status ## Using the `branch` parameter -To display the status of a workflow run for a specific branch, add `?branch=` to the end of the status badge URL. +To display the status of a workflow run for a specific branch, add `?branch=BRANCH-NAME` to the end of the status badge URL. For example, add the following Markdown to your `README.md` file to display a status badge for a branch with the name `feature-1`. diff --git a/content/actions/security-guides/security-hardening-for-github-actions.md b/content/actions/security-guides/security-hardening-for-github-actions.md index 715751fd91..f7311160d2 100644 --- a/content/actions/security-guides/security-hardening-for-github-actions.md +++ b/content/actions/security-guides/security-hardening-for-github-actions.md @@ -313,7 +313,7 @@ This list describes the recommended approaches for accessing repository data wit You can view a software bill of materials (SBOM) to see what software was pre-installed on the {% data variables.product.prodname_dotcom %}-hosted runner image used during your workflow runs. You can provide your users with the SBOM which they can run through a vulnerability scanner to validate if there are any vulnerabilities in the product. If you are building artifacts, you can include this SBOM in your bill of materials for a comprehensive list of everything that went into creating your software. -SBOMs are available for Ubuntu, Windows, and macOS runner images. You can locate the SBOM for your build in the release assets at https://github.com/actions/runner-images/releases. An SBOM with a filename in the format of `sbom..json.zip` can be found in the attachments of each release. +SBOMs are available for Ubuntu, Windows, and macOS runner images. You can locate the SBOM for your build in the release assets at https://github.com/actions/runner-images/releases. An SBOM with a filename in the format of `sbom.IMAGE-NAME.json.zip` can be found in the attachments of each release. {% endif %} diff --git a/content/admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md b/content/admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md index 71abd880a0..dfc5b8df5c 100644 --- a/content/admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md +++ b/content/admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md @@ -50,7 +50,7 @@ If you use Docker container actions or service containers in your workflows, you {% data reusables.actions.enterprise-http-proxy %} -If these settings aren't correctly configured, you might receive errors like `Resource unexpectedly moved to https://` when setting or changing your {% data variables.product.prodname_actions %} configuration. +If these settings aren't correctly configured, you might receive errors like `Resource unexpectedly moved to https://IP-ADDRESS` when setting or changing your {% data variables.product.prodname_actions %} configuration. ## Runners not connecting to {% data variables.product.prodname_ghe_server %} with a new hostname diff --git a/data/reusables/actions/allow-specific-actions-intro.md b/data/reusables/actions/allow-specific-actions-intro.md index 8707dc0f43..5a19126085 100644 --- a/data/reusables/actions/allow-specific-actions-intro.md +++ b/data/reusables/actions/allow-specific-actions-intro.md @@ -11,9 +11,9 @@ When you choose {% data reusables.actions.policy-label-for-select-actions-workfl To restrict access to specific tags or commit SHAs of an action{% ifversion actions-workflow-policy %} or reusable workflow{% endif %}, use the same syntax used in the workflow to select the action{% ifversion actions-workflow-policy %} or reusable workflow{% endif %}. - - For an action, the syntax is `/@`. For example, use `actions/javascript-action@v1.0.1` to select a tag or `actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f` to select a SHA. For more information, see "[AUTOTITLE](/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions)." + - For an action, the syntax is `OWNER/REPOSITORY@TAG-OR-SHA`. For example, use `actions/javascript-action@v1.0.1` to select a tag or `actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f` to select a SHA. For more information, see "[AUTOTITLE](/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions)." {%- ifversion actions-workflow-policy %} - - For a reusable workflow, the syntax is `///@`. For example, `octo-org/another-repo/.github/workflows/workflow.yml@v1`. For more information, see "[AUTOTITLE](/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow)." + - For a reusable workflow, the syntax is `OWNER/REPOSITORY/PATH/FILENAME@TAG-OR-SHA`. For example, `octo-org/another-repo/.github/workflows/workflow.yml@v1`. For more information, see "[AUTOTITLE](/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow)." {%- endif %} You can use the `*` wildcard character to match patterns. For example, to allow all actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} in organizations that start with `space-org`, you can specify `space-org*/*`. To allow all actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} in repositories that start with octocat, you can use `*/octocat**@*`. For more information about using the `*` wildcard, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)." diff --git a/data/reusables/actions/enterprise-oidc-prereqs.md b/data/reusables/actions/enterprise-oidc-prereqs.md index f9ed00abc4..97801475f5 100644 --- a/data/reusables/actions/enterprise-oidc-prereqs.md +++ b/data/reusables/actions/enterprise-oidc-prereqs.md @@ -2,8 +2,8 @@ - If you are using OIDC for the connection to your storage provider, you must expose the following OIDC token service URLs on {% data variables.location.product_location_enterprise %} to the public internet: ```text - https:///_services/token/.well-known/openid-configuration - https:///_services/token/.well-known/jwks + https://HOSTNAME/_services/token/.well-known/openid-configuration + https://HOSTNAME/_services/token/.well-known/jwks ``` This ensures that the storage provider can contact {% data variables.location.product_location_enterprise %} for authentication. diff --git a/data/reusables/actions/oidc-endpoints.md b/data/reusables/actions/oidc-endpoints.md index b3ac2713cd..f29480e765 100644 --- a/data/reusables/actions/oidc-endpoints.md +++ b/data/reusables/actions/oidc-endpoints.md @@ -1,3 +1,3 @@ - You must enable the following publicly accessible endpoints: - - `https:///_services/token/.well-known/openid-configuration` - - `https:///_services/token/.well-known/jwks` + - `https://HOSTNAME/_services/token/.well-known/openid-configuration` + - `https://HOSTNAME/_services/token/.well-known/jwks`