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:
- 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.
- 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.
- 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.
- 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://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",
"enterprise": "avocado-corp",
"enterprise_id": "2",
"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
}
Para ver todas as declarações compatíveis com o provedor OIDC do GitHub, revise as entradas claims_supported
em https://token.actions.githubusercontent.com/.well-known/openid-configuration.
O token inclui as declarações padrão do público-alvo, do emissor e da entidade.
Declaração | Tipo de declaração | Descrição |
---|---|---|
aud | Público | Por padrão, esta é a URL do proprietário do repositório, como a organização proprietária do repositório. Defina um público-alvo personalizado com um comando de kit de ferramentas: core.getIDToken(audience) |
iss | Emissor | O emissor do token OIDC: https://token.actions.githubusercontent.com |
sub | Assunto | Define a declaração de entidade que deve ser validada pelo provedor de nuvem. Esta configuração é essencial para garantir que os tokens de acesso sejam apenas alocados de forma previsível. |
O token do OIDC também inclui parâmetros e declarações de cabeçalho JOSE padrão adicionais.
Parâmetro de cabeçalho | Tipo de parâmetro | Descrição |
---|---|---|
alg | Algoritmo | O algoritmo usado pelo provedor OIDC. |
kid | Identificador da chave | Chave exclusiva do token OIDC. |
typ | Tipo | Descreve o tipo de token. Este é um token web do JSON (JWT). |
Declaração | Tipo de declaração | Descrição |
---|---|---|
exp | Expira em | Identifica o tempo de validade do JWT. |
iat | Emitido em | A hora em que o JWT foi emitido. |
jti | Identificador do token JWT | Identificador exclusivo do token OIDC. |
nbf | Não antes de | O JWT não é válido para uso antes deste horário. |
O token também inclui declarações personalizadas fornecidas pelo GitHub.
Declaração | Descrição |
---|---|
actor | A conta pessoal que iniciou a execução do fluxo de trabalho. |
actor_id | A ID da conta pessoal que iniciou a execução do fluxo de trabalho. |
base_ref | O branch de destino do pull request na execução de um fluxo de trabalho. |
enterprise | O nome da empresa que contém o repositório de onde o fluxo de trabalho está sendo executado. |
enterprise_id | A ID da empresa que contém o repositório do qual o fluxo de trabalho está sendo executado. |
environment | O nome do ambiente usado pelo trabalho. Se a declaração environment for incluída (também via include_claim_keys ), um ambiente será necessário e deverá ser fornecido. |
event_name | Nome do evento que acionou a execução do fluxo de trabalho. |
head_ref | O branch de origem do pull request na execução de um fluxo de trabalho. |
job_workflow_ref | Para trabalhos que usam um fluxo de trabalho reutilizável, o caminho de ref para o fluxo de trabalho reutilizável. Para obter mais informações, confira "Usando o OpenID Connect com fluxos de trabalho reutilizáveis". |
job_workflow_sha | Para trabalhos que usam um fluxo de trabalho reutilizável, o SHA de commit do arquivo de fluxo de trabalho reutilizável. |
ref | (Referência) A referência do Git que disparou a execução de fluxo de trabalho. |
ref_type | O tipo de ref , por exemplo: "branch". |
repository_visibility | A visibilidade do repositório em que o fluxo de trabalho está sendo executado. Aceita os seguintes valores: internal , private , ou public . |
repository | O repositório de onde o fluxo de trabalho está sendo executado. |
repository_id | A ID do repositório do qual o fluxo de trabalho está sendo executado. |
repository_owner | O nome da organização na qual o repository é armazenado. |
repository_owner_id | A ID da organização na qual o repository é armazenado. |
run_id | O ID da execução do fluxo de trabalho que acionou o fluxo de trabalho. |
run_number | O número de vezes que este fluxo de trabalho foi executado. |
run_attempt | O número de vezes que este fluxo de trabalho foi executado. |
runner_environment | O tipo de executor usado pelo trabalho. Aceita os seguintes valores: github-hosted ou self-hosted . |
workflow | Nome do fluxo de trabalho. |
workflow_ref | O caminho de referência para o fluxo de trabalho. Por exemplo, octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch . |
workflow_sha | O SHA de commit para o arquivo de fluxo de trabalho. |
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 somente a solicitações originadas de um repositório de uma organização específica. É possível também especificar condições adicionais, que estão 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.
Caso necessite de condições de confiança mais granulares, poderá personalizar as declarações issuer (iss
) e subject (sub
) que são 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.
Note
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.
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:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
- 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:ORG-NAME/REPO-NAME: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:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME
- 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:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
- 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:
Provedor de nuvem | Exemplo |
---|---|
Amazon Web Services | "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch" |
Azure | repo:octo-org/octo-repo:ref:refs/heads/demo-branch |
Google Cloud Platform | (assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch') |
Cofre HashiCorp | bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch" |
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.
Variável | Descrição |
---|---|
ACTIONS_ID_TOKEN_REQUEST_URL | A URL para o provedor do OIDC de GitHub. |
ACTIONS_ID_TOKEN_REQUEST_TOKEN | Token portador para a solicitação para o provedor do OIDC. |
Por exemplo:
curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"
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 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".
Personalizando as declarações de token
Você pode proteger a segurança da configuração do OIDC personalizando as declarações incluídas no JWT. Essas personalizações permitem definir condições de confiança mais granulares em suas funções de nuvem ao permitir que seus fluxos de trabalho acessem recursos hospedados na nuvem:
- Você pode personalizar valores de declarações de
issuer
ouaudience
. Confira "Como personalizar o valor deissuer
para uma empresa" e "Como personalizar o valor deaudience
". - Você pode personalizar o formato de sua configuração OIDC definindo condições na declaração de assunto (
sub
) que exigem que os tokens JWT sejam originados de um repositório específico, fluxo de trabalho reutilizável ou outra fonte. - Você pode definir políticas OIDC granulares usando declarações de token OIDC adicionais, como
repository_id
erepository_visibility
. Confira “Entendendo o token do OIDC”.
Como personalizar o valor de audience
Quando você usa ações personalizadas em seus fluxos de trabalho, essas ações podem usar o kit de ferramentas GitHub Actions para permitir que você forneça um valor personalizado para a declaração audience
. Alguns provedores de nuvem também usam isso em suas ações oficiais de logon a fim de impor um valor padrão para a declaração audience
. Por exemplo, a ação do GitHub para login do Azure fornece um valor padrão aud
de api://AzureADTokenExchange
, ou permite que você defina um valor personalizado de aud
em seus fluxos de trabalho. Para obter mais informações sobre o kit de ferramentas do GitHub Actions, confira a seção do Token OIDC na documentação.
Para usar outro valor e não o padrão aud
oferecido por uma ação, defina um valor personalizado para a declaração audience
. Isso permite que você defina uma condição de que apenas fluxos de trabalho em um repositório ou organização específica possam acessar a função de nuvem. Se a ação que você está usando oferecer suporte, você pode usar a palavra-chave with
em seu fluxo de trabalho para passar um valor personalizado aud
para a ação. Para obter mais informações, confira "Sintaxe de metadados para o GitHub Actions".
Como personalizar o valor de issuer
de uma empresa
Por padrão, o JWT é emitido pelo provedor OIDC do GitHub em https://token.actions.githubusercontent.com
. Esse caminho é apresentado ao provedor de nuvem usando o valor iss
no JWT.
Para aumentar a segurança de sua configuração do OIDC, os administradores corporativos podem configurar sua empresa para receber tokens de uma URL exclusiva em https://token.actions.githubusercontent.com/<enterpriseSlug>
, substituindo <enterpriseSlug>
pelo valor do campo de dados dinâmico da empresa.
Essa configuração significa que sua empresa receberá o token OIDC de uma URL exclusiva e você poderá configurar seu provedor de nuvem para aceitar apenas tokens dessa URL. Isso ajuda a garantir que apenas os repositórios da empresa possam acessar seus recursos de nuvem usando o OIDC.
Para ativar essa configuração para sua empresa, um administrador corporativo deve usar o ponto de extremidade /enterprises/{enterprise}/actions/oidc/customization/issuer
e especificar "include_enterprise_slug": true
no corpo da solicitação. Para obter mais informações, confira "Pontos de extremidade da API REST para OIDC do GitHub Actions".
Depois que essa configuração for aplicada, o JWT conterá o valor iss
atualizado. No seguinte exemplo, a chave iss
usa octocat-inc
como o valor enterpriseSlug
:
{
"jti": "6f4762ed-0758-4ccb-808d-ee3af5d723a8",
"sub": "repo:octocat-inc/private-server:ref:refs/heads/main",
"aud": "http://octocat-inc.example/octocat-inc",
"enterprise": "octocat-inc",
"enterprise_id": "123",
"iss": "https://token.actions.githubusercontent.com/octocat-inc",
"bf": 1755350653,
"exp": 1755351553,
"iat": 1755351253
}
Personalizando as declarações de assunto para uma organização ou repositório
Para ajudar a melhorar a segurança, a conformidade e a padronização, você pode personalizar as declarações padrão para atender às condições de acesso necessárias. Se o provedor de nuvem der suporte a condições em declarações de assunto, você poderá criar uma condição que verifique se o valor sub
corresponde ao caminho do fluxo de trabalho reutilizável, como "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"
. O formato exato variará dependendo da configuração do OIDC do provedor de nuvem. Para configurar a condição correspondente no GitHub, você pode usar a API REST para exigir que a declaração sub
sempre inclua uma declaração personalizada específica, como job_workflow_ref
. Você pode usar a API REST para aplicar um modelo de personalização à declaração de entidade do OIDC; por exemplo, você pode exigir que a declaração sub
dentro do token do OIDC sempre inclua uma declaração personalizada específica, como job_workflow_ref
. Para obter mais informações, confira "Pontos de extremidade da API REST para OIDC do GitHub Actions".
Note
Quando o modelo da organização é aplicado, ele não afeta nenhum fluxo de trabalho que já esteja usando o OIDC, a menos que o repositório tenha aceito os modelos personalizados da organização. Para todos os repositórios, existentes e novos, o proprietário do repositório precisará usar a API REST no nível do repositório para aceitar o recebimento dessa configuração, definindo use_default
como false
. Como alternativa, o proprietário do repositório pode usar a API REST para aplicar uma configuração diferente específica ao repositório. Para obter mais informações, confira "Pontos de extremidade da API REST para OIDC do GitHub Actions".
Personalizar as declarações resulta em um novo formato para toda a declaração sub
, que substitui o formato predefinido padrão sub
no token descrito em "Sobre o enrijecimento de segurança com o OpenID Connect".
Note
A declaração sub
usa a forma abreviada repo
(por exemplo, repo:ORG-NAME/REPO-NAME
) em vez de repository
para referenciar o repositório. Qualquer :
dentro do valor de contexto será substituída por %3A
.
Os modelos de exemplo a seguir demonstram várias maneiras de personalizar a declaração de assunto. Para definir essas configurações no GitHub, os administradores usam a API REST para especificar uma lista de declarações que devem ser incluídas na declaração de assunto (sub
).
Para aplicar essa configuração, envie uma solicitação ao ponto de extremidade da API e inclua a configuração necessária no corpo da solicitação. Para organizações, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions. Para repositórios, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions".
Para personalizar suas declarações de assunto, primeiro você deve criar uma condição correspondente na configuração OIDC do provedor de nuvem, antes de personalizar a configuração usando a API REST. Depois que a configuração for concluída, cada vez que um novo trabalho for executado, o token OIDC gerado durante esse trabalho seguirá o novo modelo de personalização. Se a condição correspondente não existir na configuração OIDC do provedor de nuvem antes da execução do trabalho, o token gerado poderá não ser aceito pelo provedor de nuvem, pois as condições de nuvem podem não ser sincronizadas.
Exemplo: permitir repositório com base na visibilidade e no proprietário
Este modelo de exemplo permite que a declaração sub
tenha um novo formato, usando repository_owner
e repository_visibility
:
{
"include_claim_keys": [
"repository_owner",
"repository_visibility"
]
}
Na configuração do OIDC do provedor de nuvem, configure a sub
condição para exigir que as declarações incluam valores específicos para repository_owner
e repository_visibility
. Por exemplo: "sub": "repository_owner:monalisa:repository_visibility:private"
. A abordagem permite restringir o acesso de função de nuvem a apenas repositórios privados em uma organização ou empresa.
Exemplo: permitindo acesso a todos os repositórios com um proprietário específico
Este modelo de exemplo permite que a declaração sub
tenha um novo formato apenas com o valor de repository_owner
.
Para aplicar essa configuração, envie uma solicitação ao ponto de extremidade da API e inclua a configuração necessária no corpo da solicitação. Para organizações, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions. Para repositórios, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions".
{
"include_claim_keys": [
"repository_owner"
]
}
Na configuração do OIDC do provedor de nuvem, configure a condição sub
para exigir que as declarações incluam um valor específico para repository_owner
. Por exemplo: "sub": "repository_owner:monalisa"
Exemplo: exigir um fluxo de trabalho reutilizável
Este modelo de exemplo permite que a declaração sub
tenha um novo formato que contenha o valor da job_workflow_ref
declaração. Isso permite que uma empresa use fluxos de trabalho reutilizáveis para impor implantações consistentes em nas organizações e nos repositórios dela.
Para aplicar essa configuração, envie uma solicitação ao ponto de extremidade da API e inclua a configuração necessária no corpo da solicitação. Para organizações, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions. Para repositórios, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions".
{
"include_claim_keys": [
"job_workflow_ref"
]
}
Na configuração do OIDC do provedor de nuvem, configure a condição sub
para exigir que as declarações incluam um valor específico para job_workflow_ref
. Por exemplo: "sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"
.
Exemplo: exigir um fluxo de trabalho reutilizável e outras declarações
O modelo de exemplo a seguir combina o requisito de um fluxo de trabalho reutilizável específico com declarações adicionais.
Para aplicar essa configuração, envie uma solicitação ao ponto de extremidade da API e inclua a configuração necessária no corpo da solicitação. Para organizações, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions. Para repositórios, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions".
Este exemplo também demonstra como usar "context"
para definir suas condições. Essa é a parte que segue o repositório no formato sub
padrão. Por exemplo, quando o trabalho faz referência a um ambiente, o contexto traz: environment:ENVIRONMENT-NAME
.
{
"include_claim_keys": [
"repo",
"context",
"job_workflow_ref"
]
}
Na configuração do OIDC do provedor de nuvem, configure a condição sub
para exigir que as declarações incluam valores específicos para repo
, context
e job_workflow_ref
.
Este modelo de personalização exige que sub
adote o seguinte formato: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH
.
Por exemplo: "sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"
Exemplo: conceder acesso a um repositório específico
Este modelo de exemplo permite conceder acesso à nuvem a todos os fluxos de trabalho em um repositório específico, em todos os branches/marcas e ambientes. Para melhorar ainda mais a segurança, você pode combinar esse modelo com uma URL de emissor exclusiva para sua empresa, conforme descrito em "Personalizar o valor de issuer
para uma empresa".
Para aplicar essa configuração, envie uma solicitação ao ponto de extremidade da API e inclua a configuração necessária no corpo da solicitação. Para organizações, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions. Para repositórios, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions".
{
"include_claim_keys": [
"repo"
]
}
Na configuração do OIDC do provedor de nuvem, configure a sub
condição para exigir uma repo
declaração que corresponda ao valor necessário.
Exemplo: usando GUIDs gerados pelo sistema
Este modelo de exemplo permite declarações OIDC previsíveis com GUIDs gerados pelo sistema que não mudam entre renomeações de entidades (como renomear um repositório).
Para aplicar essa configuração, envie uma solicitação ao ponto de extremidade da API e inclua a configuração necessária no corpo da solicitação. Para organizações, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions. Para repositórios, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions".
{
"include_claim_keys": [
"repository_id"
]
}
Na configuração do OIDC do provedor de nuvem, configure a sub
condição para exigir uma declaração repository_id
que corresponda ao valor necessário.
ou:
{
"include_claim_keys": [
"repository_owner_id"
]
}
Na configuração do OIDC do provedor de nuvem, configure a sub
condição para exigir uma declaração repository_owner_id
que corresponda ao valor necessário.
Exemplo: valor de contexto com :
Este exemplo demonstra como lidar com o valor de contexto com :
. Por exemplo, quando o trabalho faz referência a um ambiente chamado production:eastus
.
Para aplicar essa configuração, envie uma solicitação ao ponto de extremidade da API e inclua a configuração necessária no corpo da solicitação. Para organizações, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions. Para repositórios, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions".
{
"include_claim_keys": [
"environment",
"repository_owner"
]
}
Na configuração do OIDC do provedor de nuvem, configure a condição sub
para exigir que as declarações incluam um valor específico para environment
e repository_owner
. Por exemplo: "sub": "environment:production%3Aeastus:repository_owner:octo-org"
.
Redefinir as personalizações do modelo da organização
Este modelo de exemplo redefine as declarações de assunto para o formato padrão. Esse modelo aceita efetivamente qualquer política de personalização no nível da organização.
Para aplicar essa configuração, envie uma solicitação ao ponto de extremidade da API e inclua a configuração necessária no corpo da solicitação. Para organizações, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions. Para repositórios, consulte "Pontos de extremidade da API REST para OIDC do GitHub Actions".
{
"include_claim_keys": [
"repo",
"context"
]
}
Na configuração do OIDC do provedor de nuvem, configure a condição sub
para exigir que as declarações incluam valores específicos para repo
e context
.
Redefinir as personalizações do modelo do repositório
Todos os repositórios de uma organização têm a capacidade de aceitar ou recusar os modelos personalizados de declaração sub
(no nível da organização e do repositório).
Para recusar um repositório e redefinir para o formato de declaração sub
padrão, um administrador de repositório deve usar o ponto de extremidade de API REST em "AUTOTITLE".
Para configurar repositórios para que usem o formato de declaração padrão sub
, use o ponto de extremidade PUT /repos/{owner}/{repo}/actions/oidc/customization/sub
da API REST com o seguinte corpo da solicitação:
{
"use_default": true
}
Exemplo: configurar um repositório para usar um modelo de organização
Depois que uma organização criou um modelo de declaração sub
personalizado, a API REST pode ser usada para aplicar o modelo programaticamente aos repositórios dentro da organização. Um administrador pode configurar seu repositório para usar o modelo criado pelo administrador de sua organização.
Para configurar o repositório de modo que ele use o modelo da organização, um administrador de repositório deve usar o ponto de extremidade PUT /repos/{owner}/{repo}/actions/oidc/customization/sub
da API REST com o seguinte corpo da solicitação: Para obter mais informações, confira "Pontos de extremidade da API REST para OIDC do GitHub Actions".
{
"use_default": false
}
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".
Habilitando o OpenID Connect para publicação de pacotes Python
Você pode usar um fluxo de trabalho do GitHub Actions em um repositório como um editor confiável para um projeto PyPI. O uso de um fluxo de trabalho como um editor confiável permite que os tokens de acesso OIDC sejam trocados por tokens temporários de API do PyPI. Para obter mais informações, consulte "Configurando o OpenID Connect no PyPI" e "Publicando no PyPI com um editor confiável" na documentação do PyPI.
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:
Como seguir estes guias no GHE.com
Se você fizer parte de uma empresa que usa o GitHub Enterprise Cloud com residência de dados e estiver configurando o OIDC no GHE.com, precisará substituir alguns valores nos artigos com links.
- A declaração esperada do provedor precisa substituir
githubusercontent.com
porSUBDOMAIN.ghe.com
, em que SUBDOMAIN é o subdomínio da sua empresa no GHE.com. - Para qualquer URL que inclua uma rota com o nome ou o campo de dados dinâmico da sua empresa, substitua o subdomínio da empresa no GHE.com.
Por exemplo, se o subdomínio for octocorp
, as seguintes substituições se aplicarão:
- A URL usada para ver todas as declarações com suporte no provedor OIDC do GitHub será
https://token.actions.octocorp.ghe.com/.well-known/openid-configuration
. - O valor de
iss
no token OIDC seráhttps://token.actions.octocorp.ghe.com
. - A empresa pode receber tokens no
https://token.actions.octocorp.ghe.com/octocorp
e o ponto de extremidade de API REST para personalizar o valorissuer
será/enterprises/octocorp/actions/oidc/customization/issuer
.
Depurar as declarações do OIDC
Você pode usar a ação github/actions-oidc-debugger
para visualizar as declarações que serão enviadas, antes de integrar com um provedor de nuvem. Essa ação solicita um JWT e imprime as declarações incluídas no JWT que foram recebidas do GitHub Actions.