Identificar e autorizar usuários para aplicativos GitHub

Observação: Tokens de usuário vencidos são atualmente um recurso opcional e estão sujeitos a alterações. Para optar por participar do recurso de expiração de token de usuário para servidor, consulte "Habilitar funcionalidades opcionais para aplicativos". Para obter mais informações, consulte "Tokens com data de vencimento de acesso de usuário para servidor para aplicativos 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 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 é:

Os usuários são redirecionados para solicitar sua identidade do GitHub
Os usuários são redirecionados de volta para o seu site pelo GitHub
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

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

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

Nome	Tipo	Descrição
`client_id`	`string`	Obrigató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_uri`	`string`	A URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Este deve ser uma correspondência exata para um dos URLs fornecidos como uma URL de chamada de retorno ao configurar o aplicativo GitHub e não pode conter nenhum parâmetro adicional.
`estado`	`string`	Isso deve conter uma string aleatória para proteger contra ataques falsificados e pode conter quaisquer outros dados arbitrários.
`login`	`string`	Sugere uma conta específica para iniciar a sessão e autorizar o aplicativo.
`allow_signup`	`string`	Independentemente 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. 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, consulte "Atualizando tokens de acesso do usuário para servidor."

Os tokens de usuário expirados são atualmente um recurso opcional e estão sujeitos a alterações. Para optar por participar do recurso de expiração de token de usuário para servidor, consulte "Habilitar funcionalidades 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

Nome	Tipo	Descrição
`client_id`	`string`	Obrigatório. O ID do cliente para o seu aplicativo GitHub.
`client_secret`	`string`	Obrigatório. O segredo do cliente do seu aplicativo GitHub.
`código`	`string`	Obrigatório. O código que você recebeu como resposta ao Passo 1.
`redirect_uri`	`string`	A URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Este deve ser uma correspondência exata para um dos URLs fornecidos como uma URL de chamada de retorno ao configurar o aplicativo GitHub e não pode conter nenhum parâmetro adicional.
`estado`	`string`	A 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 os token de acesso de usuário para servidor vencidos.

{
  "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 pessoal.

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. Your app can make the following requests using GraphQL or REST endpoints.

Identificar e autorizar usuários para aplicativos GitHub

Neste artigo

Identificando usuários no seu site

Fluxo do aplicativo web

1. Solicitar identidade do GitHub de um usuário

Parâmetros

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

Parâmetros

Resposta

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

Fluxo de dispositivo

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

Tratar uma autorização revogada do aplicativo GitHub

Permissões no nível do usuário

Solicitações de usuário para servidor

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