Usando OAuth 2.0 para acessar as APIs do UOL

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.

Observação

Icon


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.

Icon

Será necessário envio de e-mail em concordância com o Termo de Uso, caso não haja concordância com o Termo mencionado o processo de cadastro não será efetivado.

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.

Observação

Icon

Salve os tokens em um armazenamento seguro de longo prazo e continue a usá-los enquanto eles continuarem a ser válidos.

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

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 redirect_uri para este projeto informado no e-mail de contato do UOL OAuth

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.
Uma URL de exemplo é apresentada abaixo.
 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 pararedirect_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:

Uma resposta de erro:
https://example.com/code?error=access_denied&state=security_token%3D138r5719ru3e1%26
Uma resposta de código de autorização:
http://example.com?state=security_token%3D138r5719ru3e1%26&code=5489f29fbca93ea06661373432326564393430333835313064303664663938343163613263646264454d0e7d

Importante

Icon
Se o seu ponto de resposta renderiza uma página HTML, todos os recursos dessa página serão capazes de ver o código de autorização na URL. Scripts podem ler a URL diretamente, e todos os recursos podem ser enviados para URL do cabeçalho HTTP Referer. Considere cuidadosamente  se você quer enviar credenciais de autorização a todos os recursos nessa página (especialmente os scripts de terceiros, tais como plugins sociais e analytics). Para evitar esse problema, recomendamos que primeiramente um recurso do servidor processe o pedido e então redirecionar para outra URL que não inclua os parâmetros de resposta.

Importante

