Configurando o OpenID Connect no HashiCorp Vault

Visão geral

O OpenID Connect (OIDC) permite aos seus fluxos de trabalho de GitHub Actions efetuar a autenticação com um HashiCorp Vault para recuperar segredos.

Este guia fornece uma visão geral sobre como configurar o HashiCorp Vault para confiar no OIDC do GitHub como uma identidade federada e demonstra como usar essa configuração na ação hashicorp/vault-action para recuperar segredos do HashiCorp Vault.

Pré-requisitos

• 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 obter mais informações, confira "Sobre o enrijecimento de segurança com o OpenID Connect".

• Se você estiver seguindo este guia sobre o GHE.com, entenda que você precisa substituir alguns valores na documentação a seguir. Confira "Sobre o enrijecimento de segurança com o OpenID Connect".

Adicionando o provedor de identidade ao HashiCorp Vault

Para usar OIDC com oHashiCorp Vault, você deverá adicionar uma configuração de confiança ao provedor do OIDC de GitHub. Para obter mais informações, confira a documentação do HashiCorp Vault.

Para configurar o servidor do Cofre para aceitar JWT (Tokens Web JSON) para autenticação:

1. Habilite o método auth do JWT e use write para aplicar a configuração ao Cofre. Para os parâmetros oidc_discovery_url e bound_issuer, use https://token.actions.githubusercontent.com. Esses parâmetros permitem que o servidor do Cofre verifique os JWT (Tokens Web JSON) recebidos durante o processo de autenticação.

   Shell

   vault auth enable jwt
   

   Shell

   vault write auth/jwt/config \
     bound_issuer="https://token.actions.githubusercontent.com" \
     oidc_discovery_url="https://token.actions.githubusercontent.com"
   

   Note

   Se uma URL de emissor exclusivo de uma empresa foi definida usando a API REST (conforme descrito em Sobre o enrijecimento de segurança com o OpenID Connect), os valores de bound_issuer e oidc_discover_url devem corresponder a essa URL exclusiva. Por exemplo, para uma empresa chamada octocat que usa a URL do emissor exclusiva, bound_issuer e oidc_discovery_url devem ser definidos como https://token.actions.githubusercontent.com/octocat.

2. Configure uma política que só concede acesso aos caminhos específicos que seus fluxos de trabalho usarão para recuperar segredos. Para obter políticas mais avançadas, confira a documentação de Políticas do HashiCorp Vault.

   Shell

   vault policy write myproject-production - <<EOF
   # Read-only permission on 'secret/data/production/*' path
   
   path "secret/data/production/*" {
     capabilities = [ "read" ]
   }
   EOF
   

3. Configure funções para agrupar políticas diferentes. Se a autenticação for bem-sucedida, essas políticas serão anexadas ao token de acesso resultante do Cofre.

   Shell

   vault write auth/jwt/role/myproject-production -<<EOF
   {
     "role_type": "jwt",
     "user_claim": "actor",
     "bound_claims": {
       "repository": "user-or-org-name/repo-name"
     },
     "policies": ["myproject-production"],
     "ttl": "10m"
   }
   EOF
   

• ttl define a validade do token de acesso resultante.
• Verifique se o parâmetro bound_claims está definido para seus requisitos de segurança e tenha pelo menos uma condição. Opcionalmente, você também pode definir o parâmetro bound_subject, bem como o parâmetro bound_audiences.
• Para verificar as declarações arbitrárias no conteúdo JWT recebido, o parâmetro bound_claims contém um conjunto de declarações e seus valores necessários. No exemplo acima, a função aceitará quaisquer solicitações de autenticação de entrada do repositório repo-name pertencente à conta user-or-org-name.
• Para ver todas as declarações compatíveis com o provedor OIDC do GitHub, confira Sobre o enrijecimento de segurança com o OpenID Connect.

Para obter mais informações, confira a documentação do HashiCorp Vault.

Atualizar o seu fluxo de trabalho de GitHub Actions

Para atualizar seus fluxos de trabalho para o OIDC, você deverá fazer duas alterações no seu YAML:

