Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para acessar as informações mais atualizadas, visite a Documentação em inglês.
� 

� 

Esta versão do GitHub Enterprise foi descontinuada em 2022-10-12. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

Como identificar e autorizar usuários para aplicativos GitHub

Neste artigo

O seu aplicativo GitHub pode executar ações em nome de um usuário, como criar um problema, criar uma implementação e usar outros pontos de extremidade compatíveis.

Observação: atualmente, os tokens de usuário prestes a vencer são um recurso opcional e estão sujeitos a alterações. Para aceitar ou recusar o recurso de vencimento de token de usuário para servidor, confira "Como ativar recursos opcionais para aplicativos". Para obter mais informações, confira "Como expirar tokens de acesso de usuário para servidor para Aplicativos do GitHub".

Quando o seu aplicativo GitHub age em nome de um usuário, ele realiza solicitações de usuário para servidor. Essas solicitações devem ser autorizadas com o token de acesso de um usuário. As solicitações de usuário para servidor incluem a solicitação de dados para um usuário, como determinar quais repositórios devem ser exibidos para um determinado usuário. Essas solicitações também incluem ações acionadas por um usuário, como executar uma criação.

Para manter tokens de acesso do usuário para servidor mais seguros, você pode usar tokens de acesso que expiram após 8 horas, e um token de atualização que pode ser trocado por um novo token de acesso. Para obter mais informações, confira "Como atualizar tokens de acesso de usuário para servidor".

Identificando usuários no seu site

Para autorizar usuários em aplicativos padrão executados no navegador, use o fluxo do aplicativo Web.

Para autorizar usuários em aplicativos sem periféricos que não têm acesso direto ao navegador, como ferramentas da CLI ou gerenciadores de credenciais do Git, use o fluxo do dispositivo. O fluxo do dispositivo usa a Concessão de Autorização de Dispositivo do OAuth 2.0.

Fluxo do aplicativo web

Ao usar o fluxo de aplicativo web, o processo para identificar usuários no seu site é:

  1. Os usuários são redirecionados para solicitar sua identidade do GitHub
  2. Os usuários são redirecionados de volta para o seu site pelo GitHub
  3. Seu aplicativo GitHub acessa a API com o token de acesso do usuário

Se você selecionar Solicitar autorização do usuário (OAuth) durante a instalação ao criar ou modificar seu aplicativo, a etapa 1 será concluída durante a instalação do aplicativo. Para obter mais informações, confira "Como autorizar usuários durante a instalação".

1. Solicitar a identidade do GitHub de um usuário

Direcione o usuário para a seguinte URL em seu navegador:

GET http(s)://HOSTNAME/login/oauth/authorize

Quando seu Aplicativo do GitHub especifica um parâmetro login, ele mostra um prompt para os usuários com uma conta específica que eles podem usar para se conectarem e autorizar seu aplicativo.

Parâmetros

NomeTipoDescrição
client_idstringNecessário. A ID do cliente do Aplicativo do GitHub. Encontre isso nas configurações do Aplicativo do GitHub ao selecionar seu aplicativo. Observação: a ID do aplicativo e a ID do cliente não são iguais e não são intercambiáveis.
redirect_uristringA URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Isso precisa ser uma correspondência exata com uma das URLs fornecidas como uma URL de retorno de chamada quando o Aplicativo do GitHub é configurado e não pode conter nenhum parâmetro adicional.
statestringIsso deve conter uma string aleatória para proteger contra ataques falsificados e pode conter quaisquer outros dados arbitrários.
loginstringSugere uma conta específica para iniciar a sessão e autorizar o aplicativo.
allow_signupstringIndependentemente de os usuários autenticados ou não atenticados terem a opção de iscrever-se em GitHub durante o fluxo do OAuth. O padrão é true. Use false quando uma política proibir inscrições.

Observação: você não precisa fornecer escopos na solicitação de autorização. Ao contrário do OAuth tradicional, o token de autorização é limitado � s permissões associadas ao seu aplicativo GitHub e � s do usuário.

2. Os usuários são redirecionados para seu site pelo GitHub

Se o usuário aceitar sua solicitação, o GitHub o redirecionará para seu site com um code temporário em um parâmetro de código, bem como o estado que você forneceu na etapa anterior em um parâmetro state. Se os estados não corresponderem, o pedido foi criado por terceiros e o processo deve ser abortado.

Observação: se você selecionar Solicitar autorização do usuário (OAuth) durante a instalação ao criar ou modificar seu aplicativo, o GitHub retornará um code temporário que você precisará trocar por um token de acesso. O parâmetro state não é retornado quando o GitHub inicia o fluxo do OAuth durante a instalação do aplicativo.

Troque este code por um token de acesso. Quando os tokens vencidos estiverem habilitados, token de acesso irá expirar em 8 horas e o token de atualização irá expirar em 6 meses. Toda vez que você atualizar o token, você receberá um novo token de atualização. Para obter mais informações, confira "Como atualizar tokens de acesso de usuário para servidor".

Os tokens de usuário expirados são atualmente um recurso opcional e estão sujeitos a alterações. Para aceitar o recurso de expiração do token de usuário para servidor, confira "Como ativar recursos opcionais para aplicativos".

Faça um pedido para o seguinte ponto de extremidade para receber um token de acesso:

POST http(s)://HOSTNAME/login/oauth/access_token

Parâmetros

