Skip to content

Commit 99a4d42

Browse files
Martin LopesimjohnboSarah Edwardshubwriter
authored
[Oct 26, 2021] Deployments: Authenticating with OpenID Connect (#21775)
Co-authored-by: John Bohannon <imjohnbo@github.com> Co-authored-by: Sarah Edwards <skedwards88@github.com> Co-authored-by: hubwriter <hubwriter@github.com>
1 parent f139bde commit 99a4d42

10 files changed

Lines changed: 415 additions & 10 deletions

‎content/actions/deployment/deploying-to-your-cloud-provider/deploying-to-amazon-elastic-container-service.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ On every new push to `main` in your {% data variables.product.company_short %} r
3131

3232
{% note %}
3333

34-
**Note**: {% data reusables.actions.about-oidc-short-overview %}
34+
**Note**: {% data reusables.actions.about-oidc-short-overview %} and ["Configuring OpenID Connect in Amazon Web Services"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services).
3535

3636
{% endnote %}
3737

‎content/actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure-app-service.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Azure App Service can run web apps in several languages, but this guide demonstr
3131

3232
{% note %}
3333

34-
**Note**: {% data reusables.actions.about-oidc-short-overview %}
34+
**Note**: {% data reusables.actions.about-oidc-short-overview %} and "[Configuring OpenID Connect in Azure](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure)."
3535

3636
{% endnote %}
3737

‎content/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,13 @@ You can now update your YAML workflows to use OIDC access tokens instead of secr
224224

225225
## Enabling OpenID Connect for your cloud provider
226226

227-
To enable and configure OIDC for your cloud provider, see the following guide:
227+
To enable and configure OIDC for your specific cloud provider, see the following guides:
228+
229+
- ["Configuring OpenID Connect in Amazon Web Services"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
230+
- ["Configuring OpenID Connect in Azure"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure)
231+
- ["Configuring OpenID Connect in Google Cloud Platform"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform)
232+
- ["Configuring OpenID Connect in Hashicorp Vault"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault)
233+
234+
To enable and configure OIDC for another cloud provider, see the following guide:
228235

229236
- ["Configuring OpenID Connect in cloud providers"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers)

‎content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Configuring OpenID Connect in Amazon Web Services
3+
shortTitle: Configuring OpenID Connect in Amazon Web Services
4+
intro: 'Use OpenID Connect within your workflows to authenticate with Amazon Web Services.'
5+
miniTocMaxHeadingLevel: 3
6+
versions:
7+
fpt: '*'
8+
ghae: 'issue-4856'
9+
ghec: '*'
10+
type: tutorial
11+
topics:
12+
- Security
13+
---
14+
15+
{% data reusables.actions.enterprise-beta %}
16+
{% data reusables.actions.enterprise-github-hosted-runners %}
17+
18+
## Overview
19+
20+
OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to access resources in Amazon Web Services (AWS), without needing to store the AWS credentials as long-lived {% data variables.product.prodname_dotcom %} secrets.
21+
22+
This guide explains how to configure AWS to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and includes a workflow example for the [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) that uses tokens to authenticate to AWS and access resources.
23+
24+
## Prerequisites
25+
26+
{% data reusables.actions.oidc-link-to-intro %}
27+
28+
{% data reusables.actions.oidc-security-notice %}
29+
30+
## Adding the identity provider to AWS
31+
32+
To add the {% data variables.product.prodname_dotcom %} OIDC provider to IAM, see the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html).
33+
34+
- For the provider URL: Use `https://token.actions.githubusercontent.com`
35+
- For the "Audience": Use `sts.amazonaws.com` if you are using the [official action](https://github.com/aws-actions/configure-aws-credentials).
36+
37+
### Configuring the role and trust policy
38+
39+
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).
40+
41+
By default, the validation only includes the audience (`aud`) condition, so you must manually add a subject (`sub`) condition. Edit the trust relationship to add the `sub` field to the validation conditions. For example:
42+
43+
```yaml{:copy}
44+
"Condition": {
45+
"StringEquals": {
46+
"token.actions.githubusercontent.com:aud": "https://github.com/octo-org",
47+
"token.actions.githubusercontent.com:sub": "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
48+
```
49+
50+
## Updating your {% data variables.product.prodname_actions %} workflow
51+
52+
To update your workflows for OIDC, you will need to make two changes to your YAML:
53+
1. Add permissions settings for the token.
54+
2. Use the [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) action to exchange the OIDC token (JWT) for a cloud access token.
55+
56+
### Adding permissions settings
57+
58+
The workflow will require a `permissions` setting with a defined [`id-token`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) value. If you only need to fetch an OIDC token for a single job, then this permission can be set within that job. For example:
59+
60+
```yaml{:copy}
61+
permissions:
62+
id-token: write
63+
```
64+
65+
You may need to specify additional permissions here, depending on your workflow's requirements.
66+
67+
### Requesting the access token
68+
69+
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).
70+
71+
- `<example-bucket-name>`: Add the name of your S3 bucket here.
72+
- `<role-to-assume>`: Replace the example with your AWS role.
73+
- `<example-aws-region>`: Add the name of your AWs region here.
74+
75+
```yaml{:copy}
76+
# Sample workflow to access AWS resources when workflow is tied to branch
77+
# The workflow Creates static website using aws s3
78+
name: AWS example workflow
79+
on:
80+
push
81+
env:
82+
BUCKET_NAME : "<example-bucket-name>"
83+
AWS_REGION : "<example-aws-region>"
84+
# permission can be added at job level or workflow level
85+
permissions:
86+
id-token: write
87+
contents: write # This is required for actions/checkout@v1
88+
jobs:
89+
S3PackageUpload:
90+
runs-on: ubuntu-latest
91+
steps:
92+
- name: Git clone the repository
93+
uses: actions/checkout@v1
94+
- name: configure aws credentials
95+
uses: aws-actions/configure-aws-credentials@master
96+
with:
97+
role-to-assume: arn:aws:iam::1234567890:role/example-role
98+
role-session-name: samplerolesession
99+
aws-region: ${{ env.AWS_REGION }}
100+
# Upload a file to AWS s3
101+
- name: Copy index.html to s3
102+
run: |
103+
aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/
104+
```

