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 Contato OAuth UOL. 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.

• Passos básicos
  • 1. Obtenha as credenciais UOL OAuth 2.0.
  • 2. Obtenha um token de acesso do UOL OAuth Server.
  • 3. Envie o token de acesso a uma API.
  • 4. Vida útil do token de acesso
• Visão geral
• Formando a URL
• Tratamento da resposta
• Como chamar uma API UOL
  • Exemplos
    • Autorização de produto
• Como criar um token de estado anti falsificação
• refresh do Token

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.

Formando a URL

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

O conjunto de parâmetros de consulta suportados pelo UOL OAuth Authorization Server para aplicações são:

 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&login_params=t%3Ddefault

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 retornados para o aplicativo com a string de consulta, 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

Depois que o aplicativo recebe o código de autorização, ele deve trocar este código de autorização para um token de acesso. Este pedido é um HTTPS POST , e pode ser usada com seguinte endpoint:

O endpoint de token de acesso possui os seguintes atributos:

POST /oauth/token HTTP/1.1
Host: api.uol.com.br
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:

{  
   "expires_in":7776000000,
   "token_type":"Bearer",
   "access_token":"fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027"
}

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
         }
      ]
   }
]

Como criar um token de estado anti falsificação 

 // 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);

# 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))

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 Contato OAuth UOL.

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

O endpoint de token de acesso possui os seguintes atributos:

exemplo:

POST /oauth/token HTTP/1.1
Host: api.uol.com.br
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 /oauHTTPth/token mostrado anteriormente:

{  
   "expires_in":7776000000,
   "token_type":"Bearer",
   "access_token":"fa7533ed95148610d07df9841ca2bdab:2.0-6d585049644158325c5736384379544359767a4633773d3d-2254-af5d52065e0a6314ab846a99f1ca3ed69946cf7480805430fa48a0d4b90cbbb4157786d905e9619b80157d5f6f2f9afa01ffd1fef773e2f6f84c4814265aa027"
}