Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.
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".
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:
-
Habilite o método
auth
do JWT e usewrite
para aplicar a configuração ao Cofre. Para os parâmetrosoidc_discovery_url
ebound_issuer
, usehttps://HOSTNAME/_services/token
. 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
vault auth enable jwt
Shell vault write auth/jwt/config \ bound_issuer="https://HOSTNAME/_services/token" \ oidc_discovery_url="https://HOSTNAME/_services/token"
vault write auth/jwt/config \ bound_issuer="https://HOSTNAME/_services/token" \ oidc_discovery_url="https://HOSTNAME/_services/token"
-
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
vault policy write myproject-production - <<EOF # Read-only permission on 'secret/data/production/*' path path "secret/data/production/*" { capabilities = [ "read" ] } EOF
-
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
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âmetrobound_subject
, bem como o parâmetrobound_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óriorepo-name
pertencente à contauser-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:
- Adicionar configurações de permissões para o token.
- Use a ação
hashicorp/vault-action
para trocar o token OIDC (JWT) por um token de acesso à nuvem.
Observação: quando os ambientes são usados em fluxos de trabalho ou em políticas OIDC, recomendamos adicionar regras de proteção ao ambiente para segurança adicional. Por exemplo, você pode configurar regras de implantação em um ambiente para restringir quais ramificações e tags podem ser implantadas no ambiente ou acessar segredos de ambiente. Para obter mais informações, confira "Usando ambientes para implantação".
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 deid-token
definido comowrite
. Isso permite obter o token do OIDC de cada trabalho do fluxo de trabalho.
- O fluxo de trabalho precisa de configurações
- 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.
- Você pode usar a ação
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 de trabalho ou de fluxo de trabalho exige uma configuração permissions
com id-token: write
. Você não poderá solicitar o token de ID JWT do OIDC se a configuração permissions
de id-token
for definida como read
ou none
.
A configuração id-token: write
permite 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
eACTIONS_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
Observação:
Quando a chave permissions
é usada, todas as permissões não especificadas são definidas como sem acesso, com exceção do escopo de metadados, que sempre obtém acesso de leitura. Como resultado, talvez seja necessário adicionar outras permissões, como contents: read
. Para obter mais informações, confira "Autenticação automática de token".
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@v2.4.0 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@v2.4.0
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.
Observação:
- Se o servidor do Cofre não estiver acessível na rede pública, considere usar um executor auto-hospedado com outros métodos de autenticação do Cofre disponíveis. Para obter mais informações, confira "Sobre executores auto-hospedados".
<Vault Namespace>
deve ser definido para uma implantação do Vault Enterprise (incluindo o HCP Vault). Para mais informações, confira Namespace do Cofre.
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.
- Defina a opção
exportToken
comotrue
(padrão:false
). Isso exporta o token de acesso do Cofre emitido como uma variável de ambiente:VAULT_TOKEN
. - 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@v2.4.0 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@v2.4.0
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