Observação: considere criar 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 de aplicativo Web: 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).
- fluxo de dispositivo: usado para aplicativos sem periféricos, como ferramentas da CLI.
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. Para obter mais informações, confira "Autenticação com um aplicativo GitHub em nome de um usuário".
O fluxo do aplicativo web para autorizar os usuários para seu aplicativo é:
- 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 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 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. |
allow_signup | string | Opcional | Independentemente 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âmetro | Tipo | Necessário? | Descrição |
---|---|---|---|
client_id | string | Obrigatório | A ID do cliente que você recebeu do GitHub Enterprise Server referente ao seu OAuth app. |
client_secret | string | Obrigatório | O segredo do cliente que você recebeu do GitHub Enterprise Server 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. |
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
- 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
http(s)://HOSTNAME/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.
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âmetro | Tipo | Descrição |
---|---|---|
client_id | string | Necessário. A ID do cliente que você recebeu do GitHub Enterprise Server para seu aplicativo. |
scope | string | Uma 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â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 : http(s)://HOSTNAME/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 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âmetro | Tipo | Descrição |
---|---|---|
client_id | string | Necessário. A ID do cliente que você recebeu do GitHub Enterprise Server referente ao seu OAuth app. |
device_code | string | Obrigatório. O device_code que você recebeu da solicitação POST http(s)://HOSTNAME/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>
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 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 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_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 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_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 http(s)://HOSTNAME/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 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 access_denied e o usuário não poderá usar o código de verificação novamente. |
device_flow_disabled | O 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.
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.
http(s)://HOSTNAME/settings/connections/applications/:client_id
Dica: 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
- "Solucionar problemas de erros de solicitação de autorização"
- "Solução de erros de solicitação de token de acesso do aplicativo OAuth"
- "Erros de fluxo do dispositivo"
- "Vencimento e revogação de token"