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 "Gerenciar 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 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: 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
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".
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@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.
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@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