Merge branch 'main' into openapi-update-ffe1dfa66820f9c14bf436aaaaac1…

…1b661118a335f1ce153bd11dbc25a39dac1
my-lambda-projects · Oct 26, 2021 · 2429de0 · 2429de0
2 parents e15fb03 + ab17d83
commit 2429de0
Show file tree

Hide file tree

Showing 12 changed files with 424 additions and 10 deletions.
diff --git a/assets/images/help/codespaces/codespaces-configure-features.png b/assets/images/help/codespaces/codespaces-configure-features.png
diff --git a/...ploying-to-your-cloud-provider/deploying-to-amazon-elastic-container-service.md b/...ploying-to-your-cloud-provider/deploying-to-amazon-elastic-container-service.md
@@ -31,7 +31,7 @@ On every new push to `main` in your {% data variables.product.company_short %} r
 
 {% note %}
 
-**Note**: {% data reusables.actions.about-oidc-short-overview %}
+**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).
 
 {% endnote %}
 

diff --git a/...s/deployment/deploying-to-your-cloud-provider/deploying-to-azure-app-service.md b/...s/deployment/deploying-to-your-cloud-provider/deploying-to-azure-app-service.md
@@ -31,7 +31,7 @@ Azure App Service can run web apps in several languages, but this guide demonstr
 
 {% note %}
 
-**Note**: {% data reusables.actions.about-oidc-short-overview %}
+**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)."
 
 {% endnote %}
 

diff --git a/...rity-hardening-your-deployments/about-security-hardening-with-openid-connect.md b/...rity-hardening-your-deployments/about-security-hardening-with-openid-connect.md
@@ -224,6 +224,13 @@ You can now update your YAML workflows to use OIDC access tokens instead of secr
 
 ## Enabling OpenID Connect for your cloud provider
 