1. Adicionar configurações de permissões para o token.
2. Use a ação hashicorp/vault-action para trocar o token OIDC (JWT) por um token de acesso à nuvem.

Para adicionar a integração do OIDC a seus fluxos de trabalho que lhes permitem acessar os segredos no Vault, você deverá adicionar as seguintes alterações de código:

• Conceder permissão para obter o token do provedor do OIDC de GitHub:
  • O fluxo de trabalho precisa de configurações permissions: com o valor de id-token definido como write. Isso permite obter o token do OIDC de cada trabalho do fluxo de trabalho.
• Solicite o JWT do provedor do OIDC GitHub e apresente-o ao HashiCorp Vault para receber um token de acesso:
  • Você pode usar a ação hashicorp/vault-action para buscar o JWT e receber o token de acesso do Cofre ou pode usar o kit de ferramentas do Actions para buscar os tokens para seu trabalho.

Este exemplo demonstra como usar o OIDC com a ação oficial para solicitar um segredo ao HashiCorp Vault.

Adicionando configurações de permissões

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, consulte "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

Talvez seja necessário 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 obter mais informações, confira "Reutilizar fluxos de trabalho".

Solicitando o token de acesso

A ação hashicorp/vault-action recebe um JWT do provedor OIDC do GitHub e solicita um token de acesso da sua instância do HashiCorp Vault para recuperar segredos. Para obter mais informações, confira a documentação do HashiCorp Vault GitHub Action.

Este exemplo demonstra como criar um trabalho que solicita um segredo para o HashiCorp Vault.

• VAULT-URL: substitua isso pela URL do seu HashiCorp Vault.
• VAULT-NAMESPACE: substitua isso pelo Namespace que você definiu no HashiCorp Vault. Por exemplo: admin.
• ROLE-NAME: substitua isso pela função que você definiu na relação de confiança do HashiCorp Vault.
• SECRET-PATH: substitua isso pelo caminho para o segredo que está sendo recuperado do HashiCorp Vault. Por exemplo: secret/data/production/ci npmToken.

jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        with:
          method: jwt
          url: VAULT-URL
          namespace: VAULT-NAMESPACE # HCP Vault and Vault Enterprise only
          role: ROLE-NAME
          secrets: SECRET-PATH

      - name: Use secret from Vault
        run: |
          # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.

jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        with:
          method: jwt
          url: VAULT-URL
          namespace: VAULT-NAMESPACE # HCP Vault and Vault Enterprise only
          role: ROLE-NAME
          secrets: SECRET-PATH

      - name: Use secret from Vault
        run: |
          # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.

Revogando o token de acesso

Por padrão, o servidor do Cofre revogará automaticamente os tokens de acesso quando a TTL expirar, para que você não precise revogar manualmente os tokens de acesso. No entanto, se você quiser revogar tokens de acesso imediatamente após a conclusão ou falha do trabalho, será possível fazer isso manualmente usando a API do Cofre.

1. Defina a opção exportToken como true (padrão: false). Isso exporta o token de acesso do Cofre emitido como uma variável de ambiente: VAULT_TOKEN.
2. Adicione uma etapa para chamar a API do Cofre de Revogação de um Token (Auto) para revogar o token de acesso.

jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        with:
          exportToken: true
          method: jwt
          url: VAULT-URL
          role: ROLE-NAME
          secrets: SECRET-PATH

      - name: Use secret from Vault
        run: |
          # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.

      - name: Revoke token
        # This step always runs at the end regardless of the previous steps result
        if: always()
        run: |
          curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \
            VAULT-URL/v1/auth/token/revoke-self

jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        with:
          exportToken: true
          method: jwt
          url: VAULT-URL
          role: ROLE-NAME
          secrets: SECRET-PATH

      - name: Use secret from Vault
        run: |
          # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.

      - name: Revoke token
        # This step always runs at the end regardless of the previous steps result
        if: always()
        run: |
          curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \
            VAULT-URL/v1/auth/token/revoke-self

Leitura adicional

• Usando o OpenID Connect com fluxos de trabalho reutilizáveis - Sobre executores auto-hospedados