Autorizar aplicativos OAuth

A implementação do OAuth feita pelo GitHub dá suporte ao tipo de concessão de código de autorização padrão e à Concessão de Autorização de Dispositivo OAuth 2.0 para aplicativos que não têm acesso a um navegador da Web.

Caso deseje ignorar a autorização do seu aplicativo da forma padrão, como no teste do aplicativo, use o fluxo de aplicativo não Web.

Para autorizar o OAuth app, analise qual fluxo de autorização é mais adequado para o aplicativo.

• Fluxo de aplicação web: usado para autorizar usuários para OAuth apps padrão que rodam no navegador. (Não há suporte para o tipo de concessão implícita).
• fluxo de dispositivo: usado para aplicativos sem periféricos, como ferramentas da CLI.

Fluxo do aplicativo web

O fluxo do aplicativo web para autorizar os usuários para seu aplicativo é:

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

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

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

Este endpoint aceita os seguintes parâmetros de entrada.

Parâmetro de consulta	Tipo	Necessário?	Descrição
client_id	string	Obrigatório	A ID do cliente que você recebeu do GitHub quando registered.
redirect_uri	string	Altamente recomendado	A URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Veja detalhes abaixo sobre as URLs de redirecionamento.
login	string	Opcional	Sugere uma conta específica para iniciar a sessão e autorizar o aplicativo.
scope	string	Dependente do contexto	Uma lista de escopos delimitada por espaço. Caso não sejam fornecidos, o aplicativo passa a utilizar como padrão uma lista vazia para os usuários que ainda não autorizaram nenhum escopo para o aplicativo. Para usuários que têm escopos autorizados para o aplicativo, a página de autorização OAuth com a lista de escopos não será exibida para o usuário. Em vez disso, esta etapa do fluxo será concluída automaticamente com o conjunto de escopos que o usuário autorizou para o aplicativo. Por exemplo, se um usuário já executou o fluxo na web duas vezes e autorizou um token com um escopo específico e outro token com um outro escopo, um terceiro fluxo na web que não fornece um escopo específico receberá um token com ambos os escopos.
state	string	Altamente recomendado	Uma string aleatória indescritível. É usado para proteger contra ataques de falsificação de pedidos entre sites.
allow_signup	string	Opcional	Se os usuários não autenticados receberão ou não uma opção para se inscrever em GitHub durante o fluxo OAuth. O padrão é . Use quando uma política proibir inscrições.
prompt	string	Opcional	Força o seletor de contas a aparecer se definido como . O seletor de conta também aparecerá se o aplicativo tiver um URI de redirecionamento que não seja HTTP ou se o usuário tiver várias contas conectadas.

No momento, não há suporte para os parâmetros PKCE (Chave de Prova para Troca de Código) e . No momento, solicitações preliminares do CORS (OPTIONS) não são suportadas.

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

Se o usuário aceitar sua solicitação, o GitHub o redirecionará novamente para seu site com um código temporário em um parâmetro de código, assim como o estado que você forneceu na etapa anterior em um parâmetro de estado. O código temporário irá expirar após 10 minutos. Se os estados não corresponderem, significa que uma terceira criou a solicitação, e você deverá abortar o processo.

Troque este por um token de acesso:

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

Este endpoint aceita os seguintes parâmetros de entrada.

Nome do parâmetro	Tipo	Necessário?	Descrição
client_id	string	Obrigatório	A ID do cliente que você recebeu do GitHub referente ao seu OAuth app.
client_secret	string	Obrigatório	O segredo do cliente que você recebeu do GitHub referente ao seu OAuth app.
code	string	Obrigatório	O código que você recebeu como resposta à Etapa 1.
redirect_uri	string	Altamente recomendado	A URL do seu aplicativo para onde os usuários são enviados após a autorização. Podemos usar isso para comparar com o URI fornecido originalmente quando o foi emitido, a fim de evitar ataques contra seu serviço.

