Autorizar aplicativos OAuth

Observação

Considere a criação de um GitHub App em vez de um OAuth app.

O OAuth apps e o GitHub Apps usam o OAuth 2.0.

Os GitHub Apps podem atuar em nome de um usuário, semelhante a um OAuth app, ou como eles mesmos, o que é benéfico para automações que não exigem entrada do usuário. Além disso, os GitHub Apps usam permissões refinadas, dando ao usuário mais controle sobre quais repositórios o aplicativo pode acessar e usam tokens de curta duração. Para saber mais, confira Diferenças entre aplicativos GitHub e aplicativos OAuth e Sobre a criação de aplicativos GitHub.

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 aplicativo Web](#web-application-flow): usado para autorizar usuários em OAuth apps padrão executados no navegador. (Não há suporte para o [tipo de concessão implícita](https://tools.ietf.org/html/rfc6749#section-4.2)).

        [fluxo de dispositivo](#device-flow): usado para aplicativos sem periféricos, como ferramentas da CLI.

Fluxo do aplicativo web

Observação

Se você estiver criando um aplicativo GitHub, ainda poderá usar o fluxo do aplicativo Web OAuth, mas a configuração terá algumas diferenças importantes. Confira Autenticação com um aplicativo GitHub em nome de um usuário para obter mais informações.

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

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

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

GET https://github.com/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 recebida do GitHub quando você o registrou.
`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 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`.
`state`	`string`	Altamente recomendado	Uma string aleatória indescritível. É usado para proteger contra ataques de falsificação de pedidos entre sites.
`code_challenge`	`string`	Altamente recomendado	Usado para proteger o fluxo de autenticação com PKCE (chave de prova para troca de códigos). Necessário se `code_challenge_method` estiver incluído. Deve ser um hash SHA-256 de 43 caracteres de uma cadeia de caracteres aleatória gerada pelo cliente. Confira PKCE RFC para obter mais detalhes sobre essa extensão de segurança.
`code_challenge_method`	`string`	Altamente recomendado	Usado para proteger o fluxo de autenticação com PKCE (chave de prova para troca de códigos). Necessário se `code_challenge` estiver incluído. Deve ser `S256`. Não há suporte para o método de desafio de código `plain`.
`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 é `true`. Use `false` quando uma política proibir inscrições.
`prompt`	`string`	Opcional	Força o seletor de contas a aparecer se definido como `select_account`. 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, 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 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

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 `code` foi emitido, a fim de evitar ataques contra seu serviço.
`code_verifier`	`string`	Altamente recomendado	Usado para proteger o fluxo de autenticação com PKCE (chave de prova para troca de códigos). Necessário se `code_challenge` foi enviado durante a autorização do usuário. Deve ser o valor original usado para gerar o `code_challenge` na solicitação de autorização. Isso pode ser armazenado em um cookie com o parâmetro `state` ou em uma variável de sessão durante a autenticação, dependendo da arquitetura do aplicativo.

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

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 em que ele abre a sessão quando você envia tokens para autorizar seu aplicativo, havendo assim risco de confusão entre os dados do usuário se a identidade do usuário não for validada sempre que uma sessão for iniciada.

Fluxo de dispositivo

O fluxo de dispositivos permite que você autorize usuários para um aplicativo sem periféricos, como uma ferramenta da 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 do dispositivo em seu aplicativo, confira Modificando um registro de aplicativo GitHub para GitHub Apps e Modificar um aplicativo OAuth para OAuth apps.

Visão geral do fluxo do dispositivo

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.
O aplicativo solicita que o usuário insira um código de verificação em https://github.com/login/device.
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 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.

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 Escopos para aplicativos OAuth.

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%2Fgithub.com%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 `user_code`: `https://github.com/login/device`.
`expires_in`	`integer`	O número de segundos antes que o `device_code` e o `user_code` 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 (`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`.

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>

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.

Etapa 3: O aplicativo consulta o GitHub para verificar 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.

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 referente ao seu OAuth app.

device_code | string | Obrigatório. O device_code que você recebeu da solicitação POST https://github.com/login/device/code. grant_type | string | Obrigatório. O tipo de concessão precisa ser urn:ietf:params:oauth:grant-type:device_code.

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 (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 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 `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_down`	Quando 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_token`	Se 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_type`	O 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_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 `client_secret` não é necessário para o fluxo do 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 `access_denied` 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 redirect_uri parâmetro é opcional. Se não for fornecido, o GitHub redirecionará os usuários à URL de retorno de chamada definida 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 redirect_uri 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 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, você poderá usar este redirect_uri se seu aplicativo estiver escutando na porta 1234:

http://127.0.0.1:1234/path

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

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.

Isso é útil quando o OAuth app dá suporte a um fluxo de trabalho que usa o GitHub para entrada e exige apenas informações básicas do usuário. 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 da Web de cada caso, 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.

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 OAuth app para que os usuários possam revisar e revogar as respectivas autorizações do aplicativo.

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

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

Dica

Para saber mais sobre os recursos que seu OAuth app pode acessar para um usuário, confira Descobrir recursos para um usuário.

Solução de problemas

        [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors)

        [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors)

        [Erros de fluxo do dispositivo](#error-codes-for-the-device-flow)

        [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)

Leitura adicional

        [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github)

Neste artigo