Referência do OpenID Connect

Declarações de token OIDC

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

O token OIDC inclui as declarações a seguir.

Declarações de audiência, emissor e entidade padrão

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.

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.

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.
environment	O nome do ambiente usado pelo trabalho. Se a declaraçãoenvironment for incluída (também viainclude_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 saber mais, confiraUsando 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 deref, 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, oupublic.
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 orepository é armazenado.
repository_owner_id	A ID da organização na qual orepository é 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 ouself-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.

Declarações OIDC usadas para definir condições de confiança em funções de nuvem

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 ambientejob associado. ConfiraExemplos 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 subject (sub) que é incluídas no JWT. Para obter mais informações, confiraPersonalizando 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. Aentidade usa as informações docontextojob 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 deambiente específico. Neste exemplo, a execução de fluxo de trabalho precisa ter se originado de um trabalho que tenha um ambiente chamadoProduction, em um repositório chamadoocto-repo que pertence à organizaçãoocto-org:

• Sintaxe:repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
• Exemplo:repo:octo-org/octo-repo:environment:Production

Filtragem de eventospull_request

A declaração de entidade inclui a cadeia de caracterespull_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 eventopull_request. Neste exemplo, a execução de fluxo de trabalho precisa ter sido disparada por um eventopull_request em um repositório chamadoocto-repo que pertence à organizaçãoocto-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 chamadodemo-branch, em um repositório chamadoocto-repo que pertence à organizaçãoocto-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 chamadademo-tag, em um repositório chamadoocto-repo que pertence à organizaçãoocto-org:

• Sintaxe:repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
• Exemplo:repo:octo-org/octo-repo:ref:refs/tags/demo-tag

Filtragem de metadados que contêm:

Qualquer: presente nos valores de metadados será substituído por%3A na declaração de assunto.

Você pode configurar um tópico que inclui metadados contendo dois-pontos. Neste exemplo, a execução de fluxo de trabalho precisa ter se originado de um trabalho que tenha um ambiente chamadoProduction:V1, em um repositório chamadoocto-repo que pertence à organizaçãoocto-org:

• Sintaxe:repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
• Exemplo:repo:octo-org/octo-repo:environment:Production%3AV1

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 entidaderepo: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 sobre como configurar provedores de nuvem específicos, confira os guias listados emSegurança que enrijece as suas implentações.

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 audience. Confira 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, comorepository_id erepository_visibility. ConfiraOpenID Connect.

Como personalizar o valor deaudience

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çãoaudience. 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çãoaudience. Por exemplo, aação do GitHub para login do Azure fornece um valor padrãoaud deapi://AzureADTokenExchange, ou permite que você defina um valor personalizado deaud em seus fluxos de trabalho. Para obter mais informações sobre o kit de ferramentas do GitHub Actions, confira a seção doToken OIDC na documentação.

Para usar outro valor e não o padrãoaud oferecido por uma ação, defina um valor personalizado para a declaraçãoaudience. 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-chavewith em seu fluxo de trabalho para passar um valor personalizadoaud para a ação. Para saber mais, confiraReferência de sintaxe de metadados.

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 valorsub 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çãosub sempre inclua uma declaração personalizada específica, comojob_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çãosub dentro do token do OIDC sempre inclua uma declaração personalizada específica, comojob_workflow_ref. Para saber mais, confiraPontos de extremidade da API REST para OIDC do GitHub Actions.

Personalizar as declarações resulta em um novo formato para toda a declaraçãosub, que substitui o formato predefinido padrãosub no token descrito em "Declarações de entidade de exemplo".

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, confira Pontos de extremidade da API REST para OIDC do GitHub Actions e para repositórios, confira 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çãosub tenha um novo formato, usandorepository_owner erepository_visibility:

{
   "include_claim_keys": [
       "repository_owner",
       "repository_visibility"
   ]
}

Na configuração do OIDC do provedor de nuvem, configure asub condição para exigir que as declarações incluam valores específicos pararepository_owner erepository_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çãosub tenha um novo formato apenas com o valor derepository_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, confira Pontos de extremidade da API REST para OIDC do GitHub Actions e para repositórios, confira 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çãosub para exigir que as declarações incluam um valor específico pararepository_owner. Por exemplo:"sub": "repository_owner:monalisa"

Exemplo: exigir um fluxo de trabalho reutilizável

Este modelo de exemplo permite que a declaraçãosub tenha um novo formato que contenha o valor dajob_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, confira Pontos de extremidade da API REST para OIDC do GitHub Actions e para repositórios, confira 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çãosub para exigir que as declarações incluam um valor específico parajob_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, confira Pontos de extremidade da API REST para OIDC do GitHub Actions e para repositórios, confira 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 formatosub 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çãosub para exigir que as declarações incluam valores específicos pararepo,context ejob_workflow_ref.

Este modelo de personalização exige quesub 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 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, confira Pontos de extremidade da API REST para OIDC do GitHub Actions e para repositórios, confira 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 asub condição para exigir umarepo 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, confira Pontos de extremidade da API REST para OIDC do GitHub Actions e para repositórios, confira 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 asub condição para exigir umarepository_id declaração que corresponda ao valor necessário.

ou:

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

Na configuração do OIDC do provedor de nuvem, configure asub condição para exigir umarepository_owner_id declaração 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 chamadoproduction: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, confira Pontos de extremidade da API REST para OIDC do GitHub Actions e para repositórios, confira 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çãosub para exigir que as declarações incluam um valor específico paraenvironment erepository_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, confira Pontos de extremidade da API REST para OIDC do GitHub Actions e para repositórios, confira 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 asub condição para exigir que as declarações incluam valores específicos pararepo econtext.

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çãosub (no nível da organização e do repositório).

Para recusar um repositório e redefinir para o formato de declaraçãosub padrão, um administrador de repositório deve usar o ponto de extremidade de API REST emPontos de extremidade da API REST para OIDC do GitHub Actions.

Para configurar repositórios para que usem o formato de declaração padrãosub, use o ponto de extremidadePUT /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çãosub 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 extremidadePUT /repos/{owner}/{repo}/actions/oidc/customization/sub da API REST com o seguinte corpo da solicitação: Para saber mais, confiraPontos de extremidade da API REST para OIDC do GitHub Actions.

{
   "use_default": false
}

Depurar as declarações do OIDC

Você pode usar a açãogithub/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.

Permissões de fluxo de trabalho para a solicitação do token OIDC

Permissão necessária

• O trabalho ou fluxo de trabalho deve conceder aid-token: write permissão para permitir que o provedor OIDC GitHub crie um JWT (Token Web JSON):

  permissions:
    id-token: write
  

• Semid-token: write, o token de ID JWT do OIDC não pode ser solicitado. Essa configuração habilita apenas a busca e a configuração do token OIDC; ela não concede acesso de gravação a outros recursos.

Como configurar as permissões

• Para buscar um token OIDC para um fluxo de trabalho, defina a permissão no nível do fluxo de trabalho:

  permissions:
    id-token: write # This is required for requesting the JWT
    contents: read # This is required for actions/checkout
  

• Para buscar um token OIDC para um só trabalho, defina a permissão dentro desse trabalho:

  permissions:
    id-token: write # This is required for requesting the JWT
  

• Podem ser necessárias permissões adicionais dependendo das necessidades do fluxo de trabalho.

Fluxos de trabalho reutilizáveis

• Para fluxos de trabalho reutilizáveis pertencentes ao mesmo usuário, organização ou empresa que o chamador, o token OIDC gerado no fluxo de trabalho reutilizável está acessível pelo contexto do chamador.
• Para fluxos de trabalho reutilizáveis fora de sua empresa ou organização, defina explicitamente a configuraçãopermissions paraid-token comowrite no fluxo de trabalho ou no nível de trabalho do chamador. Isso garante que o token OIDC só esteja disponível para fluxos de trabalho de chamador pretendidos.

Métodos para solicitar o token OIDC

Ações personalizadas podem solicitar o token OIDC usando:

• O métodogetIDToken() do kit de ferramentas do Actions. Para obter mais informações, confiraOIDC Token na documentação do pacote npm.

• As variáveis de ambiente a seguir no executor.

  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:

  Shell

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