OpenID Connect

Visão geral do OIDC (OpenID Connect)

GitHub Actions fluxos de trabalho geralmente são elaborados para acessar um provedor de nuvem (como AWS, Azure, GCP, HashiCorp Vault e outros) para implantar software ou usar 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.

Depois de estabelecer uma conexão de confiança com um provedor de nuvem que dá suporte ao OIDC, você pode configurar seu fluxo de trabalho para solicitar um token de acesso de curta duração diretamente do provedor de nuvem.

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 precisará duplicar suas credenciais da nuvem como segredos de longa duração 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 autorização:** você tem um controle mais granular sobre como os fluxos de trabalho podem usar credenciais, usando as ferramentas de autenticação (authN) e autorização (authZ) do seu provedor de nuvem para controlar o acesso aos recursos da nuvem.

        **Credenciais rotativas:** com o OIDC, seu provedor de nuvem emite um token de acesso de curta duração, válido apenas para uma única tarefa, e que expira automaticamente em seguida.

Como o OIDC se integra às GitHub Actions

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

Diagrama de como um provedor de nuvem se integra ao GitHub Actions por meio de tokens de acesso e IDs de função de nuvem do token Web JSON.

Você estabelece uma relação de confiança do OIDC no provedor de nuvem, permitindo que fluxos de trabalho específicos do GitHub solicitem tokens de acesso à nuvem em nome de uma função de nuvem definida.
Toda vez que o seu trabalho é executado, o provedor OIDC do GitHub gera um token do 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.
Uma etapa ou ação no trabalho do fluxo de trabalho pode solicitar um token do provedor OIDC do GitHub, que pode ser apresentado ao provedor de nuvem como prova da identidade do fluxo de trabalho.
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.

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://github.com/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",
  "runner_environment": "github-hosted",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "repo_property_workspace_id": "ws-abc123",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

Autenticar ações personalizadas usando o OIDC

As ações personalizadas usam o método getIDToken() do kit de ferramentas do Ações ou de um comando curl para autenticar usando o OIDC.

Para saber mais, confira Referência do OpenID Connect.

Atualizando seus fluxos de trabalho para o OIDC

Os fluxos de trabalho do GitHub Actions podem usar tokens OIDC em vez de segredos para autenticar com provedores de nuvem. Muitos provedores de nuvem populares oferecem ações de logon oficiais que simplificam o processo de uso do OIDC em seus fluxos de trabalho. Para obter mais informações sobre como atualizar seus fluxos de trabalho com provedores de nuvem específicos, consulte Reforço de segurança em suas implementações.

Usando propriedades personalizadas do repositório como declarações OIDC

Observação

Esse recurso está atualmente em versão prévia pública e está sujeito a alterações.

Administradores corporativos e organizacionais podem incluir propriedades personalizadas do repositório como declarações em tokens OIDC. Uma vez adicionado, cada repositório na organização ou empresa que tem um valor definido para essa propriedade personalizada irá incluí-lo automaticamente em seus tokens OIDC, prefixados com repo_property_.

Isso permite criar políticas de acesso granulares que se associam diretamente aos metadados do repositório, reduzindo o descompasso de configuração e eliminando a necessidade de duplicar informações de governança em vários sistemas.

Pré-requisitos

As propriedades personalizadas já devem ser definidas no nível da organização ou da empresa.
Você deve ser um administrador da organização ou administrador corporativo.

Adicionando uma propriedade personalizada a declarações de token OIDC

Para incluir uma propriedade personalizada em tokens OIDC, use a API REST ou a interface de configurações da sua organização ou empresa.

          **Usando a interface de usuário das configurações:** Navegue até a página de configurações de ações OIDC de sua organização ou empresa para exibir e gerenciar quais propriedades personalizadas estão incluídas em tokens OIDC.

Captura de tela das configurações do OIDC para uma organização ou empresa.

        **Usando a API REST:** Envie uma `POST` solicitação para adicionar uma propriedade personalizada às declarações de token OIDC para sua organização:

Exemplo de token OIDC com uma propriedade personalizada

O exemplo a seguir mostra um token OIDC que inclui a workspace_id propriedade personalizada:

{
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "aud": "https://github.com/my-org",
  "repository": "my-org/my-repo",
  "repo_property_workspace_id": "ws-abc123"
}

Você pode usar as repo_property_* declarações nas condições de confiança do provedor de nuvem para criar políticas flexíveis de controle de acesso baseadas em atributo. Para saber mais, confira Referência do OpenID Connect.

Suporte do OIDC para Dependabot

O Dependabot pode usar OIDC para autenticar com registros privados, eliminando a necessidade de armazenar credenciais de longa duração como segredos de repositório. Com a autenticação baseada em OIDC, os trabalhos de atualização do Dependabot podem obter dinamicamente credenciais de curta duração do seu provedor de identidade na nuvem.

Dependabot dá suporte à autenticação OIDC para qualquer tipo de registro que use username e password autenticação, quando o registro é hospedado no AWS CodeArtifact, Azure DevOps Artifacts ou JFrog Artifactory.

Os benefícios da autenticação OIDC para Dependabot são:

        **Segurança aprimorada:** Elimina credenciais estáticas e de longa duração de seus repositórios.

        **Gerenciamento mais simples:** Habilita o acesso seguro e compatível com a política a registros privados.

        **Evite limitar a taxa:** As credenciais dinâmicas ajudam você a evitar atingir os limites de taxa associados a tokens estáticos.

Para saber mais, confira Configurando o acesso a registros privados para Dependabot.

Próximas etapas

Para saber mais sobre como configurar OIDC, confira Reforço de segurança em suas implementações.

Para obter informações de referência sobre o OIDC, consulte Referência do OpenID Connect.

Neste artigo