Skip to main content

Autorizando Aplicativos OAuth

Você pode habilitar outros usuários para autorizar o seu aplicativo 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 seu aplicativo OAuth, considere qual fluxo de autorização melhor se adequa ao seu aplicativo.

Fluxo do aplicativo web

Observação: se você estiver criando um Aplicativo do GitHub, ainda poderá usar o fluxo de aplicativo Web OAuth, mas a configuração traz algumas diferenças importantes. Confira "Como identificar e autorizar usuários nos Aplicativos do GitHub" para obter mais informações.

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

  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 acessa a API com o token de acesso do usuário

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

GET https://github.com/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_idstringObrigatório. A ID do cliente recebida do GitHub quando você o registrou.
redirect_uristringA 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.
loginstringSugere uma conta específica para iniciar a sessão e autorizar o aplicativo.
scopestringUma lista de escopos delimitada por espaço. Caso ela não seja fornecida, o scope usa como padrão uma lista vazia para os usuários que não autorizaram nenhum escopo no 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 da Web duas vezes e autorizou um token com o escopo user e outro token com o escopo repo, um terceiro fluxo da Web que não fornece um scope recebe um token com o escopo user e repo.
statestringUma string aleatória indescritível. É usado para proteger contra ataques de falsificação de pedidos entre sites.
allow_signupstringIndependentemente de os usuários serem autenticados, eles receberão uma opção para inscrever-se no GitHub durante o fluxo do OAuth. O padrão é true. Use false quando uma política proibir inscrições.

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

Se o usuário aceitar sua solicitação, o GitHub o redirecionará novamente 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. 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 code por um token de acesso:

POST https://github.com/login/oauth/access_token

Parâmetros

NomeTipoDescrição
client_idstringNecessário. A ID do cliente que você recebeu do GitHub referente ao seu OAuth App.
client_secretstringNecessário. O segredo do cliente que você recebeu do GitHub referente ao seu OAuth App.
codestringNecessário. O código que você recebeu como resposta à Etapa 1.
redirect_uristringA URL do seu aplicativo para onde os usuários são enviados após a autorização.

Resposta

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 https://api.github.com/user

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

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/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.

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 de dispositivo no seu aplicativo, confira "Como modificar um Aplicativo OAuth" para Aplicativos OAuth e "Como modificar um Aplicativo do GitHub" para Aplicativos do GitHub.

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 https://github.com/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.

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

POST https://github.com/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.

Parâmetros de Entrada

NomeTipoDescrição
client_idstringNecessário. A ID do cliente que você recebeu do GitHub para seu aplicativo.
scopestringO escopo ao qual o seu aplicativo está solicitando acesso.

Resposta

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%github.com%2Flogin%2Fdevice

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": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}
Accept: application/xml
<OAuth>
  <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
  <user_code>WDJB-MJHT</user_code>
  <verification_uri>https://github.com/login/device</verification_uri>
  <expires_in>900</expires_in>
  <interval>5</interval>
</OAuth>

Parâmetros de resposta

