As APIs UOL usam o protocolo OAuth 2.0 para autenticação e autorização. O UOL suporta os cenários comum de integração de OAuth 2.0 tais como web, aplicativos móveis, desktop e outros.
OAuth 2.0 é um protocolo relativamente simples. Para começar, você deve obter as credenciais de OAuth 2.0 enviando um e-mail para <email>. Em seguida, o seu aplicativo cliente solicita um token de acesso para o UOL OAuth Server, extrai um token à partir da resposta, e envia o token para o API UOL que você deseja acessar.
Esta página apresenta uma visão geral dos cenários de autorização OAuth 2.0 que suporta UOL, e fornece links para conteúdo mais detalhado. Para detalhes sobre como usar OAuth 2.0 para autenticação, ver oauth.net.
- Servicos
e funcionalidades do Uol - Oauth 2.0
- 1 - Obter o código de acesso (access code)
-    - Tratamento da resposta
- 2 - Obter o token de acesso (access token)
-    - Obter o token de acesso (com publicId na resposta)
-    - Obter um id_token além do token de acesso
- 3 - Introspecção de Token
- 4 - Probe - Verificar a disponibilidade do Uol-Oauth 2.0
- 5 - Como chamar uma API UOL
- 6 - Como criar um token de estado anti falsificação
- 7 - Refresh do Token
- 8 - Logout
Passos básicos
Todas os aplicativos seguem um padrão básico ao acessar uma API UOL usando OAuth 2.0. Em alto nível, você segue quatro passos:
1. Obtenha as credenciais UOL OAuth 2.0.
Envie um e-mail para o contato UOL OAuth para obter as credenciais OAuth 2.0, como a identificação e a chave secreta do cliente que são conhecidos por ambos, UOL e sua aplicação. O conjunto de valores varia de acordo com o tipo de aplicação que você está construindo.
2. Obtenha um token de acesso do UOL OAuth Server.
Antes de seu aplicativo poder acessar dados privados usando uma API UOL, deve-se obter um token de acesso que concede o acesso à API. Um único token de acesso pode conceder diferentes graus de acesso a múltiplas APIs.
Existem várias maneiras de fazer este pedido e eles variam em função do tipo de aplicação que você está construindo. Por exemplo, um aplicativo instalado em um dispositivo que não tem navegador usa solicitações por meio de serviço da web; ou uma aplicação móvel que utiliza o componente Webview .
Alguns pedidos exigem uma etapa de autenticação onde o usuário faz o login com sua conta do UOL. Após o login, em alguns casos, o usuário é perguntado se ele está disposto a conceder as permissões que o aplicativo está solicitando. Este processo é chamado o consentimento do usuário.
Se o usuário concede a permissão, o UOL OAuth Server envia para seu aplicativo um token de acesso (ou um código de autorização que o aplicativo pode usar para obter um token de acesso). Se o usuário não conceder a permissão, o servidor retorna um erro.
3. Envie o token de acesso a uma API.
Depois que um aplicativo obtém um token de acesso, ele o envia a uma API UOL em um cabeçalho de autorização HTTP.
4. Vida útil do token de acesso
Os tokens de acesso têm vida útil limitada e se o token de acesso expirar, você precisará obter um novo token fazendo o fluxo novamente.
Visão geral
O endpoint UOL OAuth 2.0 suporta aplicativos de servidor web que usam linguagens e frameworks como PHP, Java, Python, Ruby, e ASP.NET e aplicativos que são instalados em dispositivos como computadores, dispositivos móveis e tablets.
A sequência de autorização começa quando seu aplicativo redireciona o navegador para uma URL UOL OAuth; a URL inclui parâmetros de consulta que indicam o tipo de acesso que está sendo solicitado. Como em outros cenários, UOL OAuth lida com a autenticação do usuário, a seleção de sessão, e em alguns casos, o consentimento do usuário. O resultado é um código de autorização que o UOL OAuth retorna à sua aplicação em uma string de consulta.
Depois de receber o código de autorização, o aplicativo pode trocar o código (junto com um ID e a chave secreta do cliente) por um token de acesso. A aplicação deve armazenar o token para uso futuro e utilizar o token de acesso para acessar uma API UOL. Uma vez que o token de acesso expirar, o aplicativo precisa novamente fazendo esse fluxo para obter um novo.
Servicos e funcionalidades do Uol - Oauth 2.0
1 - Obter o código de acesso (access code)
A URL usada para a autenticação de um usuário é https://api.uol.com.br/oauth/auth. Este ponto é acessível através de SSL e conexões HTTP são recusadas.
Endpoint
|
Descrição
|
---|---|
https://api.uol.com.br/oauth/auth | Este ponto é o alvo do pedido inicial. Ele lida com verificação de sessão ativa, autenticação do usuário, e, em alguns casos, o consentimento do usuário. O resultado da solicitações para este ponto inclui códigos de autorização e tokens de acesso. |
O conjunto de parâmetros de consulta suportados pelo UOL OAuth Authorization Server para aplicações são:
Parâmetro
|
Valores
|
Descrição |
---|---|---|
response_type
|
code |
Determina se o UOL OAuth 2.0 retorna um código de autorização. As aplicações devem usar o |
client_id |
O ID do cliente obtido do e-mail de contato do UOL OAuth |
Identifica o cliente que está fazendo a solicitação. O valor passado nesse parâmetro deve ser exatamente igual ao valor fornecido no e-mail. |
redirect_uri
|
O valor |
Determina para onde a resposta é enviada. O valor deste parâmetro deve corresponder exatamente o valor informado para este projeto no e-mail de contato UOL OAuth (incluindo o esquema http ou https, inclusive o caractere '/'). |
state |
Qualquer string | Fornece qualquer estado que pode ser útil para a sua aplicação após o recebimento da resposta. O UOL OAuth Authorization Server mantém esse parâmetro, para que o seu aplicativo receba o mesmo valor que foi enviado . Para mitigar cross-site request forgery (CSRF), é altamente recomendável incluir um token de anti falsificação neste parâmetro, e confirmá-lo na resposta. Veja esta dica para um exemplo de como fazer isso. |
t |
Valor para identificar a identidade visual personalizada do produto no fluxo de autenticação do usuário | Parâmetro opcional que permite o fluxo de autenticação do usuário ser personalizado conforme características do aplicativo ou do produto |
scope (opcional) |
Strings delimitado por espaço minuscula. Apenas "openid" e/ou "publicid" sâo aceitas | O endpoint permite o cliente especificar o scope do pedido de acesso (RFC6749). Este parâmetro é opcional se precisar um id_token com claims sobre o usuário além do token de acesso no seguinte pedido. |
https://api.uol.com.br/oauth/auth?response_type=code&redirect_uri=http%3A%2F%2Fexample.com&state=security_token%3D138r5719ru3e1%26&client_id=fa7533ed95148610d07df9841ca2bdab
Tratamento da resposta
A resposta será enviada para a redirect_uri
conforme requisição especificada na URL . Se o usuário aprovar a solicitação de acesso, então a resposta conterá um código de autorização e o parâmetro state
(se incluído no pedido). Se o usuário não aprovar o pedido, a resposta conterá uma mensagem de erro. Todas as respostas são retornadas para o aplicativo com a string de consulta (state), como mostrado abaixo:
https://example.com/code?error=access_denied&state=security_token%3D138r5719ru3e1%26
http://example.com?state=security_token%3D138r5719ru3e1%26&code=5489f29fbca93ea06661373432326564393430333835313064303664663938343163613263646264454d0e7d
2 - Obter o token de acesso (access token)
Depois que o aplicativo recebe o código de autorização (access code), ele deve trocar este código de autorização para um token de acesso (access token). Este pedido é um HTTPS POST
, e pode ser requisitado com o seguinte endpoint:
Endpoint
|
Descrição
|
---|---|
https://api.uol.com.br/oauth/token | Url de pedido de access token para o Oauth. É um pedido HTTPS POST
que recebe o access code gerado pela url anterior https://api.uol.com.br/oauth/auth
ou um refresh token no fluxo de renovacao.
|
O endpoint de token de acesso (access token) possui os seguintes atributos:
Campo
|
Descrição
|
---|---|
code | O código de autorização retornado do pedido inicial. |
client_id | O ID do cliente obtido do e-mail de contato do UOL OAuth. |
client_secret |
A chave secreta obtida do e-mail de contato do UOL OAuth. |
redirect_uri |
A URI de redirecionamento para este projeto informado no e-mail de contato do UOL OAuth. |
grant_type | Conforme definido na especificação OAuth 2.0, este campo deve conter o valor authorization_code .
|
refresh(opcional) | Parametro opcional para habilitar a renovação de Token. Valores: true|false |
POST /oauth/token HTTP/1.1 Host: api.uol.com.br Date: Thu, 11 Dec 2014 20:30:53 GMT Content-Type: application/x-www-form-urlencoded code=5489f29fbca93ea06661373432326564393430333835313064303664663938343163613263646264454d0e7d& client_id=fa7533ed95148610d07df9841ca2bdab& client_secret={client_secret}& redirect_uri=https://example.com/code& grant_type=authorization_code
Uma resposta bem sucedida a este pedido contém os seguintes campos:
Campo | Descrição |
---|---|
access_token
|
O token utilizado para acessar uma API UOL. |
expires_in |
O tempo de vida restante do token de acesso. |
token_type |
Identifica o tipo de token retornado. Neste momento, este campo terá sempre o valor |
refresh_token (opcional) | Token de Refresh utilizado para fazer a renovação do token access_token somente é mostrado quando o parametro "refresh" for colocado e se a aplicação tiver permissão de renovacao de token |
{ "expires_in":7776000000, "token_type":"Bearer", "access_token":"fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027" }
Observação
Outros campos podem ser incluídos na resposta e sua aplicação não deve tratar isso como um erro. O conjunto acima é o conjunto mínimo.
2.1 - Obter o token de acesso (com publicId na resposta)
Este serviço é uma segunda forma de se obter o access token, sendo o diferencial conter o publicId
junto com as outras informaçoẽss no retorno do serviço.
Deve-ser incluído o scope
de "publicid" no pedido
do código de acesso.
{ "expires_in":7776000000, "token_type":"Bearer", "access_token":"fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027", "publicId":"3lgbamuq40cd" }
2.2 - Obter um id_token além do token de acesso
Deve-ser incluído o scope de "openid" no pedido do código de acesso.
{ "expires_in":7776000000, "token_type":"Bearer", "access_token":"fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027", "id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXMiOiJDX1VmTEY4Um9hN3RUU3ZOd2xhOWt3IiwiYXVkIjoiZTk3ZTFmZjQ1MDc4MDdmN2E5MjRkOTlmOWIxYTgyY2QiLCJzdWIiOiJicmltdHFhaHlzMXgiLCJleHAiOjE2MzA0Njc0OTAsImlhdCI6MTYyOTc0NzQ5MH0.N7YMfgdHVcB9uWAXhtCceFGPamjrL2-3j-61gUJvEoE" }
O id_token é um JSON web token (JWT) assinado. Os conteúdos dele são os seguintes
Parâmetro | Descrição |
---|---|
sub | id do assinante. Neste caso, o publicId |
aud | o público ao qual o token se destina - clientId |
iat | A hora o token foi emitido |
exp | tempo de expiração |
ses | id da sessão filha |
Observação: para um response de erro acompanhando a RFC 7807 enviar o cabeçalho Accept com o valor:
"application/json, application/problem+json"
Exemplo de response de erro com esse Accept:
{
"detail": "Parameter or Header value missing",
"type": "errors:request-parameter-invalid",
"title": "Request parameter is invalid"
}