Skip to main content

Autorizar aplicativos OAuth

Você pode permitir que outros usuários autorizem o OAuth app.

Note

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 obter mais informações, confira "Diferenças entre os aplicativos GitHub e os aplicativos OAuth" e "Sobre a criação de Aplicativos do GitHub."

A implementação do OAuth feita pelo GitHub Enterprise Server 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 do aplicativo web

Note

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 "Autenticação com um aplicativo GitHub em nome de um usuário" para saber mais.

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 http(s)://HOSTNAME/login/oauth/authorize

Esse ponto de extremidade usa os parâmetros de entrada a seguir.

Parâmetro de consultaTipoNecessário?Descrição
client_idstringObrigatórioA ID do cliente recebida do GitHub quando você o registrou.
redirect_uristringAltamente recomendadoA 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.
loginstringOpcionalSugere uma conta específica para iniciar a sessão e autorizar o aplicativo.
scopestringDependente do contextoUma 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.
statestringAltamente recomendadoUma string aleatória indescritível. É usado para proteger contra ataques de falsificação de pedidos entre sites.
allow_signupstringOpcionalIndependentemente 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.

No momento, não há suporte para os parâmetros PKCE (Chave de Prova para Troca de Código) code_challenge e code_challenge_method. No momento, não há suporte para solicitações de pré-lançamento do CORS (OPTIONS).

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

Se o usuário aceitar sua solicitação, o GitHub Enterprise Server 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 http(s)://HOSTNAME/login/oauth/access_token

Esse ponto de extremidade usa os parâmetros de entrada a seguir.

Nome do parâmetroTipoNecessário?Descrição
client_idstringObrigatórioA ID do cliente que você recebeu do GitHub Enterprise Server referente ao seu OAuth app.
client_secretstringObrigatórioO segredo do cliente que você recebeu do GitHub Enterprise Server referente ao seu OAuth app.
codestringObrigatórioO código que você recebeu como resposta à Etapa 1.
redirect_uristringAltamente recomendadoA 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.

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 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 "Modificar um registro do Aplicativo GitHub" para GitHub Apps e "Modificar um aplicativo OAuth" 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.

Passo 1: O aplicativo solicita o dispositivo e os códigos de verificação de usuário do 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 usa os parâmetros de entrada a seguir.

Nome do parâmetroTipoDescrição
client_idstringNecessário. A ID do cliente que você recebeu do GitHub Enterprise Server para seu aplicativo.
scopestringUma lista delimitada por espaço dos escopos aos quais seu aplicativo está solicitando acesso. Para obter mais informações, 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%2FHOSTNAME%2Flogin%2Fdevice
Nome do parâmetroTipoDescriçã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: http(s)://HOSTNAME/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 http(s)://HOSTNAME/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": "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.

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

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

Seu aplicativo fará solicitações de autorização de dispositivo que sondam POST http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 usa os parâmetros de entrada a seguir.

Nome do parâmetroTipoDescrição
client_idstringNecessário. A ID do cliente que você recebeu do GitHub Enterprise Server referente ao seu OAuth app.
device_codestringObrigatório. O device_code que você recebeu da solicitação POST http(s)://HOSTNAME/login/device/code.
grant_typestringObrigató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>

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 http(s)://HOSTNAME/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 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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 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 é 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.

Criar vários 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 o usuário usar o aplicativo apenas para entrar, ele nunca será obrigado a permitir o acesso do OAuth app aos respectivos 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.

Warning

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.

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

Tip

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

Solução de problemas

Leitura adicional