NomeTipoDescrição
device_codestringO código de verificação do dispositivo tem 40 caracteres e é usado para verificar o dispositivo.
user_codestringO 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_uristringA URL de verificação em que os usuários devem inserir o user_code: https://github.com/login/device.
expires_inintegerO número de segundos antes que o device_code e o user_code expirem. O padrão é 900 segundos ou 15 minutos.
intervalintegerO número mínimo de segundos que precisa transcorrer para que você possa fazer uma nova solicitação de token de acesso (POST https://github.com/login/oauth/access_token) 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 slow_down.

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 https://github.com/login/device.

Campo para digitar o código de verificação do usuário exibido no seu dispositivo

Passo 3: O aplicativo solicita que o GitHub verifique se o usuário autorizou o dispositivo

POST https://github.com/login/oauth/access_token

Seu aplicativo fará solicitações de autorização de dispositivo que sondam POST https://github.com/login/oauth/access_token, até que os códigos de usuário e de dispositivo expirem ou o usuário autorize o aplicativo com sucesso com um código de usuário válido. O aplicativo precisa usar o interval mínimo de sondagem recuperado na etapa 1 para evitar erros de limite de taxa. Para obter mais informações, confira "Limites de taxa para o fluxo de dispositivo".

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 POST https://github.com/login/device/code.

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.

Parâmetros de entrada

NomeTipoDescrição
client_idstringNecessário. A ID do cliente que você recebeu do GitHub referente ao seu OAuth App.
device_codestringNecessário. O código de verificação do dispositivo que você recebeu da solicitação POST https://github.com/login/device/code.
grant_typestringNecessário. O tipo de concessão precisa ser urn:ietf:params:oauth:grant-type:device_code.

Resposta

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>

Limites de taxa para o fluxo do 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 (POST https://github.com/login/oauth/access_token) dentro do período mínimo necessário entre solicitações (ou interval), atingirá o limite de taxa e receberá a resposta de erro slow_down. A resposta de erro slow_down adiciona cinco segundos ao último interval. Para obter mais informações, confira os Erros do fluxo de dispositivo.

Códigos de erro para o fluxo do dispositivo

Código do erroDescrição
authorization_pendingEste 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 POST https://github.com/login/oauth/access_token sem exceder o interval, o que exige um número mínimo de segundos entre cada solicitação.
slow_downQuando você recebe o erro slow_down, cinco segundos extras são adicionados ao interval ou ao período mínimo necessário entre as solicitações por meio de POST https://github.com/login/oauth/access_token. Por exemplo, se o intervalo inicial exigir, pelo menos, cinco segundos entre as solicitações e você receber a resposta de erro slow_down, 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 interval que você precisa usar.
expired_tokenSe o código do dispositivo expirar, você verá o erro token_expired. Você deve fazer uma nova solicitação para um código de dispositivo.
unsupported_grant_typeO tipo de concessão precisa ser urn:ietf:params:oauth:grant-type:device_code e precisa ser incluído como um parâmetro de entrada quando a solicitação de token OAuth POST https://github.com/login/oauth/access_token é sondada.
incorrect_client_credentialsPara 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 client_secret não é necessário para o fluxo de dispositivo.
incorrect_device_codeO device_code fornecido não é válido.
access_deniedQuando um usuário clicar em Cancelar durante o processo de autorização, você receberá o erro access_denied e o usuário não poderá usar o código de verificação novamente.
device_flow_disabledO fluxo do dispositivo não foi habilitado 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 do aplicativo que não são da web

A autenticação que não é da web está disponível para situações limitadas como testes. Se necessário, use a Autenticação Básica para criar um token de acesso pessoal usando a página Configurações de tokens de acesso pessoal. Essa técnica permite ao usuário revogar o acesso a qualquer momento.

Observação: ao usar o fluxo de aplicativo não Web para criar um token OAuth2, verifique se você entendeu como usar a autenticação de dois fatores se você ou os usuários têm a autenticação de dois fatores habilitada.

URLs de redirecionamento

O redirect_uri é opcional. Se ignorado, o GitHub redirecionará os usuários para a URL de retorno de chamada definida nas configurações do Aplicativo OAuth. Se fornecido, o host e a porta da URL de redirecionamento precisará exatamente corresponder à 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
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 do Localhost

O parâmetro opcional redirect_uri também pode ser usado para URLs do localhost. Se o aplicativo especificar uma URL do localhost e uma porta, após a autorização, os usuários do aplicativo serão redirecionados para a URL e porta fornecidas. O redirect_uri não precisa corresponder à porta especificada na URL de retorno de chamada do aplicativo.

Para a URL de retorno de chamada http://127.0.0.1/path, use este redirect_uri:

http://127.0.0.1:1234/path

Criar vários tokens para aplicativos OAuth

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

Isso é útil se o seu aplicativo OAuth for compatível com um fluxo de trabalho que usa o GitHub para iniciar sessão e exigir apenas informações básicas do usuário. Outro fluxo de trabalho pode exigir acesso aos repositórios privados de um usuário. Ao usar vários tokens, o seu aplicativo OAuth pode realizar o fluxo web para cada caso, solicitando apenas os escopos necessários. Se um usuário usar apenas seu aplicativo para iniciar a sessão, ele nunca será obrigado a conceder acesso do aplicativo OAuth aos seus repositórios privados.

Há um limite de dez tokens emitidos por combinação de usuário/aplicativo/escopo. Se um aplicativo cria mais de 10 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.

Aviso: a revogação de todas as permissões de um OAuth App exclui todas as chaves SSH que o aplicativo gerou em nome do usuário, incluindo as chaves de implantação.

Direcionar os usuários para revisar seus acessos

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

Para criar esse link, você precisará da client_id dos Aplicativos OAuth que recebeu do GitHub quando registrou o aplicativo.

https://github.com/settings/connections/applications/:client_id

Dica: para saber mais sobre os recursos que o Aplicativo OAuth pode acessar para um usuário, confira "Como descobrir recursos para um usuário".

Solução de problemas

Leitura adicional