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

   Observação

   Se uma URL de emissor exclusivo de uma empresa foi definida usando a API REST (conforme descrito em 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 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 configuração permissions com id-token: write para permitir que o provedor OIDC do GitHub crie um JSON Web Token para cada execução.

Para obter informações detalhadas sobre permissões necessárias, exemplos de configuração e cenários avançados, confira Referência do OpenID Connect.

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
• Referência de executores auto-hospedados