Icon
É recomendado checar se a redirect_uri é encodada antes de ser enviada. Em Geral, quando é enviada uma url, ela é codificada para o padrão de url, porém, em alguns sistemas, esse processo não é feito e o sistema do Oauth não consegue processar a requisição.


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.
Essa request poderá conter o cabeçalho Date. (opcional)
 

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
O pedido real pode parecer com o seguinte:
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 Bearer.

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
Uma resposta bem sucedida é retornada como uma matriz JSON, semelhante ao seguinte:
{
   "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.

Uma resposta bem sucedida é retornada como uma matriz JSON, semelhante ao seguinte:
{
   "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.

Uma resposta bem sucedida é retornada como uma matriz JSON, semelhante ao seguinte:
{
   "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"
}


3 - Introspecção de Token

Esse endpoint é utilizado para verificação de um token e os detalhes do funcionamento estão descritos neste link.

O path deste endpoint está em: /oauth/token/introspect
Para utilização do endpoint é necessário que a aplicação cliente esteja cadastrada no Gibraltar, não importando o meio de autorização utilizado.

Atenção:

Apesar dos modelos de autorização estarem disponíveis (Basic e Bearer), é recomendável utilizar preferencialmente autorização do Gibraltar (Ex.: Authorization: UOLWS ....)

Ao utilizar o modelo Bearer, não é permitido que utilize o mesmo token da autorização para a introspecção.
Não faz sentido a utilização desse endpoint para validar um token, se ele mesmo já estiver invalidado.
Exemplo - Essa request poderá conter o cabeçalho Date. (opcional)

3 > POST https://api.uol.com.br/oauth/token/introspect
3 > Date: Thu, 02 Apr 2020 12:00:00 GMT
3 > Accept: application/json
3 > Content-Type: application/x-www-form-urlencoded
3 > Authorization: UOLWS fa7422ed94038510d06df9841ca2cdbd:I/RdC+YE1ATR0jdZM5lRcOvjsDAC0C3cvoeWwR+hhpw=:S2:0.2
token=fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027

Resposta:
4 < 200
4 < Connection: Keep-Alive
4 < Content-Length: 79
4 < Content-Type: application/json
4 < Date: Thu, 02 Apr 2020 12:00:01 GMT
4 < Keep-Alive: timeout=120, max=200
{"active":true,"client_id":"fa7422ed94038510d06df9841ca2cdbd","exp":1585842095}

4 - Probe - Verificar a disponibilidade do Uol-Oauth 2.0

O Probe é um serviço utilizado para a verificaçâo de disponibilidade da aplicaçâo, podendo ser consultada conforme abaixo:


Usando terminal linux:


curl -I  http://api.uol.com.br/probe


Resposta:

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 01 Apr 2021 15:12:03 GMT
Content-Length: 0
Connection: keep-alive
Expires: Thu, 01 Apr 2021 16:12:03 GMT
Cache-Control: max-age=3600
Strict-Transport-Security: max-age=63072000; includeSubdomains; preload
X-Frame-Options: DENY
X-Content-Type-Options: nosniff

O status da resposta 200 OK, significa que a aplicaçâo esta em pleno funcionamento e disponível para ser utilizada.

5 - Como chamar uma API UOL

Após o seu aplicativo obteve um token de acesso, você pode usar o token para fazer chamadas para uma API UOL em nome de uma determinada conta de usuário ou serviço. Para fazer isso, é necessário incluir o token de acesso em uma requisição para a API, incluindo o access_token em um cabeçalho HTTP Authorization: Bearer.

Exemplos

Autorização de produto

Para verificar se um usuário tem autorização para usar um ID de produto específico

Request:
> GET https://api.uol.com.br/autho/authorizations/services/7/products/32
> Date: Thu, 11 Dec 2014 20:30:53 GMT
> Accept: application/json
>
 Authorization: Bearer
fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027
Response:
< 200
< Connection: Keep-Alive
< Content-Length: 58
< Content-Type: application/json
< Date: Thu, 11 Dec 2014 20:30:57 GMT
< Keep-Alive: timeout=120, max=200
{
   "id":32,
   "status":1,
   "idtOperation":-1,
   "inheritable":false
}

Para verificar se um usuário tem autorização de produtos para um ID de serviço específico

Request:
> GET https://api.uol.com.br/autho/authorizations/services?srv=7
> Date: Thu, 11 Dec 2014 20:30:53 GMT
> Accept: application/json
>
 Authorization: Bearer
fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027
Response:
< 200
< Connection: Keep-Alive
< Content-Length: 58
< Content-Type: application/json
< Date: Thu, 11 Dec 2014 20:30:57 GMT
< Keep-Alive: timeout=120, max=200
[
   {
      "id":7,
      "products":[
         {
            "id":33,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         },
         {
            "id":401,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         },
         {
            "id":402,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         },
         {
            "id":32,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         }
      ]
   }
]

Para verificar se um usuário tem autorização de produtos para uma lista de ID de serviços

Request:
> GET https://api.uol.com.br/autho/authorizations/services?srv=1&srv=7
> Date: Thu, 11 Dec 2014 20:30:53 GMT
> Accept: application/json
>
 Authorization: Bearer
fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027
Response:
< 200
< Connection: Keep-Alive
< Content-Length: 58
< Content-Type: application/json
< Date: Thu, 11 Dec 2014 20:30:57 GMT
< Keep-Alive: timeout=120, max=200
[
   {
      "id":1,
      "products":[
         {
            "id":355,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         },
         {
            "id":8,
            "status":1,
            "idtOperation":-1,
            "inheritable":true
         },
         {
            "id":1,
            "status":1,
            "idtOperation":-1,
            "inheritable":true
         },
         {
            "id":1702,
            "status":1,
            "idtOperation":-1,
            "inheritable":true
         }
      ]
   },
   {
      "id":7,
      "products":[
         {
            "id":33,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         },
         {
            "id":401,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         },
         {
            "id":402,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         },
         {
            "id":32,
            "status":1,
            "idtOperation":-1,
            "inheritable":false
         }
      ]
   }
]

Descrição dos códigos do atributo status

Código Descrição
1 produto ou serviço autorizado
100 inscrição que tem o produto ou serviço expirada
150 inscrição que tem o produto ou serviço cancelada
200 inscrição que tem o produto ou serviço suspensa
250 inscrição que tem o produto ou serviço não autorizada
600 conta que tem o produto ou serviço não autorizado
650 conta que tem o produto ou serviço expirada
700 usuário não tem o produto ou serviço

6 - Como criar um token de estado anti falsificação

Icon

Você deve proteger a segurança de seus usuários, impedindo requisições de ataques de falsificação. O primeiro passo é criar um token de sessão única que mantém o estado entre seu aplicativo e o aplicativo cliente do usuário. Depois o aplicativo deve verificar esse token de sessão única, com a resposta do serviço de autenticação devolvido pelo UOL OAuth, para verificar se o usuário que está fazendo a requisição não um invasor mal-intencionado. Esses tokens são muitas vezes referidos como cross-site request forgery (CSRF) tokens.

Uma boa escolha para um token de estado é uma sequência de 30 ou mais caracteres construído usando um gerador de números aleatórios de alta qualidade. Outro é um hash gerado através da assinatura de algumas de suas variáveis de estado de sessão com uma chave que é mantida em segredo em seu back-end.

O código a seguir demonstra a geração de tokens de sessão únicas.

Java example
 // Create a state token to prevent request forgery.
 // Store it in the session for later validations.
 String state = new BigInteger(130, new SecureRandom()).toString(32);
 request.session().attribute("state", state);
 // Read index.html into memory, and set the client ID,
 // token state and application name in the HTML before serving it.
 return new Scanner(new File("index.html"), "UTF-8")
      .useDelimiter("\\A").next()
      .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
      .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
      .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
                  APPLICATION_NAME);
Python example
# Create a state token to prevent request forgery.
# Store it in the session for later validations.
state = ''.join(random.choice(string.ascii_uppercase + string.digits)
                  for x in xrange(32))
session['state'] = state
# Set the client ID, token state and application name in the HTML while
# serving it.
response = make_response(
      render_template('index.html',
                      CLIENT_ID=CLIENT_ID,
                      STATE=state,
                      APPLICATION_NAME=APPLICATION_NAME))

7 - Refresh do Token

  +--------+                                           +---------------+
  |        |--(A)------- Authorization Grant --------->|               |
  |        |                                           |               |
  |        |<-(B)----------- Access Token -------------|               |
  |        |               & Refresh Token             |               |
  |        |                                           |               |
  |        |                                           |               |
  |        |--(C)----------- Access Token ------------>|               |
  |        |                                           |               |
  |        |<-(D)-------- Protected Resource --------->|      UOL      |
  | Your   |                                           |     Server    |
  | App    |--(E)------------ Access Token ----------->|               |
  |        |                                           |               |
  |        |<-(F)--------- Invalid Token Error ------->|               |
  |        |                                           |               |
  |        |                                           |               |
  |        |--(G)----------- Refresh Token ----------->|               |
  |        |                                           |               |
  |        |<-(H)----------- Access Token -------------|               |
  +--------+           & Optional Refresh Token        +---------------+

Refresh é o processo de renovação do Access Token. O Access Token deixa de ser válido quando ultrapassa o tempo de expiração. Nesse ponto, seria necessário requisitar novamente as credenciais do usuário através da tela de login repetindo todo o processo de autenticacao novamente. Esse processo de login e autenticacao são mostrados nas setas (A),(B). Assim, para evitar a autenticação do cliente, o refresh Token foi criado para fazer a renovacao do Access Token. A requisição do Refresh pode ser vista na seta (G) e (H) do desenho. Nessas duas setas é enviado o Refresh Token e o Oauth do UOL retorna um novo Access Token e opcionalmente um novo Refresh Token.

A renovação é pode ser feita a qualquer momento se o Refresh Token estiver válido, independente do Access Token ter expirado ou não.

O Refresh Token pode ser habilitado através da chamada ao endpoint https://api.uol.com.br/oauth/token com o parâmetro refresh igual a true. É também necessário requisitar o serviço para <email>.

O tempo de expiração do Refresh Token é duas vezes o tempo de expiração do Access Token.

O endpoint do token pode ser usado com os parametros refresh_token informando o token de refresh e grant_type=refresh_token, ao invés do code

Endpoint
Descrição
https://api.uol.com.br/oauth/token

Url de pedido de token para o Oauth. É um pedido HTTPS POST que recebe o code gerado pela url anterior https://api.uol.com.br/oauth/auth ou um refresh token no fluxo de renovacao.  Essa request poderá conter o cabeçalho Date. (opcional)

O endpoint de token de acesso possui os seguintes atributos:

Campo
Descrição
refresh_token

Token refresh recebido

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 refresh_token
refresh(opcional) Parametro opcional para habilitar a renovação de Token. Valores: true|false

exemplo:

O pedido real pode parecer com o seguinte:
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

refresh_token={refresh_token}&
client_id=fa7533ed95148610d07df9841ca2bdab&
client_secret={client_secret}&
redirect_uri=https://example.com/code&
grant_type=refresh_token

A resposta é identica ao fluxo do enpoint /oauth/token mostrado anteriormente:

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

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

Considerações de Segurança

  1. a validade (tempo de duração) do token de acesso, prevista na RFC 6749, passa a ser inócua, já que um novo token pode ser obtido indefinidamente a partir do refresh token;
  2. a aplicação cliente passa a ter credencial para acesso aos recursos do usuário permanentemente, já que um novo token pode ser emitido sempre que necessário, sem intervenção do proprietário dos recursos;
  3. o vazamento do refresh token permitiria a seu interceptador solicitar um token de acesso e obter acesso indevido aos recursos do usuário;
  4. o proprietário do recurso perderia o controle sobre o acesso a tais recursos, já que a aplicação cliente poderia emitir um novo token de acesso sempre que desejar.
Uma resposta bem sucedida é retornada como uma matriz JSON, semelhante ao seguinte:
{
   "expires_in":7776000000,
   "token_type":"Bearer",
   "access_token":"fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027"
}

8 - Logout

Este serviço só está disponível para sessões com scope que inclui "openid".

Endpoint

Descrição

https://api.uol.com.br/oauth/logout

Pedido HTTPS GET - Este serviço é usado para derrubar a sessão filha no servidor de sessão e redirecionar o usuário para o redirect_uri. Essa request poderá conter o cabeçalho Date. (opcional)

Campo

Descrição

redirect_uri A URI para redirecionar depois que o logout
id_token Openid token emitido na etapa 2.2


exemplo:

O pedido real pode parecer com o seguinte:
GET /oauth/logout HTTP/1.1
Host: api.uol.com.br
Date: Thu, 11 Dec 2014 20:30:53 GMT

redirect_uri=https://example.com&
id_token={id_token}
Uma resposta bem sucedida é retornada sem body, e tem os seguintes headers.
{
	Expire: "Thu, 01 Jan 1970 00:00:00 GMT",
	Connection: "keep-alive",
	Cache-Control: "no-store",
	Pragma: "no-cache",
	Location: "https://example.com",
	Content-Length: "0",
}