Por padrão, a resposta assume o seguinte formato:

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer

Você também poderá receber a resposta em formatos diferentes se fornecer o formato no cabeçalho Accept. Por exemplo, Accept: application/json ou Accept: application/xml:

Accept: application/json
{
  "access_token":"gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "scope":"repo,gist",
  "token_type":"bearer"
}

Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
</OAuth>

3. Usar o token de acesso para acessar a API

O token de acesso permite que você 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

Toda vez que você receber um token de acesso, deverá usá-lo para revalidar a identidade do usuário. Um usuário pode alterar a conta na qual está conectado quando você o envia para autorizar seu aplicativo, e você corre o risco de misturar os dados do usuário se não validar a identidade do usuário após cada entrada na conta.

Fluxo de dispositivo

O fluxo de dispositivos permite que você autorize usuários para um aplicativo sem interface gráfica, como uma ferramenta de CLI ou o Gerenciador de Credenciais do Git.

Antes de usar o fluxo do dispositivo para autorizar e identificar usuários, primeiro habilite-o nas configurações do aplicativo. Para obter mais informações sobre como habilitar o fluxo do dispositivo em seu aplicativo, confira AUTOTITLE para GitHub Apps e AUTOTITLE para OAuth apps.

Visão geral do fluxo do dispositivo

1. O seu aplicativo solicita o dispositivo e o código de verificação do usuário e obtém a URL de autorização em que o usuário digitará o código de verificação do usuário.
2. O aplicativo solicita que o usuário insira um código de verificação em http(s)://HOSTNAME/login/device.
3. O aplicativo pesquisa status de autenticação do usuário. Uma vez que o usuário tenha autorizado o dispositivo, o aplicativo poderá fazer chamadas de API com um novo token de acesso.

Etapa 1: o aplicativo solicita os códigos de verificação do dispositivo e do usuário de GitHub

POST http(s)://HOSTNAME/login/device/code

O seu aplicativo deve solicitar um código de verificação e uma URL de verificação que o aplicativo usará para solicitar que o usuário seja autenticado na próxima etapa. Essa solicitação também retorna um código de verificação de dispositivo que o aplicativo deve usar para receber um token de acesso e verificar o status da autenticação do usuário.

O ponto de extremidade aceita os seguintes parâmetros de entrada.

Nome do parâmetro	Tipo	Descrição
client_id	string	Obrigatório. A ID do cliente que você recebeu do GitHub para seu aplicativo.
scope	string	Uma lista delimitada por espaço dos escopos aos quais seu aplicativo está solicitando acesso. Para saber mais, confira AUTOTITLE.

Por padrão, a resposta assume o seguinte formato:

device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%2FHOSTNAME%2Flogin%2Fdevice

Nome do parâmetro	Tipo	Descrição
device_code	string	O código de verificação do dispositivo tem 40 caracteres e é usado para verificar o dispositivo.
user_code	string	O código de verificação do usuário é exibido no dispositivo para que o usuário possa inserir o código no navegador. Este código tem 8 caracteres com um hífen no meio.
verification_uri	string	A URL de verificação em que os usuários devem inserir o : http(s)://HOSTNAME/login/device.
expires_in	integer	O número de segundos antes que o [item1] e o [item2] expirem. O padrão é 900 segundos ou 15 minutos.
interval	integer	O número mínimo de segundos que precisa transcorrer para que você possa fazer uma nova solicitação de token de acesso () a fim de concluir a autorização do dispositivo. Por exemplo, se o intervalo for 5, você não poderá fazer uma nova solicitação a partir de 5 segundos. Se você fizer mais de uma solicitação em cinco segundos, atingirá o limite de taxa e receberá o erro .

Você também poderá receber a resposta em formatos diferentes se fornecer o formato no cabeçalho Accept. Por exemplo, Accept: application/json ou Accept: application/xml:

Accept: application/json
{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJHT",
  "verification_uri": "http(s)://HOSTNAME/login/device",
  "expires_in": 900,
  "interval": 5
}

