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

Use consistent format for placeholders in Open ID section #34454

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ The subject claim includes the environment name when the job references an envir

You can configure a subject that filters for a specific [environment](/actions/deployment/targeting-different-environments/managing-environments-for-deployment) name. In this example, the workflow run must have originated from a job that has an environment named `Production`, in a repository named `octo-repo` that is owned by the `octo-org` organization:

* Syntax: `repo:<orgName/repoName>:environment:<environmentName>`
* Syntax: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME`
* Example: `repo:octo-org/octo-repo:environment:Production`

#### Filtering for `pull_request` events
Expand All @@ -191,7 +191,7 @@ The subject claim includes the `pull_request` string when the workflow is trigge

You can configure a subject that filters for the [`pull_request`](/actions/using-workflows/events-that-trigger-workflows#pull_request) event. In this example, the workflow run must have been triggered by a `pull_request` event in a repository named `octo-repo` that is owned by the `octo-org` organization:

* Syntax: `repo:<orgName/repoName>:pull_request`
* Syntax: `repo:ORG-NAME/REPO-NAME:pull_request`
* Example: `repo:octo-org/octo-repo:pull_request`

#### Filtering for a specific branch
Expand All @@ -200,7 +200,7 @@ The subject claim includes the branch name of the workflow, but only if the job

You can configure a subject that filters for a specific branch name. In this example, the workflow run must have originated from a branch named `demo-branch`, in a repository named `octo-repo` that is owned by the `octo-org` organization:

* Syntax: `repo:<orgName/repoName>:ref:refs/heads/branchName`
* Syntax: `repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME`
* Example: `repo:octo-org/octo-repo:ref:refs/heads/demo-branch`

#### Filtering for a specific tag
Expand All @@ -209,7 +209,7 @@ The subject claim includes the tag name of the workflow, but only if the job doe

You can create a subject that filters for specific tag. In this example, the workflow run must have originated with a tag named `demo-tag`, in a repository named `octo-repo` that is owned by the `octo-org` organization:

* Syntax: `repo:<orgName/repoName>:ref:refs/tags/<tagName>`
* Syntax: `repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME`
* Example: `repo:octo-org/octo-repo:ref:refs/tags/demo-tag`

### Configuring the subject in your cloud provider
Expand Down Expand Up @@ -304,7 +304,7 @@ Customizing the claims results in a new format for the entire `sub` claim, which

{% note %}

**Note**: The `sub` claim uses the shortened form `repo` (for example, `repo:<orgName/repoName>`) instead of `repository` to reference the repository.
**Note**: The `sub` claim uses the shortened form `repo` (for example, `repo:ORG-NAME/REPO-NAME`) instead of `repository` to reference the repository.

{% endnote %}

Expand Down Expand Up @@ -368,7 +368,7 @@ The following example template combines the requirement of a specific reusable w

{% data reusables.actions.use-request-body-api %}

This example also demonstrates how to use `"context"` to define your conditions. This is the part that follows the repository in the [default `sub` format](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims). For example, when the job references an environment, the context contains: `environment:<environmentName>`.
This example also demonstrates how to use `"context"` to define your conditions. This is the part that follows the repository in the [default `sub` format](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims). For example, when the job references an environment, the context contains: `environment:ENVIRONMENT-NAME`.

```json
{
Expand All @@ -382,7 +382,7 @@ This example also demonstrates how to use `"context"` to define your conditions.

In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include specific values for `repo`, `context`, and `job_workflow_ref`.

This customization template requires that the `sub` uses the following format: `repo:<orgName/repoName>:environment:<environmentName>:job_workflow_ref:<reusableWorkflowPath>`.
This customization template requires that the `sub` uses the following format: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH`.
For example: `"sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"`

#### Example: Granting access to a specific repository
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Edit the trust policy, adding the `sub` field to the validation conditions. For
}
```

If you use a workflow with an environment, the `sub` field must reference the environment name: `repo:OWNER/REPOSITORY:environment:NAME`. For more information, see "[AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token)."
If you use a workflow with an environment, the `sub` field must reference the environment name: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME`. For more information, see "[AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token)."

{% data reusables.actions.oidc-deployment-protection-rules %}

Expand Down Expand Up @@ -124,9 +124,9 @@ To update your workflows for OIDC, you will need to make two changes to your YAM

The `aws-actions/configure-aws-credentials` action receives a JWT from the {% data variables.product.prodname_dotcom %} OIDC provider, and then requests an access token from AWS. For more information, see the AWS [documentation](https://github.com/aws-actions/configure-aws-credentials).

* `<example-bucket-name>`: Add the name of your S3 bucket here.
* `<role-to-assume>`: Replace the example with your AWS role.
* `<example-aws-region>`: Add the name of your AWS region here.
* `BUCKET-NAME`: Add the name of your S3 bucket here.
* `AWS-REGION`: Add the name of your AWS region here.
* `ROLE-TO-ASSUME`: Replace this with your AWS role. For example, `arn:aws:iam::1234567890:role/example-role`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made <role-to-assume> a placeholder ROLE-TO-ASSUME with an example, and referenced that in the YAML file similar to what's in GCP documentation:

image


```yaml copy
# Sample workflow to access AWS resources when workflow is tied to branch
Expand All @@ -135,8 +135,8 @@ name: AWS example workflow
on:
push
env:
BUCKET_NAME : "<example-bucket-name>"
AWS_REGION : "<example-aws-region>"
BUCKET_NAME : "BUCKET-NAME"
AWS_REGION : "AWS-REGION"
# permission can be added at job level or workflow level
permissions:
id-token: write # This is required for requesting the JWT
Expand All @@ -150,7 +150,7 @@ jobs:
- name: configure aws credentials
uses: aws-actions/configure-aws-credentials@v3
with:
role-to-assume: arn:aws:iam::1234567890:role/example-role
role-to-assume: ROLE-TO-ASSUME
role-session-name: samplerolesession
aws-region: {% raw %}${{ env.AWS_REGION }}{% endraw %}
# Upload a file to AWS s3
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,8 @@ The `google-github-actions/auth` action receives a JWT from the {% data variable

This example has a job called `Get_OIDC_ID_token` that uses actions to request a list of services from GCP.

* `<example-workload-identity-provider>`: Replace this with the path to your identity provider in GCP. For example, `projects/<example-project-id>/locations/global/workloadIdentityPools/<name-of-pool>/providers/<name-of-provider>`
* `<example-service-account>`: Replace this with the name of your service account in GCP.
* `<project-id>`: Replace this with the ID of your GCP project.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The entire <project-id> line is removed as there is no reference in the YAML to this.

* `WORKLOAD-IDENTITY-PROVIDER`: Replace this with the path to your identity provider in GCP. For example, `projects/example-project-id/locations/global/workloadIdentityPools/name-of-pool/providers/name-of-provider`
* `SERVICE-ACCOUNT`: Replace this with the name of your service account in GCP.

This action exchanges a {% data variables.product.prodname_dotcom %} OIDC token for a Google Cloud access token, using [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation).

Expand All @@ -86,8 +85,8 @@ jobs:
uses: 'google-github-actions/auth@v0.3.1'
with:
create_credentials_file: 'true'
workload_identity_provider: '<example-workload-identity-provider>'
service_account: '<example-service-account>'
workload_identity_provider: 'WORKLOAD-IDENTITY-PROVIDER'
service_account: 'SERVICE-ACCOUNT'
- id: 'gcloud'
name: 'gcloud'
run: |-
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -124,10 +124,10 @@ The `hashicorp/vault-action` action receives a JWT from the {% data variables.pr

This example demonstrates how to create a job that requests a secret from HashiCorp Vault.

* `<Vault URL>`: Replace this with the URL of your HashiCorp Vault.
* `<Vault Namespace>`: Replace this with the Namespace you've set in HashiCorp Vault. For example: `admin`.
* `<Role name>`: Replace this with the role you've set in the HashiCorp Vault trust relationship.
* `<Secret-Path>`: Replace this with the path to the secret you're retrieving from HashiCorp Vault. For example: `secret/data/production/ci npmToken`.
* `VAULT-URL`: Replace this with the URL of your HashiCorp Vault.
* `VAULT-NAMESPACE`: Replace this with the Namespace you've set in HashiCorp Vault. For example: `admin`.
* `ROLE-NAME`: Replace this with the role you've set in the HashiCorp Vault trust relationship.
* `SECRET-PATH`: Replace this with the path to the secret you're retrieving from HashiCorp Vault. For example: `secret/data/production/ci npmToken`.

```yaml copy
jobs:
Expand All @@ -141,10 +141,10 @@ jobs:
uses: hashicorp/vault-action@v2.4.0
with:
method: jwt
url: <Vault URL>
namespace: <Vault Namespace - HCP Vault and Vault Enterprise only>
role: <Role name>
secrets: <Secret-Path>
url: VAULT-URL
namespace: VAULT-NAMESPACE # HCP Vault and Vault Enterprise only
role: ROLE-NAME
secrets: SECRET-PATH

- name: Use secret from Vault
run: |
Expand All @@ -156,7 +156,7 @@ jobs:
**Note**:

* If your Vault server is not accessible from the public network, consider using a self-hosted runner with other available Vault [auth methods](https://www.vaultproject.io/docs/auth). For more information, see "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners)."
* `<Vault Namespace>` must be set for a Vault Enterprise (including HCP Vault) deployment. For more information, see [Vault namespace](https://www.vaultproject.io/docs/enterprise/namespaces).
* `VAULT-NAMESPACE` must be set for a Vault Enterprise (including HCP Vault) deployment. For more information, see [Vault namespace](https://www.vaultproject.io/docs/enterprise/namespaces).

{% endnote %}

Expand All @@ -180,9 +180,9 @@ jobs:
with:
exportToken: true
method: jwt
url: <Vault URL>
role: <Role name>
secrets: <Secret-Path>
url: VAULT-URL
role: ROLE-NAME
secrets: SECRET-PATH

- name: Use secret from Vault
run: |
Expand All @@ -193,7 +193,7 @@ jobs:
if: always()
run: |
curl -X POST -sv -H "X-Vault-Token: {% raw %}${{ env.VAULT_TOKEN }}{% endraw %}" \
<Vault URL>/v1/auth/token/revoke-self
VAULT-URL/v1/auth/token/revoke-self
```

## Further reading
Expand Down
Loading