Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

Identificar e autorizar usuários para aplicativos GitHub

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.

Neste artigo

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 mais informação, consulte "Refreshing user-to-server access tokens."

Identificando usuários no seu site

Para autorizar usuários para aplicativos-padrão executados no navegador, use o fluxo de aplicativo web.

Para autorizar usuários para aplicativos sem acesso direto ao navegador, como ferramentas de CLI ou gerentes de credenciais do Git, use o fluxo de dispositivos. O fluxo de dispositivo usa o OAuth 2.0 Concessão de autorização do dispositivo.

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 de 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, consulte "Autorizando usuários durante a instalação".

1. Solicitar identidade do GitHub de um usuário

GET http(s)://[hostname]/login/oauth/authorize

Quando seu aplicativo GitHub especifica um parâmetro do login, ele solicita aos usuários com uma conta específica que podem usar para iniciar sessão e autorizar seu aplicativo.

Parâmetros
NomeTipoDescrição
client_idstringObrigatório. O ID do cliente para o seu aplicativo GitHub. Você pode encontrá-lo em suas configurações do aplicativo GitHub quando você selecionar seu aplicativo.
redirect_uristringA URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Este deve ser um match exato para a URL fornecida no campo de URL de callback de autorização do usuário ao configurar o aplicativo GitHub e não pode conter nenhum parâmetro adicional.
estadostringIsso 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.

Observação: Você não precisa fornecer escopos na sua 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 de volta para o seu site pelo GitHub

Se o usuário aceitar o seu pedido, O GitHub irá fazer o redirecionamento para seu site com um código temporário em um parâmetro de código, bem como o estado que você forneceu na etapa anterior em um parâmetro do estado. 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 de usuário (OAuth) durante a instalação ao criar ou modificar seu aplicativo, o GitHub irá retornar um código temporário que você precisará trocar por um token de acesso. O parâmetro estado não é retornado quando o GitHub inicia o fluxo OAuth durante a instalação do aplicativo.

Troque este código por um token de acesso. Quando os tokens com expiração estão habilitados, o token de acesso expira em 8 horas e o token de atualização expira em 6 meses. Toda vez que você atualizar o token, você receberá um novo token de atualização. Para obter mais informações, consulte "Atualizando tokens de acesso do usuário para servidor."

Os tokens de usuário expirados atualmente fazem parte da expiração do token beta de usuário para servidor e estão sujeitos a alterações. Para optar por participar do recurso beta do token de usuário para servidor com expiração, consulte "Ativar os recursos beta para aplicativos".

POST http(s)://[hostname]/login/oauth/access_token
Parâmetros
NomeTipoDescrição
client_idstringObrigatório. O ID do cliente para o seu aplicativo GitHub.
client_secretstringObrigatório. O segredo do cliente do seu aplicativo GitHub.
códigostringObrigatório. O código que você recebeu como resposta ao Passo 1.
redirect_uristringA URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Este deve ser um match exato para a URL fornecida no campo de URL de callback de autorização do usuário ao configurar o aplicativo GitHub e não pode conter nenhum parâmetro adicional.
estadostringA 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, atualizar_token, e refresh_token_expires_in são apenas retornados quando você ativar o beta para expirar os tokens de acesso do usuário para servidor.

{
  "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
  "expires_in": "28800",
  "refresh_token": "r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692",
  "refresh_token_expires_in": "15811200",
  "scope": "",
  "token_type": "bearer"
}

3. Seu aplicativo 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.

Autorização: token OUTH-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: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/user

Fluxo de dispositivo

Nota: O fluxo do dispositivo está na 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 autorização de usuários que usam o fluxo do dispositivo, consulte "Autorizar aplicativos 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: token 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: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

Você pode encontrar mais informações em: Listar instalações de aplicativos acessíveis para o token de acesso do usuário e Listar 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 sua autorização de um aplicativo 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 a partir da sua página de configurações de conta do 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 seu aplicativo GitHub continuar usando um token de acesso revogado, ele receberá a mensagem de 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 GitHub para acessar os recursos de usuários, como, por exemplo, e-mails de usuários, concedidos por usuários individuais como parte do fluxo de autorização do usuário . As permissões de nível de usuário diferem das permissões do repositório do nível de organização, que são concedidas no momento da instalação em uma conta de organização ou usuário.

Você pode selecionar permissões de nível de usuário nas configurações do seu aplicativo GitHub na seção Permissões de usuário na página Permissões & webhooks. Para obter mais informações sobre como selecionar permissões, consulte "Editando permissões de um aplicativo 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. Seu aplicativo pode fazer as seguintes solicitações usando pontos de extremidade do GraphQL v4 ou REST v3.

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
Commits 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
Etiquetas
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
Raiz
Pesquisar
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

Esse documento ajudou você?

Privacy policy

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.