Accept: application/xml
<OAuth>
  <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
  <user_code>WDJB-MJHT</user_code>
  <verification_uri>http(s)://HOSTNAME/login/device</verification_uri>
  <expires_in>900</expires_in>
  <interval>5</interval>
</OAuth>

Passo 2: Solicite ao usuário que insira o código do usuário em um navegador

O seu dispositivo mostrará o código de verificação do usuário e solicitará que o usuário insira o código em http(s)://HOSTNAME/login/device.

Etapa 3: O aplicativo consulta o GitHub para verificar se o usuário autorizou o dispositivo

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

Seu aplicativo fará solicitações contínuas de autorização de dispositivo, até que os códigos de usuário e de dispositivo expirem ou o usuário autorize o aplicativo com sucesso utilizando um código de usuário válido. O aplicativo precisa usar o mínimo de sondagem recuperado na etapa 1 para evitar erros de limite de taxa. Para obter mais informações, confira Limites de rateio para o fluxo de dispositivos.

O usuário deve inserir um código válido em de 15 minutos (ou 900 segundos). Após 15 minutos, você precisará solicitar um novo código de autorização do dispositivo com .

Uma vez que o usuário tenha autorizado, o aplicativo receberá um token de acesso que poderá ser usado para fazer solicitações para a API em nome de um usuário.

O endpoint aceita os seguintes parâmetros de entrada.

Nome do parâmetro	Tipo	Descrição
client_id	string	Obrigatório. A ID do cliente que você recebeu do GitHub referente ao seu OAuth app.
device_code	string	Obrigatório. Os dados/informações que você recebeu da solicitação.
grant_type	string	Obrigatório. O tipo de concessão precisa ser .

Por padrão, a resposta assume o seguinte formato:

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&token_type=bearer&scope=repo%2Cgist

Você também poderá receber a resposta em formatos diferentes se fornecer o formato no cabeçalho Accept. Por exemplo, Accept: application/json ou Accept: application/xml:

Accept: application/json
{
 "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_type": "bearer",
  "scope": "repo,gist"
}

Accept: application/xml
<OAuth>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
  <token_type>bearer</token_type>
  <scope>gist,repo</scope>
</OAuth>

Limitações de taxa para o fluxo de dispositivo

Quando um usuário envia o código de verificação no navegador, há um limite de taxa de 50 envios por hora por aplicativo.

Se você fizer mais de uma solicitação de token de acesso () dentro do período mínimo necessário entre solicitações (ou ), atingirá o limite de taxa e receberá a resposta de erro . A resposta de erro adiciona cinco segundos ao último . Para obter mais informações, confira os Códigos de erros do fluxo de dispositivo.

Códigos de erro para o fluxo do dispositivo

Código do erro	Descrição
authorization_pending	Este erro ocorre quando a solicitação de autorização está pendente e o usuário ainda não inseriu o código do usuário. É esperado que o aplicativo continue sondando a solicitação sem exceder o , o que exige um número mínimo de segundos entre cada solicitação.
slow_down	Quando você recebe o erro, cinco segundos extras são adicionados ao intervalo ou ao período mínimo necessário entre as suas solicitações. Por exemplo, se o intervalo inicial exigir, pelo menos, cinco segundos entre as solicitações e você receber a resposta de erro , você precisará aguardar, no mínimo, dez segundos antes de fazer uma nova solicitação para um token de acesso OAuth. A resposta de erro inclui o novo elemento que você precisa usar.
expired_token	Se o código do dispositivo expirar, você verá o erro . Você deve fazer uma nova solicitação para um código de dispositivo.
unsupported_grant_type	O tipo de concessão precisa ser especificado e incluído como um parâmetro de entrada quando você fizer a solicitação de token OAuth.
incorrect_client_credentials	Para o fluxo do dispositivo, você deve passar o ID de cliente do aplicativo, que pode ser encontrado na página de configurações do aplicativo. O componente não é necessário para o fluxo de dispositivo.
incorrect_device_code	O device_code fornecido não é válido.
access_denied	Quando um usuário clicar em Cancelar durante o processo de autorização, você receberá o erro e o usuário não poderá usar o código de verificação novamente.
device_flow_disabled	O fluxo de dispositivo não foi ativado nas configurações do aplicativo. Para obter mais informações, confira Fluxo de dispositivo.