-To enable and configure OIDC for your cloud provider, see the following guide:
+To enable and configure OIDC for your specific cloud provider, see the following guides:
+
+- ["Configuring OpenID Connect in Amazon Web Services"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
+- ["Configuring OpenID Connect in Azure"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure)
+- ["Configuring OpenID Connect in Google Cloud Platform"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform)
+- ["Configuring OpenID Connect in Hashicorp Vault"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault)
+
+To enable and configure OIDC for another cloud provider, see the following guide:
 
 - ["Configuring OpenID Connect in cloud providers"](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers)
diff --git a/...hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md b/...hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md
@@ -0,0 +1,104 @@
+---
+title: Configuring OpenID Connect in Amazon Web Services
+shortTitle: Configuring OpenID Connect in Amazon Web Services
+intro: 'Use OpenID Connect within your workflows to authenticate with Amazon Web Services.'
+miniTocMaxHeadingLevel: 3
+versions:
+  fpt: '*'
+  ghae: 'issue-4856'
+  ghec: '*'
+type: tutorial
+topics:
+  - Security
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+## Overview
+
+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. 
+
+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.
+
+## Prerequisites
+
+{% data reusables.actions.oidc-link-to-intro %}
+
+{% data reusables.actions.oidc-security-notice %}
+
+## Adding the identity provider to AWS
+
+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).
+
+- For the provider URL: Use `https://token.actions.githubusercontent.com`
+- For the "Audience": Use `sts.amazonaws.com` if you are using the [official action](https://github.com/aws-actions/configure-aws-credentials).
+
+### 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).
+
+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:
+
+```yaml{:copy}
+"Condition": {
+  "StringEquals": {
+    "token.actions.githubusercontent.com:aud": "https://github.com/octo-org",
+    "token.actions.githubusercontent.com:sub": "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
+```
+
+## Updating your {% data variables.product.prodname_actions %} workflow
+
+To update your workflows for OIDC, you will need to make two changes to your YAML:
+1. Add permissions settings for the token.
+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.
+
+### Adding permissions settings
+
+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:
+
+```yaml{:copy}
+permissions:
+  id-token: write
+```
+
+You may need to specify additional permissions here, depending on your workflow's requirements. 
+
+### Requesting the access token
+
+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.
+
+```yaml{:copy}
+# Sample workflow to access AWS resources when workflow is tied to branch
+# The workflow Creates static website using aws s3
+name: AWS example workflow
+on:
+  push
+env:
+  BUCKET_NAME : "<example-bucket-name>"
+  AWS_REGION : "<example-aws-region>"
+# permission can be added at job level or workflow level    
+permissions:
+      id-token: write
+      contents: write    # This is required for actions/checkout@v1
+jobs:
+  S3PackageUpload:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Git clone the repository
+        uses: actions/checkout@v1
+      - name: configure aws credentials
+        uses: aws-actions/configure-aws-credentials@master
+        with:
+          role-to-assume: arn:aws:iam::1234567890:role/example-role
+          role-session-name: samplerolesession
+          aws-region: ${{ env.AWS_REGION }}
+      # Upload a file to AWS s3
+      - name:  Copy index.html to s3
+        run: |
+          aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/
+```
diff --git a/...ment/security-hardening-your-deployments/configuring-openid-connect-in-azure.md b/...ment/security-hardening-your-deployments/configuring-openid-connect-in-azure.md
@@ -0,0 +1,100 @@
+---
+title: Configuring OpenID Connect in Azure
+shortTitle: Configuring OpenID Connect in Azure
+intro: 'Use OpenID Connect within your workflows to authenticate with Azure.'
+miniTocMaxHeadingLevel: 3
+versions:
+  fpt: '*'
+  ghae: 'issue-4856'
+  ghec: '*'
+type: tutorial
+topics:
+  - Security
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+## Overview
+
+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. 
+
+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.
+
+## Prerequisites
+
+{% data reusables.actions.oidc-link-to-intro %}
+
+{% data reusables.actions.oidc-security-notice %}
+
+## Adding the Federated Credentials to Azure
+
+{% 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)."
+
+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).
+
+1. Create an Active Directory application and a service principal.
+2. Add federated credentials for the Active Directory application.
+3. Create {% data variables.product.prodname_dotcom %} secrets for storing Azure configuration.
+
+Additional guidance for configuring the identity provider:
+
+- 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).
+- For the `audience` setting,  `api://AzureADTokenExchange` is the recommended value, but you can also specify other values here.
+
+## Updating your {% data variables.product.prodname_actions %} workflow
+
+To update your workflows for OIDC, you will need to make two changes to your YAML:
+1. Add permissions settings for the token.
+2. Use the [`azure/login`](https://github.com/Azure/login) action to exchange the OIDC token (JWT) for a cloud access token.
+
+### Adding permissions settings
+
+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:
+
+```yaml{:copy}
+permissions:
+  id-token: write
+```
+
+You may need to specify additional permissions here, depending on your workflow's requirements. 
+
+### Requesting the access token
+
+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.
+
+The following example exchanges an OIDC ID token with Azure to receive an access token, which can then be used to access cloud resources.
+
+```yaml{:copy}
+name: Run Azure Login with OpenID Connect
+on: [push]
+
+permissions:
+      id-token: write
+      
+jobs: 
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+        
+    - name: Installing CLI-beta for OpenID Connect
+      run: |
+        cd ../..
+        CWD="$(pwd)"
+        python3 -m venv oidc-venv
+        . oidc-venv/bin/activate
+        echo "activated environment"
+        python3 -m pip install -q --upgrade pip
+        echo "started installing cli beta"
+        pip install -q --extra-index-url https://azcliprod.blob.core.windows.net/beta/simple/ azure-cli
+        echo "***************installed cli beta*******************"
+        echo "$CWD/oidc-venv/bin" >> $GITHUB_PATH
+        
+    - name: 'Az CLI login'
+      uses: azure/[email protected]
+      with:
+        client-id: {% raw %}${{ secrets.AZURE_CLIENTID }}{% endraw %}
+        tenant-id: {% raw %}${{ secrets.AZURE_TENANTID }}{% endraw %}
+        subscription-id: {% raw %}${{ secrets.AZURE_SUBSCRIPTIONID }}{% endraw %}
+```
+
diff --git a/...ity-hardening-your-deployments/configuring-openid-connect-in-cloud-providers.md b/...ity-hardening-your-deployments/configuring-openid-connect-in-cloud-providers.md
@@ -37,17 +37,15 @@ If your cloud provider doesn't yet offer an official action, you can update your
 
 ### Adding permissions settings
 
-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:
-
-```yaml
-name: Example deployment workflow
-on:
-  workflow_dispatch:
+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:
 
+```yaml{:copy}
 permissions:
   id-token: write
 ```
 
+You may need to specify additional permissions here, depending on your workflow's requirements. 
+
 ### Using official actions
 
 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.

diff --git a/...rdening-your-deployments/configuring-openid-connect-in-google-cloud-platform.md b/...rdening-your-deployments/configuring-openid-connect-in-google-cloud-platform.md
@@ -0,0 +1,99 @@
+---
+title: Configuring OpenID Connect in Google Cloud Platform
+shortTitle: Configuring OpenID Connect in Google Cloud Platform
+intro: 'Use OpenID Connect within your workflows to authenticate with Google Cloud Platform.'
+miniTocMaxHeadingLevel: 3
+versions:
+  fpt: '*'
+  ghae: 'issue-4856'
+  ghec: '*'
+type: tutorial
+topics:
+  - Security
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+## Overview
+
+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. 
+
+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.
+
+## Prerequisites
+
+{% data reusables.actions.oidc-link-to-intro %}
+
+{% data reusables.actions.oidc-security-notice %}
+
+## Adding a Google Cloud Workload Identity Provider
+
+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).
+
+1. Create a new identity pool.
+2. Configure the mapping and add conditions.
+3. Connect the new pool to a service account. 
+
+Additional guidance for configuring the identity provider:
+
+- 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).
+- 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).
+- The Issuer URL to use: `https://token.actions.githubusercontent.com`
+
+## Updating your {% data variables.product.prodname_actions %} workflow
+
+To update your workflows for OIDC, you will need to make two changes to your YAML:
+1. Add permissions settings for the token.
+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.
+
+### Adding permissions settings
+
+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:
+
+```yaml{:copy}
+permissions:
+  id-token: write
+```
+
+You may need to specify additional permissions here, depending on your workflow's requirements. 
+
+### Requesting the access token
+
+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).
+
+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.
+
+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).
+
+```yaml{:copy}
+name: List services in GCP
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  id-token: write
+
+jobs:
+  Get_OIDC_ID_token:
+    runs-on: ubuntu-latest
+    steps:
+    - id: 'auth'
+      name: 'Authenticate to GCP'
+      uses: 'google-github-actions/[email protected]'
+      with:
+          create_credentials_file: 'true'
+          workload_identity_provider: '<example-workload-identity-provider>'
+          service_account: '<example-service-account>'
+    - id: 'gcloud'
+      name: 'gcloud'
+      run: |-
+        gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}"
+        gcloud config list
+```