Note
No momento, não há suporte para 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 que os seus fluxos de trabalho de GitHub Actions acessem recursos no seu provedor da nuvem, sem ter que armazenar qualquer credencial como segredos de GitHub de longa duração.
Para usar o OIDC, você primeiro precisará configurar seu provedor de nuvem para confiar no OIDC de GitHub como uma identidade federada e, em seguida, atualizar seus fluxos de trabalho para efetuar a autenticação usando tokens.
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".
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 oficial do seu provedor de nuvem para trocar o token OIDC (JWT) por um token de acesso em nuvem.
Se seu provedor de nuvem ainda não oferece uma ação oficial, você pode atualizar seus fluxos de trabalho para executar essas etapas manualmente.
Note
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".
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".
Usando ações oficiais
Se seu provedor de nuvem criou uma ação oficial para usar o OIDC com GitHub Actions, isso permitirá que você troque o token OIDC por um token de acesso facilmente. Em seguida, você pode atualizar seus fluxos de trabalho para usar este token ao acessar recursos da nuvem.
Por exemplo, o Alibaba Cloud criou o aliyun/configure-aliyun-credentials-action
para se integrar ao uso do OIDC com o GitHub.
Usando ações personalizadas
Se seu provedor de nuvem não tiver uma ação oficial, ou se você preferir criar scripts personalizados, você poderá solicitar manualmente o token web do JSON (JWT) do provedor OIDC de GitHub.
Se você não estiver usando uma ação oficial, então GitHub recomenda que você use o kit de ferramentas principal das Ações. Como alternativa, você pode usar as seguintes variáveis de ambiente para recuperar o token: ACTIONS_ID_TOKEN_REQUEST_TOKEN
e ACTIONS_ID_TOKEN_REQUEST_URL
.
Para atualizar seus fluxos de trabalho usando esta abordagem, você deverá fazer três alterações no seu YAML:
- Adicionar configurações de permissões para o token.
- Adicione o código que solicita o token OIDC do provedor OIDC de GitHub.
- Adicione um código que troque o token OIDC com seu provedor de nuvem por um token de acesso.
Solicitando o JWT que usa a o kit de ferramentas principal das Ações
O exemplo a seguir demonstra como usar actions/github-script
com o kit de ferramentas core
para solicitar o JWT do provedor OIDC do GitHub. Para obter mais informações, confira "Criando uma ação de JavaScript".
jobs:
job:
environment: Production
runs-on: ubuntu-latest
steps:
- name: Install OIDC Client from Core Package
run: npm install @actions/core@1.6.0 @actions/http-client
- name: Get Id Token
uses: actions/github-script@v6
id: idtoken
with:
script: |
const coredemo = require('@actions/core')
let id_token = await coredemo.getIDToken()
coredemo.setOutput('id_token', id_token)
Solicitando o JWT que usa variáveis de ambiente
O exemplo a seguir demonstra como usar variáveis de ambiente para solicitar um Token Web JSON.
Para seu trabalho de implantação, você precisará definir as configurações de token usando actions/github-script
com o kit de ferramentas core
. Para obter mais informações, confira "Criando uma ação de JavaScript".
Por exemplo:
jobs:
job:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v6
id: script
timeout-minutes: 10
with:
debug: true
script: |
const token = process.env['ACTIONS_RUNTIME_TOKEN']
const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
core.setOutput('TOKEN', token.trim())
core.setOutput('IDTOKENURL', runtimeUrl.trim())
Em seguida, use curl
para recuperar um JWT do provedor OIDC do GitHub. Por exemplo:
- run: |
IDTOKEN=$(curl -H "Authorization: bearer ${{steps.script.outputs.TOKEN}}" ${{steps.script.outputs.IDTOKENURL}} -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" | jq -r '.value')
echo $IDTOKEN
jwtd() {
if [[ -x $(command -v jq) ]]; then
jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}"
echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')"
fi
}
jwtd $IDTOKEN
echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT
id: tokenid
Obtendo o token de acesso do provedor da nuvem
Você precisará apresentar o token web JSON do OIDC para seu provedor de nuvem a fim de obter um token de acesso.
Para cada implantação, seus fluxos de trabalho devem usar ações de login em nuvem (ou scripts personalizados) que buscam o token do OIDC e o apresentam ao seu provedor de nuvem. O provedor da nuvem valida as reivindicações no token; se for bem sucedido, ele fornece um token de acesso à nuvem que está disponível apenas para a execução do trabalho. O token de acesso fornecido pode ser usado por ações subsequentes no trabalho para conectar-se à nuvem e fazer a implantação nos seus recursos.
As etapas para trocar o token do OIDC por um token de acesso irão variar para cada provedor de nuvem.
Acessando recursos no seu provedor da nuvem
Depois de obter o token de acesso, você pode usar as ações específicas da nuvem ou scripts para efetuar a autenticação no provedor da nuvem e fazer a implantação nos seus recursos. Essas etapas podem ser diferentes para cada provedor da nuvem.
Por exemplo, o Alibaba Cloud mantém suas próprias instruções para autenticação OIDC. Para obter mais informações, consulte Visão geral do SSO baseado em OIDC na documentação do Alibaba Cloud.
Além disso, o tempo de expiração padrão desse token de acesso pode variar entre as nuvens e pode ser configurável no lado do provedor de nuvem.