Para obter mais informações, confira a Concessão de Autorização de Dispositivo OAuth 2.0.

Fluxo de aplicativos não web

A autenticação que não é da web está disponível para situações limitadas como testes. Se precisar, você poderá usar a Autenticação Básica para criar um personal access token usando a página de configurações do personal access token. Essa técnica permite ao usuário revogar o acesso a qualquer momento.

URLs de redirecionamento

O parâmetro é opcional. Se omitido, o GitHub redirecionará os usuários para a URL de retorno de chamada configurada nas configurações do OAuth app. Se fornecidos, o host e a porta da URL de redirecionamento (excluindo os subdomínios) precisarão corresponder exatamente à URL de retorno de chamada. O caminho da URL de redirecionamento precisa referenciar um subdiretório da URL de retorno de chamada.

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
GOOD: http://oauth.example.com/path
GOOD: http://oauth.example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

URLs de redirecionamento de loopback

O parâmetro opcional também pode ser usado para URLs de loopback, o que é útil para aplicativos nativos em execução em um computador desktop. Se o aplicativo especificar uma URL de loopback e uma porta, após a autorização, os usuários do aplicativo serão redirecionados para a URL e a porta fornecidas. O não precisa corresponder à porta especificada na URL de retorno de chamada do aplicativo.

Para a URL de callback, você pode usar esta se seu aplicativo estiver escutando na porta:

http://127.0.0.1:1234/path

Observe que o RFC do OAuth recomenda não usar , mas usar o literal de loopback ou o IPv6 .

Criando múltiplos tokens para OAuth apps

Você pode criar vários tokens para uma combinação de usuário/aplicativo/escopo para criar tokens para casos de uso específicos.

Caso o OAuth app forneça suporte a um fluxo de trabalho que utiliza o GitHub para login e exige apenas informações básicas do usuário, isso será útil. Outro fluxo de trabalho pode exigir acesso aos repositórios privados de um usuário. Usando vários tokens, o OAuth app pode executar o fluxo web para cada caso de uso, solicitando apenas os escopos necessários. Se um usuário usar seu aplicativo apenas para entrar, nunca precisará permitir o acesso do OAuth app aos seus repositórios privados.

Há um limite de dez tokens emitidos por combinação de usuário/aplicativo/escopo e um limite de taxa de dez tokens criados por hora. Se um aplicativo criar mais de dez tokens para o mesmo usuário e os mesmos escopos, os tokens mais antigos com a mesma combinação de usuário/aplicativo/escopo serão revogados. No entanto, atingir o limite da taxa horária não revogará seu token mais antigo. Em vez disso, ele acionará um aviso de reautorização no navegador, solicitando que o usuário verifique novamente as permissões que está concedendo ao seu aplicativo. Esse prompt tem o objetivo de interromper qualquer possível loop infinito em que o aplicativo esteja preso, já que há pouca ou nenhuma razão para um aplicativo solicitar dez tokens do usuário em uma hora.

Direcionar os usuários para revisar seus acessos

Você pode vincular informações sobre a autorização de um OAuth app para que os usuários possam revisar e revogar as respectivas autorizações do aplicativo.

Para criar esse link, você precisará do OAuth app's client_id que recebeu de GitHub ao registrar o aplicativo.

http(s)://HOSTNAME/settings/connections/applications/:client_id

Solução de problemas

• AUTOTITLE
• AUTOTITLE
• Erros de fluxo do dispositivo
• AUTOTITLE

Leitura adicional

• AUTOTITLE