Sobre o enrijecimento de segurança com o OpenID Connect

Visão geral do OpenID Connect

Os fluxos de trabalho de GitHub Actions são geralmente projetados para acessar um provedor de nuvem (como AWS, Azure, GCP, ou HashiCorp Vault) para implantar o software ou usar os serviços da nuvem. Antes que o fluxo de trabalho possa acessar esses recursos, ele fornecerá credenciais para o provedor da nuvem, como uma senha ou token. Estas credenciais geralmente são armazenadas como um segredo em GitHub, e o fluxo de trabalho apresenta esse segredo para o provedor da nuvem toda vez que é executado.

No entanto, usar segredos codificados exige que você crie credenciais no provedor de nuvem e, em seguida, duplique-as em GitHub como segredo.

Com o OpenID Connect (OIDC), você pode adotar uma abordagem diferente configurando seu fluxo de trabalho para solicitar um token de acesso de curta duração diretamente do provedor da nuvem. Seu provedor de nuvem também precisa ser compatível com OIDC na sua extremidade, e você deve configurar um relacionamento de confiança que controla quais fluxos de trabalho podem solicitar os tokens de acesso. Os provedores que atualmente são compatíveis com o OIDC incluem o Amazon Web Services, Azure, Google Cloud Platform e HashiCorp Vault, entre outros.

Benefícios de usar o OIDC

Ao atualizar seus fluxos de trabalho para usar tokens do OIDC, você pode adotar as seguintes práticas recomendadas de segurança:

• Sem segredos na nuvem: você não vai precisar duplicar suas credenciais da nuvem como segredos de longa duração do GitHub. Em vez disso, você pode configurar a confiança do OIDC no seu provedor de nuvem, e, em seguida, atualizar seus fluxos de trabalho para solicitar um token de acesso curto do provedor de nuvem por meio do OIDC.
• Gerenciamento de autenticação e de autorização: você tem um mais controle granular sobre como os fluxos de trabalho podem usar as credenciais usando a autenticação do seu provedor de nuvem (authN) e as ferramentas de autorização (authZ) para controlar o acesso aos recursos na nuvem.
• Rotação de credenciais: com o OIDC, seu provedor de nuvem emite um token de acesso de curta duração que só é válido para uma execução de trabalho individual e, posteriormente, vence de modo automático.

Introdução ao OIDC

O diagrama a seguir fornece uma visão geral de como o provedor OIDC de GitHub integra-se aos seus fluxos de trabalho e provedor de nuvem:

1. No seu provedor de nuvem, crie uma confiança do OIDC entre a sua função na nuvem e o(s) seu(s) fluxo(s) de trabalho GitHub que precisam acessar a nuvem.
2. Toda vez que o seu trabalho é executado, o provedor OIDC de GitHub gera um token de OIDC automaticamente. Esse token contém várias reivindicações para estabelecer uma identidade de segurança reforçada e verificável sobre o fluxo de trabalho específico que está tentando autenticar.
3. Você pode incluir um passo ou ação no seu trabalho para solicitar este token do provedor do OIDC de GitHub, e apresentá-lo ao provedor da nuvem.
4. Uma vez que o provedor de nuvem valida as reivindicações apresentadas no token, ele irá fornecer, posteriormente, um token de acesso à nuvem de curta duração que está disponível apenas para a duração do trabalho.

Configurando a confiança do OIDC com a nuvem

Ao configurar sua nuvem para confiar no provedor OIDC do GitHub, você precisa adicionar condições para filtrar as solicitações de entrada, de modo que os repositórios ou os fluxos de trabalho não confiáveis não possam solicitar tokens de acesso para seus recursos na nuvem:

• Antes de conceder um token de acesso, o provedor de nuvem verifica se as declarações de subject e outras usadas para definir as condições nas respectivas configurações da relação de confiança correspondem àquelas do JWT (Token Web JSON) da solicitação. Como resultado, você precisa ter cautela para definir corretamente a entidade e outras condições no provedor de nuvem.
• As etapas de configuração da relação de confiança do OIDC e a sintaxe para definir as condições para as funções de nuvem (usando a Entidade e outras declarações) poderão variar dependendo do provedor de nuvem que estiver sendo usado. Para ver alguns exemplos, confira "Exemplos de declarações de entidade".