NomeTipoDescrição
client_idstringNecessário. A ID do cliente do Aplicativo do GitHub.
client_secretstringNecessário. O segredo do cliente do Aplicativo do GitHub.
codestringNecessário. O código que você recebeu como resposta �  Etapa 1.
redirect_uristringA URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Isso precisa ser uma correspondência exata com uma das URLs fornecidas como uma URL de retorno de chamada quando o Aplicativo do GitHub é configurado e não pode conter nenhum parâmetro adicional.
statestringA string aleatória inexplicável que você forneceu na etapa 1.

Resposta

Por padrão, a resposta assume o seguinte formato. Os parâmetros de resposta expires_in, refresh_token e refresh_token_expires_in só são retornados quando você habilita o vencimento dos tokens de acesso de usuário para servidor.

{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expires_in": 28800,
  "refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "token_type": "bearer"
}

3. Seu Aplicativo do GitHub acessa a API com o token de acesso do usuário

O token de acesso do usuário permite que o aplicativo GitHub faça solicitações para a API em nome de um usuário.

Authorization: Bearer OAUTH-TOKEN
GET http(s)://HOSTNAME/api/v3/user

Por exemplo, no cURL você pode definir o cabeçalho de autorização da seguinte forma:

curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user

Fluxo de dispositivo

Observação: o fluxo do dispositivo está em versão beta pública e sujeito a alterações.

O fluxo de dispositivos permite que você autorize usuários para um aplicativo sem cabeçalho, como uma ferramenta de CLI ou um gerenciador de credenciais do Git.

Para obter mais informações sobre como autorizar usuários usando o fluxo do dispositivo, confira "Como autorizar aplicativos do OAuth".

Verifique quais recursos de instalação um usuário pode acessar

Depois de ter um token OAuth para um usuário, você pode verificar quais instalações o usuário poderá acessar.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations

Você também pode verificar quais repositórios são acessíveis a um usuário para uma instalação.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

Encontre mais detalhes em: Listar as instalações de aplicativo acessíveis para o token de acesso do usuário e Listar os repositórios acessíveis para o token de acesso do usuário.

Tratar uma autorização revogada do aplicativo GitHub

Se um usuário revogar a autorização dele de um Aplicativo do GitHub, o aplicativo receberá o webhook github_app_authorization por padrão. Os aplicativos GitHub não podem cancelar a assinatura deste evento. Qualquer pessoa pode revogar a autorização de um aplicativo GitHub na página de configurações da conta GitHub. Revogar a autorização de um aplicativo GitHub não desinstala o aplicativo GitHub. Você deve programar seu aplicativo do GitHub para que, ao receber esse webhook, ele para de chamar a API em nome da pessoa que revogou o token. Se o aplicativo GitHub continuar a usar um token de acesso revogado, ele receberá o erro 401 Bad Credentials.

Permissões no nível do usuário

Você pode adicionar permissões de nível de usuário ao seu Aplicativo do GitHub para acessar os recursos do usuário, como emails de usuários, que são concedidas por usuários individuais como parte do fluxo de autorização do usuário. As permissões de nível de usuário são diferentes das permissões de nível da organização e do repositório, que são concedidas no momento da instalação em uma conta pessoal ou corporativa.

Você pode selecionar permissões de nível de usuário nas configurações do Aplicativo do GitHub na seção Permissões do usuário da página Permissões e webhooks. Para obter mais informações sobre como selecionar permissões, confira "Como editar as permissões de um Aplicativo do GitHub".

Quando um usuário instala seu aplicativo em sua conta, o prompt de instalação listará as permissões de nível de usuário que seu aplicativo solicita e explicará que o aplicativo pode pedir essas permissões a usuários individuais.

Como as permissões de nível de usuário são concedidas em uma base de usuário individual, você poderá adicioná-las ao aplicativo existente sem pedir que os usuários façam a atualização. No entanto, você precisa enviar usuários existentes através do fluxo de autorização do usuário para autorizar a nova permissão e obter um novo token de usuário para servidor para essas solicitações.

Solicitações de usuário para servidor

Embora a maior parte da interação da sua API deva ocorrer usando os tokens de acesso de servidor para servidor, certos pontos de extremidade permitem que você execute ações por meio da API usando um token de acesso do usuário. O aplicativo pode fazer as solicitações a seguir usando pontos de extremidade do GraphQL ou REST.

Pontos de extremidade compatíveis

Execuções de verificação

conjuntos de verificações

Códigos de conduta

Status da implementação

Implantações

Eventos

Feeds

Blobs do Git

Confirmações do Git

Refs do Git

Tags do Git

Árvores do Git

Modelos do Gitignore

Instalações

Responsáveis pelo problema

Comentários do problema

Eventos do problema

Linha do tempo do problema

Problemas

Rótulos

Licenças

Markdown

Meta

Marcos

Hooks da organização

Integrantes da organização

Colaboradores externos da organização

Hooks pre-receive da organização

Projetos da aquipe da organização

Repositórios da equipe da organização

Equipes da organização

Organizações

Colaboradores do projeto

Projetos

Commentários pull

Eventos de revisão de pull request

Solicitações de revisão de pull request

Revisões de pull request

Pulls

Reações

Repositórios

Atividade do repositório

Branches do repositório

Colaboradores do repositório

Comentários do commit do repositório

Commits do repositório

Comunidade do repositório

Conteúdo do repositório

Envio de eventos do repositório

Hooks do repositório

Convites do repositório

Chaves de repositório

Páginas do repositório

Hooks pre-receive do repositório

Versões do repositório

Estatísticas do repositório

Root

Status

Discussões de equipe

Tópicos

Emails do Usuário

Seguidores do usuário

Chaves Gpg do usuário

Chaves públicas do usuário

Usuários

Leitura adicional