Autorizar aplicativos OAuth

A implementação OAuth de GitHub AE é compatível com o tipo de código de autorização padrão e com o OAuth 2.0 Concessão de Autorização do Dispositivo para aplicativos que não têm acesso a um navegador web.

Se você desejar ignorar a autorização do seu aplicativo da forma-padrão, como no teste do seu aplicativo, você poderá usar o fluxo do aplicativo que não é web.

Para autorizar o seu aplicativo OAuth, considere qual fluxo de autorização melhor se adequa ao seu aplicativo.

• Fluxo de aplicativos web: Usado para autorizar usuários para aplicativos OAuth padrão executados no navegador. (O tipo implícito de concessão não é compatível)
• fluxo de dispositivo: Usado para aplicativos sem cabeçalho, como ferramentas de 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 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 identidade do GitHub de um usuário

GET http(s)://[hostname]/login/oauth/authorize

Quando seu aplicativo GitHub especifica um parâmetro do login, ele solicita aos usuários com uma conta específica que podem usar para iniciar sessão e autorizar seu aplicativo.

Parâmetros

Nome	Tipo	Descrição
client_id	string	Obrigatório. O ID do cliente que você recebeu do GitHub quando você registrados.
redirect_uri	string	A URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Veja os detalhes abaixo sobre redirecionamento das urls.
login	string	Sugere uma conta específica para iniciar a sessão e autorizar o aplicativo.
escopo	string	Uma lista de escopos delimitada por espaço. Caso não seja fornecido, o escopo-padrão será uma lista vazia para usuários que 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 web duas vezes e autorizou um token com escopo do usuário e outro token com o escopo do repositório, um terceiro fluxo web que não fornece um escopo `receberá um token com os escopos dousuárioe dorepositório`.
estado	string	Uma string aleatória indescritível. É usado para proteger contra ataques de falsificação de pedidos entre sites.
allow_signup	string	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 é verdadeiro. Use falso quando uma política proibir inscrições.

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

Se o usuário aceitar a sua solicitação, o GitHub AE redireciona de volta para seu site com código temporário em um parâmetro de código, bem 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 código por um token de acesso:

POST http(s)://[hostname]/login/oauth/access_token

Parâmetros

Nome	Tipo	Descrição
client_id	string	Obrigatório. O ID do cliente que você recebeu do GitHub AE para o seu aplicativo OAuth.
client_secret	string	Obrigatório. O segredo do cliente que recebeu do GitHub AE para o seu aplicativo OAuth.
código	string	Obrigatório. O código que você recebeu como resposta ao Passo 1.
redirect_uri	string	A 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 pode receber a resposta em diferentes formatos se você fornecer o formato no cabeçalho Aceitar. 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. Use 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.

Autorização: token OUTH-TOKEN
GET https://[hostname]/api/v3/user

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

curl -H "Authorization: token OAUTH-TOKEN" https://[hostname]/api/v3/user

Fluxo de dispositivo

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.

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 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.

Parâmetros de entrada

Nome	Tipo	Descrição
client_id	string	Obrigatório. O ID do cliente que você recebeu do GitHub AE para o seu aplicativo.
escopo	string	O 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%[hostname]%2Flogin%2Fdevice

Você também pode receber a resposta em diferentes formatos se você fornecer o formato no cabeçalho Aceitar. 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>

Parâmetros de resposta

Nome	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 digitar o código do usuário `: [https://github.com/login/device`](https://github.com/login/device).
expires_in	inteiro	O número de segundos antes dos códigos device_code e user_code expirarem. O padrão é 900 segundos ou 15 minutos.
interval	inteiro	O número mínimo de segundos que decorridos antes de você poder fazer uma nova solicitação de token de acesso (POST http(s)://[hostname]/login/oauth/access_token) para 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 5 segundos, você atingirá o limite de taxa e receberá uma mensagem de 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.

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

POST http(s)://[hostname]/login/oauth/access_token

O seu aplicativo fará solicitações de autorização do dispositivo que pesquisem POST http(s)://[hostname]/login/oauth/access_token, até que o dispositivo e códigos de usuário expirem ou o usuário autorizem com sucesso o aplicativo com um código de usuário válido. O aplicativo deve usar o intervalo mínimo de sondagem recuperado na etapa 1 para evitar erros de limite de taxa. Para obter mais informações, consulte "Limites de taxa para o fluxo do dispositivo".

O usuário deve inserir um código válido em de 15 minutos (ou 900 segundos). Após 15 minutos, você deverá solicitar um novo código de autorização do dispositivo com POST http(s)://[hostname]/login/dispositivo/código.

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

Nome	Tipo	Descrição
client_id	string	Obrigatório. O ID do cliente que você recebeu do GitHub AE para o seu aplicativo OAuth.
device_code	string	Obrigatório. O código de verificação do dispositivo que você recebeu da solicitação POST http(s)://[hostname]/login/dispositivo/código.
grant_type	string	Obrigatório. O tipo de concessão deve 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 pode receber a resposta em diferentes formatos se você fornecer o formato no cabeçalho Aceitar. 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/oaccess_token) no período mínimo necessário entre solicitações (ou intervalo), você atingirá o limite de taxa e receberá uma resposta de erro slow_down. A resposta de erro slow_downadiciona 5 segundos ao último intervalo. Para obter mais informações, consulte Erros para o fluxo do 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. Espera-se que o aplicativo continue fazendo a sondagem da solicitação POST http(s)://[hostname]/login/oauth/oaccess_token sem exceder o intervalo, que exige um número mínimo de segundos entre cada solicitação.
slow_down	Ao receber o erro slow_down, são adicionados 5 segundos extras ao intervalo mínimo `ou período de tempo necessário entre as suas solicitações usandoPOST http(s)://[hostname]/login/oauth/oaccess_token. Por exemplo, se o intervalo inicial for necessário pelo menos 5 segundos entre as solicitações e você receber uma resposta de erro de slow_down, você deverá aguardar pelo menos 10 segundos antes de fazer uma nova solicitação para um token de acesso OAuth. A resposta de erro inclui o novo intervalo` que você deve usar.
expired_token	Se o código do dispositivo expirou, 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 deve ser urn:ietf:params:oauth:grant-type:device_code e incluído como um parâmetro de entrada quando você faz a sondagem da solicitação do token do OAuth POST http(s)://[hostname]/login/oauth/oaccess_token.
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 clica em cancelar durante o processo de autorização, você receberá um erro de access_denied e o usuário não poderá usar o código de verificação novamente.

Para obter mais informações, consulte "Concessão de Autorização do 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, você pode usar a autenticação básica para criar um token de acesso usando a sua página pessoal de configurações de tokens de acesso. Essa técnica permite ao usuário revogar o acesso a qualquer momento.

URLs de redirecionamento

O parâmetro 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 porta do URL de redirecionamento deve exatamente corresponder à URL de retorno de chamada. O caminho da URL de redirecionamento deve fazer referência uma subpasta da URL de retorno de chamada.

RETORNO DE CHAMADA: 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 localhhost. 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, você poderá usar 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.

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 vínculo, você precisará do client_id dos aplicativos OAuth, que você recebeu do GitHub quando fez o cadastro no aplicativo.

http(s)://[hostname]/settings/connections/applications/:client_id

Solução de Problemas

• "Solucionando erros de solicitação de autorização"
• "Solucionando erros na requisição de token de acesso do aplicativo OAuth"
• "Erros de fluxo do dispositivo"
• "Vencimento e revogação do Token"

Leia mais

• "Sobre a autenticação em GitHub"