Configuring OpenID Connect in Google Cloud Platform

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in Google Cloud Platform (GCP), without needing to store the GCP credentials as long-lived GitHub secrets.

This guide gives an overview of how to configure GCP to trust GitHub's OIDC as a federated identity, and includes a workflow example for the google-github-actions/auth action that uses tokens to authenticate to GCP and access resources.

Prerequisites

• Para saber os conceitos básicos de como o GitHub usa o OIDC (OpenID Connect), além da arquitetura e dos benefícios, confira Sobre o enrijecimento de segurança com o OpenID Connect.

• Antes de prosseguir, você deve planejar sua estratégia de segurança para garantir que os tokens de acesso sejam atribuídos apenas de forma previsível. Para controlar como o provedor de nuvem emite os tokens de acesso, você precisa definir, pelo menos, uma condição, para que os repositórios não confiáveis não possam solicitar tokens de acesso aos seus recursos de nuvem. Para saber mais, confira Sobre o enrijecimento de segurança com o OpenID Connect.

• Você deve garantir que os seguintes pontos de extremidade OIDC sejam acessíveis pelo seu provedor de nuvem:

  • https://HOSTNAME/_services/token/.well-known/openid-configuration
  • https://HOSTNAME/_services/token/.well-known/jwks

  Observação

  Google Cloud Platform does not have fixed IP ranges defined for these endpoints.

• 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 Sobre o enrijecimento de segurança com o OpenID Connect.

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.

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. For an example, see 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.
• The Issuer URL to use: https://HOSTNAME/_services/token

Updating your GitHub 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 action to exchange the OIDC token (JWT) for a cloud access token.

Adding permissions settings

A execução do trabalho ou do fluxo de trabalho requer uma permissions configuração para id-token: write permitir que o provedor OIDC do GitHub crie um JSON Web Token para cada execução. Você não poderá solicitar o token de ID JWT do OIDC se as permissions para id-token não estiverem definidas como write; no entanto, esse valor não implica a concessão de acesso para gravação a nenhum recurso, apenas a possibilidade de buscar e definir o token OIDC para uma ação ou etapa para habilitar a autenticação com um token de acesso de curta duração. Qualquer configuração de confiança real é definida usando declarações OIDC; para obter mais informações, confira Sobre o enrijecimento de segurança com o OpenID Connect.

A configuração id-token: writepermite que o JWT seja solicitado do provedor OIDC do GitHub usando uma destas abordagens:

• Usando variáveis de ambiente no executor (ACTIONS_ID_TOKEN_REQUEST_URL e ACTIONS_ID_TOKEN_REQUEST_TOKEN).
• Usando getIDToken() por meio do kit de ferramentas do Actions.

Se você precisar buscar um token OIDC para um fluxo de trabalho, a permissão poderá ser definida no nível do fluxo de trabalho. Por exemplo:

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

Se você só precisa obter um token OIDC para um único trabalho, essa permissão poderá ser definida dentro desse trabalho. Por exemplo:

permissions:
  id-token: write # This is required for requesting the JWT

permissions:
  id-token: write # This is required for requesting the JWT

Você pode precisar especificar permissões adicionais aqui, dependendo das necessidades do seu fluxo de trabalho.

Para fluxos de trabalho reutilizáveis pertencentes ao mesmo usuário, organização ou empresa que o fluxo de trabalho do chamador, o token OIDC gerado no fluxo de trabalho reutilizável pode ser acessado no contexto do chamador. Para fluxos de trabalho reutilizáveis fora de sua empresa ou organização, a configuração permissions para id-token deve ser explicitamente definida como write no nível do fluxo de trabalho do chamador ou no trabalho específico que chama o fluxo de trabalho reutilizável. Isso garante que o token OIDC gerado no fluxo de trabalho reutilizável só tenha permissão para ser consumido nos fluxos de trabalho do chamador quando pretendido.

Para saber mais, confira Reusing workflows.

Requesting the access token

The google-github-actions/auth action receives a JWT from the GitHub OIDC provider, and then requests an access token from GCP. For more information, see the GCP documentation.

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

• 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 GitHub OIDC token for a Google Cloud access token, using Workload Identity Federation.

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/auth@f1e2d3c4b5a6f7e8d9c0b1a2c3d4e5f6a7b8c9d0'
      with:
          create_credentials_file: 'true'
          workload_identity_provider: 'WORKLOAD-IDENTITY-PROVIDER'
          service_account: 'SERVICE-ACCOUNT'
    - id: 'gcloud'
      name: 'gcloud'
      run: |-
        gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}"
        gcloud services list

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/auth@f1e2d3c4b5a6f7e8d9c0b1a2c3d4e5f6a7b8c9d0'
      with:
          create_credentials_file: 'true'
          workload_identity_provider: 'WORKLOAD-IDENTITY-PROVIDER'
          service_account: 'SERVICE-ACCOUNT'
    - id: 'gcloud'
      name: 'gcloud'
      run: |-
        gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}"
        gcloud services list

Further reading

• Using OpenID Connect with reusable workflows
• Como se comunicar com executores auto-hospedados