Entendendo o token do OIDC

Cada trabalho solicita um token do OIDC de GitHub, que responde com um token web do JSON gerado automaticamente (JWT) que é único para cada trabalho de fluxo de trabalho em que é gerado. Quando o trabalho é executado, o token de OIDC é apresentado ao provedor de nuvem. Para validar o token, o provedor de nuvem verifica se o assunto do token do OIDC e outras reivindicações correspondem às condições que foram pré-configuradas na definição de confiança do OIDC da função da nuvem.

O exemplo de token OIDC a seguir usa uma entidade (sub) que referencia um ambiente de trabalho chamado prod no repositório octo-org/octo-repo.

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://HOSTNAME/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://HOSTNAME/_services/token",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

Para ver todas as declarações compatíveis com o provedor OIDC do GitHub, revise as entradas claims_supported em https://HOSTNAME/_services/token/.well-known/openid-configuration.

O token inclui as declarações padrão do público-alvo, do emissor e da entidade.

O token do OIDC também inclui declarações padrão adicionais.

O token também inclui declarações personalizadas fornecidas pelo GitHub.

Definir condições de confiança em funções de nuvem usando as reivindicações do OIDC

Com o OIDC, um fluxo de trabalho de GitHub Actions exige que um token acesse os recursos do provedor da nuvem. O fluxo de trabalho solicita um token de acesso do seu provedor de nuvem, que verifica os detalhes apresentados pelo JWT. Se a configuração de confiança no JWT tiver correspondência, o seu provedor de nuvem responderá emitindo um token temporário para o fluxo de trabalho, que poderá ser usado para acessar os recursos do seu provedor de nuvem. Você pode configurar seu provedor de nuvem para responder apenas a solicitações originárias de um repositório de uma organização específica. Você também pode especificar condições adicionais, descritas abaixo.

As reivindicações de Audiência e Assunto são normalmente usadas em combinação, ao definir as condições da função/recursos em nuvem para definir o escopo do seu acesso aos fluxos de trabalho do GitHub.

• Público-alvo: por padrão, esse valor usa a URL do proprietário da organização ou do repositório. Isto pode ser usado para definir uma condição para que apenas os fluxos de trabalho na organização específica possam acessar a função da nuvem.
• Entidade: por padrão, tem um formato predefinido e é uma concatenação de alguns dos principais metadados sobre o fluxo de trabalho, como a organização do GitHub, o repositório, o branch ou o ambiente job associado. Confira "Exemplos de declarações de entidade" para ver como a declaração de entidade é montada com base em metadados concatenados.

Se você precisar de condições de confiança mais granulares, poderá personalizar as declarações do emissor (iss) e do assunto (sub) incluídas no JWT. Para obter mais informações, confira "Personalizando as declarações de token".

Há também muitas reivindicações adicionais compatíveis com o token do OIDC que podem ser usadas para definir essas condições. Além disso, seu provedor de nuvem poderia permitir que você atribuísse uma função aos tokens de acesso, permitindo que você especifique ainda mais permissões granulares.

Exemplo de reivindicações de assunto

Os exemplos a seguir demonstram como usar "Assunto" como condição e explicam como o "Assunto" é montado a partir de metadados concatenados. A entidade usa as informações do contexto job e instrui o provedor de nuvem sobre o fato de as solicitações de token de acesso só poderem ser concedidas para solicitações de fluxos de trabalho em execução em branches e ambientes específicos. As seguintes secções descrevem alguns assuntos comuns que você pode usar.

Filtragem para um ambiente específico

A reivindicação de assunto inclui o nome do ambiente quando o trabalho fizer referência a um ambiente.

Você pode configurar uma entidade que filtra um nome de ambiente específico. Neste exemplo, a execução de fluxo de trabalho precisa ter se originado de um trabalho que tenha um ambiente chamado Production, em um repositório chamado octo-repo que pertence à organização octo-org:

• Sintaxe: repo:<orgName/repoName>:environment:<environmentName>
• Exemplo:repo:octo-org/octo-repo:environment:Production

