Autorizar aplicativos OAuth

A implementação OAuth de GitHub Enterprise Server é 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 implícito tipo de concessão não é compatível)

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 Enterprise Server 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 Enterprise Server para o seu aplicativo OAuth.
client_secret	string	Obrigatório. O segredo do cliente que recebeu do GitHub Enterprise Server 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=e72e16c7e42f292c6912e7710c838347ae178b4a&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":"e72e16c7e42f292c6912e7710c838347ae178b4a",
  "scope":"repo,gist",
  "token_type":"bearer"
}

Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</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 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: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/user

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"

Leia mais

• "Sobre a autenticação em GitHub"