‎content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Configuring OpenID Connect in Azure
3+
shortTitle: Configuring OpenID Connect in Azure
4+
intro: 'Use OpenID Connect within your workflows to authenticate with Azure.'
5+
miniTocMaxHeadingLevel: 3
6+
versions:
7+
fpt: '*'
8+
ghae: 'issue-4856'
9+
ghec: '*'
10+
type: tutorial
11+
topics:
12+
- Security
13+
---
14+
15+
{% data reusables.actions.enterprise-beta %}
16+
{% data reusables.actions.enterprise-github-hosted-runners %}
17+
18+
## Overview
19+
20+
OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to access resources in Azure, without needing to store the Azure credentials as long-lived {% data variables.product.prodname_dotcom %} secrets.
21+
22+
This guide gives an overview of how to configure Azure to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and includes a workflow example for the [`azure/login`](https://github.com/Azure/login) action that uses tokens to authenticate to Azure and access resources.
23+
24+
## Prerequisites
25+
26+
{% data reusables.actions.oidc-link-to-intro %}
27+
28+
{% data reusables.actions.oidc-security-notice %}
29+
30+
## Adding the Federated Credentials to Azure
31+
32+
{% data variables.product.prodname_dotcom %}'s OIDC provider works with Azure's workload identity federation. For an overview, see Microsoft's documentation at "[Workload identity federation](https://docs.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation)."
33+
34+
To configure the OIDC identity provider in Azure, you will need to perform the following configuration. For instructions on making these changes, refer to [the Azure documentation](https://docs.microsoft.com/en-us/azure/developer/github/connect-from-azure).
35+
36+
1. Create an Active Directory application and a service principal.
37+
2. Add federated credentials for the Active Directory application.
38+
3. Create {% data variables.product.prodname_dotcom %} secrets for storing Azure configuration.
39+
40+
Additional guidance for configuring the identity provider:
41+
42+
- For security hardening, make sure you've reviewed ["Configuring the OIDC trust with the cloud"](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-oidc-trust-with-the-cloud). For an example, see ["Configuring the subject in your cloud provider"](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-subject-in-your-cloud-provider).
43+
- For the `audience` setting, `api://AzureADTokenExchange` is the recommended value, but you can also specify other values here.
44+
45+
## Updating your {% data variables.product.prodname_actions %} workflow
46+
47+
To update your workflows for OIDC, you will need to make two changes to your YAML:
48+
1. Add permissions settings for the token.
49+
2. Use the [`azure/login`](https://github.com/Azure/login) action to exchange the OIDC token (JWT) for a cloud access token.
50+
51+
### Adding permissions settings
52+
53+
The workflow will require a `permissions` setting with a defined [`id-token`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) value. If you only need to fetch an OIDC token for a single job, then this permission can be set within that job. For example:
54+
55+
```yaml{:copy}
56+
permissions:
57+
id-token: write
58+
```
59+
60+
You may need to specify additional permissions here, depending on your workflow's requirements.
61+
62+
### Requesting the access token
63+
64+
The [`azure/login`](https://github.com/Azure/login) action receives a JWT from the {% data variables.product.prodname_dotcom %} OIDC provider, and then requests an access token from Azure. For more information, see the [`azure/login`](https://github.com/Azure/login) documentation.
65+
66+
The following example exchanges an OIDC ID token with Azure to receive an access token, which can then be used to access cloud resources.
67+
68+
```yaml{:copy}
69+
name: Run Azure Login with OpenID Connect
70+
on: [push]
71+
72+
permissions:
73+
id-token: write
74+
75+
jobs:
76+
build-and-deploy:
77+
runs-on: ubuntu-latest
78+
steps:
79+
80+
- name: Installing CLI-beta for OpenID Connect
81+
run: |
82+
cd ../..
83+
CWD="$(pwd)"
84+
python3 -m venv oidc-venv
85+
. oidc-venv/bin/activate
86+
echo "activated environment"
87+
python3 -m pip install -q --upgrade pip
88+
echo "started installing cli beta"
89+
pip install -q --extra-index-url https://azcliprod.blob.core.windows.net/beta/simple/ azure-cli
90+
echo "***************installed cli beta*******************"
91+
echo "$CWD/oidc-venv/bin" >> $GITHUB_PATH
92+
93+
- name: 'Az CLI login'
94+
uses: azure/login@v1.4.0
95+
with:
96+
client-id: {% raw %}${{ secrets.AZURE_CLIENTID }}{% endraw %}
97+
tenant-id: {% raw %}${{ secrets.AZURE_TENANTID }}{% endraw %}
98+
subscription-id: {% raw %}${{ secrets.AZURE_SUBSCRIPTIONID }}{% endraw %}
99+
```
100+

‎content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,17 +37,15 @@ If your cloud provider doesn't yet offer an official action, you can update your
3737

3838
### Adding permissions settings
3939

40-
The workflow will likely require a `permissions` setting with a defined [`id-token`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) value. For example:
41-
42-
```yaml
43-
name: Example deployment workflow
44-
on:
45-
workflow_dispatch:
40+
The workflow will require a `permissions` setting with a defined [`id-token`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) value. If you only need to fetch an OIDC token for a single job, then this permission can be set within that job. For example:
4641

42+
```yaml{:copy}
4743
permissions:
4844
id-token: write
4945
```
5046

47+
You may need to specify additional permissions here, depending on your workflow's requirements.
48+
5149
### Using official actions
5250

5351
If your cloud provider has created an official action for using OIDC with {% data variables.product.prodname_actions %}, it will allow you to easily exchange the OIDC token for an access token. You can then update your workflows to use this token when accessing cloud resources.

‎content/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: Configuring OpenID Connect in Google Cloud Platform
3+
shortTitle: Configuring OpenID Connect in Google Cloud Platform
4+
intro: 'Use OpenID Connect within your workflows to authenticate with Google Cloud Platform.'
5+
miniTocMaxHeadingLevel: 3
6+
versions:
7+
fpt: '*'
8+
ghae: 'issue-4856'
9+
ghec: '*'
10+
type: tutorial
11+
topics:
12+
- Security
13+
---
14+
15+
{% data reusables.actions.enterprise-beta %}
16+
{% data reusables.actions.enterprise-github-hosted-runners %}
17+
18+
## Overview
19+
20+
OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to access resources in Google Cloud Platform (GCP), without needing to store the GCP credentials as long-lived {% data variables.product.prodname_dotcom %} secrets.
21+
22+
This guide gives an overview of how to configure GCP to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and includes a workflow example for the [`google-github-actions/auth`](https://github.com/google-github-actions/auth) action that uses tokens to authenticate to GCP and access resources.
23+
24+
## Prerequisites
25+
26+
{% data reusables.actions.oidc-link-to-intro %}
27+
28+
{% data reusables.actions.oidc-security-notice %}
29+
30+
## Adding a Google Cloud Workload Identity Provider
31+
32+
To configure the OIDC identity provider in GCP, you will need to perform the following configuration. For instructions on making these changes, refer to [the GCP documentation](https://github.com/google-github-actions/auth).
33+
34+
1. Create a new identity pool.
35+
2. Configure the mapping and add conditions.
36+
3. Connect the new pool to a service account.
37+
38+
Additional guidance for configuring the identity provider:
39+
40+
- For security hardening, make sure you've reviewed ["Configuring the OIDC trust with the cloud"](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-oidc-trust-with-the-cloud). For an example, see ["Configuring the subject in your cloud provider"](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-subject-in-your-cloud-provider).
41+
- For the service account to be available for configuration, it needs to be assigned to the `roles/iam.workloadIdentityUser` role. For more information, see [the GCP documentation](https://cloud.google.com/iam/docs/workload-identity-federation?_ga=2.114275588.-285296507.1634918453#conditions).
42+
- The Issuer URL to use: `https://token.actions.githubusercontent.com`
43+
44+
## Updating your {% data variables.product.prodname_actions %} workflow
45+
46+
To update your workflows for OIDC, you will need to make two changes to your YAML:
47+
1. Add permissions settings for the token.
48+
2. Use the [`google-github-actions/auth`](https://github.com/google-github-actions/auth) action to exchange the OIDC token (JWT) for a cloud access token.
49+
50+
### Adding permissions settings
51+
52+
The workflow will require a `permissions` setting with a defined [`id-token`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) value. If you only need to fetch an OIDC token for a single job, then this permission can be set within that job. For example:
53+
54+
```yaml{:copy}
55+
permissions:
56+
id-token: write
57+
```
58+
59+
You may need to specify additional permissions here, depending on your workflow's requirements.
60+
61+
### Requesting the access token
62+
63+
The `google-github-actions/auth` action receives a JWT from the {% data variables.product.prodname_dotcom %} OIDC provider, and then requests an access token from GCP. For more information, see the GCP [documentation](https://github.com/google-github-actions/auth).
64+
65+
This example has a job called `Get_OIDC_ID_token` that uses actions to request a list of services from GCP.
66+
67+
- `<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>`
68+
- `<example-service-account>`: Replace this with the name of your service account in GCP.
69+
- `<project-id>`: Replace this with the ID of your GCP project.
70+
71+
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).
72+
73+
```yaml{:copy}
74+
name: List services in GCP
75+
on:
76+
pull_request:
77+
branches:
78+
- main
79+
80+
permissions:
81+
id-token: write
82+
83+
jobs:
84+
Get_OIDC_ID_token:
85+
runs-on: ubuntu-latest
86+
steps:
87+
- id: 'auth'
88+
name: 'Authenticate to GCP'
89+
uses: 'google-github-actions/auth@v0.3.1'
90+
with:
91+
create_credentials_file: 'true'
92+
workload_identity_provider: '<example-workload-identity-provider>'
93+
service_account: '<example-service-account>'
94+
- id: 'gcloud'
95+
name: 'gcloud'
96+
run: |-
97+
gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}"
98+
gcloud config list
99+
```

0 commit comments

Comments
 (0)