Filtragem de eventos pull_request

A declaração de entidade inclui a cadeia de caracteres pull_request quando o fluxo de trabalho é disparado por um evento de solicitação de pull, mas apenas se o trabalho não referencia um ambiente.

Você pode configurar uma entidade que filtra o evento pull_request. Neste exemplo, a execução de fluxo de trabalho precisa ter sido disparada por um evento pull_request em um repositório chamado octo-repo que pertence à organização octo-org:

• Sintaxe: repo:<orgName/repoName>:pull_request
• Exemplo: repo:octo-org/octo-repo:pull_request

Filtrando um branch específico

A reivindicação de assunto inclui o nome do branch do fluxo de trabalho, mas somente se o trabalho não fizer referência a um ambiente e se o fluxo de trabalho não for acionado por um evento de pull request.

Você pode configurar um assunto que filtra para um nome de branch específico. Neste exemplo, a execução de fluxo de trabalho precisa ter se originado de um branch chamado demo-branch, em um repositório chamado octo-repo que pertence à organização octo-org:

• Sintaxe: repo:<orgName/repoName>:ref:refs/heads/branchName
• Exemplo: repo:octo-org/octo-repo:ref:refs/heads/demo-branch`

Filtrando uma tag específica

A reivindicação de assunto inclui o nome da tag do fluxo de trabalho, mas somente se o trabalho não fizer referência a um ambiente e se o fluxo de trabalho não for acionado por um evento de pull request.

Você pode criar um assunto que filtra uma tag específica. Neste exemplo, a execução de fluxo de trabalho precisa ter se originado com uma marca chamada demo-tag, em um repositório chamado octo-repo que pertence à organização octo-org:

• Sintaxe: repo:<orgName/repoName>:ref:refs/tags/<tagName>
• Exemplo: repo:octo-org/octo-repo:ref:refs/tags/demo-tag

Configurando o assunto no seu provedor de nuvem

Para configurar o assunto no relacionamento de confiança do seu provedor de nuvem, você deve adicionar a string de assunto à sua configuração de confiança. Os seguintes exemplos demonstram como vários provedores de nuvem podem aceitar a mesma entidade repo:octo-org/octo-repo:ref:refs/heads/demo-branch de diferentes maneiras:

Para obter mais informações, confira os guias listados em "Como habilitar o OpenID Connect para seu provedor de nuvem".

Atualizando suas ações para o OIDC

Para atualizar as ações personalizadas e se autenticar usando o OIDC, use getIDToken() no kit de ferramentas do Actions para solicitar um JWT do provedor OIDC do GitHub. Para obter mais informações, confira "Token OIDC" na documentação do pacote npm.

Use também um comando curl para solicitar o JWT com as seguintes variáveis de ambiente.

Por exemplo:

curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"

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

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

Você pode precisar especificar permissões adicionais aqui, dependendo das necessidades do seu fluxo de trabalho.

Para fluxos de trabalho reutilizáveis, a configuração permissions para id-token deve ser 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. Para obter mais informações, confira "Reutilizar fluxos de trabalho".

Atualizando seus fluxos de trabalho para o OIDC

Agora você pode atualizar seus fluxos de trabalho do YAML para usar tokens de acesso do OIDC em vez de segredos. Os provedores de nuvem populares publicaram suas ações de login oficiais que facilitam o seu início de sessão com o OIDC. Para obter mais informações sobre como atualizar seus fluxos de trabalho, confira os guias específicos de nuvem listados abaixo em "Como habilitar o OpenID Connect para seu provedor de nuvem".

Habilitnado o OpenID Connect para o seu provedor de nuvem

Para habilitar e configurar o OIDC para seu provedor de nuvem específico, veja os seguintes guias:

• "Configurando o OpenID Connect no Amazon Web Services"
• "Configurando o OpenID Connect no Azure"
• "Configurando OpenID Connect na Google Cloud Platform"
• "Configurando o OpenID Connect no HashiCorp Vault"

Para habilitar e configurar o OIDC para outro provedor de nuvem, consulte o guia a seguir:

• "Configurando OpenID Connect em provedores da nuvem"