Esta versão do GitHub Enterprise foi descontinuada em 2021-06-09. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, melhorar a segurança e novos recursos, upgrade to the latest version of GitHub Enterprise. Para ajuda com a atualização, contact GitHub Enterprise support.

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.

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.

Identificando usuários no seu site

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

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. Observação: O ID do aplicativo e o 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. 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.
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 é verdadeiro. Use falso quando uma política proibir inscrições.

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.

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:

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&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

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

Observação: Para acessar a API com o seu aplicativo GitHub, você deve fornecer um tipo de mídia personalizado no cabeçalho Aceitar para as suas solicitações.

application/vnd.github.machine-man-preview+json

Aviso: A API pode mudar sem aviso prévio durante o período de pré-visualização. Os recursos de visualização não são compatíveis com o uso em produção. Em caso de problemas, entre em contato com o administrador do site.

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