Fluxo de Autorização OAuth 2

OAuth 2 e o protocolo padrao da industria para autorizacao. De forma geral, o OAuth fornece aos clientes um acesso delegado e seguro a recursos do servidor em nome do proprietario do recurso. Especifica um processo para que os proprietarios de recursos autorizem o acesso de terceiros aos seus recursos do servidor sem partilhar as suas credenciais. Concebido especificamente para funcionar com HTTP, o OAuth permite essencialmente que tokens de acesso sejam emitidos para clientes de terceiros por um servidor de autorizacao, com a aprovacao do proprietario do recurso. O terceiro utiliza entao o token de acesso para aceder aos recursos protegidos alojados no servidor de recursos.

Na Jumpseller, este fluxo de autorizacao gera um token de acesso que pode utilizar para solicitar informacoes da API da Jumpseller.

Fluxos de Autorização Suportados

O serviço OAuth 2 da Jumpseller suporta o fluxo de Código de Autorização (Authorization Code), ou seja, utiliza o seu client id para solicitar um código e depois trocar esse código por um access token e um refresh token. Por defeito, o access token expira em 1 hora, mas pode obter um novo com o refresh token.

O access token é utilizado pelo cliente para aceder à API da Jumpseller.

A ideia dos refresh tokens é que, se um access token for comprometido, como tem uma duração curta, o atacante tem uma janela limitada para o utilizar indevidamente.

Os refresh tokens, se comprometidos, são inúteis porque o atacante necessita do client id e do secret, além do refresh token, para obter um access token.

O Fluxo de Código de Autorização

Entre os diferentes fluxos suportados pelo OAuth 2, o Fluxo de Código de Autorização (Authorization Code Flow) é o utilizado pela Jumpseller. A maioria das linguagens de programação já disponibiliza bibliotecas que abstraem o fluxo OAuth 2 apresentado abaixo e podem facilitar o seu trabalho.

Estes são os passos do fluxo de código de autorização:

1. O Cliente solicita uma autorização.
2. O Utilizador é convidado a autorizar o acesso dentro dos âmbitos.
3. O Utilizador é redirecionado de volta para o URI especificado.
4. O Cliente solicita os tokens de acesso e de atualização utilizando o código recebido.
5. O Cliente recebe os tokens.
6. O Cliente utiliza o access token para fazer pedidos à API da Jumpseller.
7. O Cliente recebe a resposta da API.
8. O Cliente solicita novos tokens quando estes expiram ou são revogados.
9. O Cliente recebe os novos tokens.

Vamos começar a compreender cada um deles.

O Cliente solicita uma autorização

Este passo começa com a aplicação a solicitar autorização ao serviço OAuth 2 da Jumpseller:

GET https://accounts.jumpseller.com/oauth/authorize

Este pedido deve incluir os seguintes parâmetros na query string:

Um pedido típico tem este aspeto:

GET https://accounts.jumpseller.com/oauth/authorize?client_id=e27af9be9e7343dc29095d292d7a1103383a5d010c8912783e0fa54f993ca751&redirect_uri=http%3A%2F%2Flocalhost%3A8000%2Fcallback&response_type=code&scope=read_orders%20write_products%20read_customers%20write_promotions

O Utilizador é convidado a autorizar o acesso dentro dos âmbitos

Depois de solicitar o endpoint /oauth/authorize, o serviço OAuth 2 da Jumpseller apresenta ao utilizador detalhes sobre os âmbitos para os quais o acesso está a ser solicitado. O utilizador é então convidado a autorizar o acesso aos conjuntos de dados definidos nos âmbitos.

O Utilizador é redirecionado de volta para o URI especificado

Independentemente da autorização ou recusa por parte do utilizador, o serviço OAuth 2 da Jumpseller redireciona de volta para o redirect_uri informado. No nosso exemplo do passo 1, este endereço é http://localhost:8000/callback.

Se o utilizador autorizar o pedido, a query string da resposta conterá o parâmetro code. O parâmetro code é um código de autorização que pode ser utilizado para trocar por um access token e um refresh token. Por exemplo:

GET http://localhost:8000/callback?code=f04bb200f5779644a65e0a174f49776004bc3de060a96f961f72c5835533d006

O Cliente solicita os tokens de acesso e de atualização utilizando o código recebido

Quando tiver o código de autorização, precisará de fazer um pedido POST e trocá-lo por um access token. Este pedido POST é feito ao endpoint:

POST https://accounts.jumpseller.com/oauth/token

O corpo deste pedido POST deve conter os seguintes parâmetros:

Este é o formato cURL para solicitar os seus tokens utilizando o código:

curl -F grant_type=authorization_code \
-F client_id=6e19c63534c711bd2ec82da2a4bcc80638c79223b6bad064ce81a8987ec49ecb \
-F client_secret=bfab60ff47504b29bf2a29c4a8f30800286a36b590b1c36ce619f5255f43b0ef \
-F code=f04bb200f5779644a65e0a174f49776004bc3de060a96f961f72c5835533d006 \
-F redirect_uri=urn:ietf:wg:oauth:2.0:oob \
-X POST https://accounts.jumpseller.com/oauth/token

O Utilizador recebe os tokens

Numa resposta bem-sucedida a este pedido, o serviço OAuth 2 da Jumpseller devolve um código HTTP 200 OK no cabeçalho da resposta e os seguintes dados JSON:

  {
    "access_token":"80de978742714f8747036188cf6bab538e976adf72144d545e185ae444bc473d",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"86454df3e89cd34bd006ac68a76f6f2af884822ed68ce417777a4cffaae64b61",
    "created_at":1502473092
  }

Vamos compreender cada par chave-valor:

Recomendamos guardar estas credenciais na base de dados da sua aplicação.

O Cliente utiliza o access token para fazer pedidos à API da Jumpseller

Com este access token pode começar a fazer pedidos à API da Jumpseller. Vamos fazer um pedido GET simples ao endpoint /store/info.json:

curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer 80de978742714f8747036188cf6bab538e976adf72144d545e185ae444bc473d" \
https://api.jumpseller.com/v1/store/info.json

O Cliente recebe a resposta da API

A resposta deste pedido devolve os seguintes dados JSON:

  {
    "store": {
      "name":"Your Store",
      "code":"yourstore",
      "currency":"EUR",
      "country":"PT",
      "email":"youremail@example.com"
    }
  }

Aceda à página da API da Jumpseller para conhecer os nossos endpoints.

O Cliente solicita novos tokens quando estes expiram ou são revogados

O access token é válido por apenas 1 hora, por isso, ao construir a sua aplicação web, é da sua responsabilidade verificar se o access token atual expirou e depois utilizar o refresh token para solicitar um novo access token.

NOTA: Guarde os access e refresh tokens, bem como uma data de expiração criada a partir do par chave-valor expires_in, na sua base de dados. Desta forma, pode verificar se expirou e atualizá-lo sempre que necessário.

Para atualizar o seu access token, deve fazer um pedido POST ao seguinte endpoint:

POST https://accounts.jumpseller.com/oauth/token

O corpo deste pedido POST deve conter os seguintes parâmetros:

Este é o formato cURL para solicitar os seus tokens atualizados:

curl -F grant_type=refresh_token \
-F client_id=6e19c63534c711bd2ec82da2a4bcc80638c79223b6bad064ce81a8987ec49ecb \
-F client_secret=bfab60ff47504b29bf2a29c4a8f30800286a36b590b1c36ce619f5255f43b0ef \
-F refresh_token=86454df3e89cd34bd006ac68a76f6f2af884822ed68ce417777a4cffaae64b61 \
-X POST https://accounts.jumpseller.com/oauth/token

O Cliente recebe os novos tokens

A resposta terá a mesma estrutura JSON do passo 5, mas com tokens completamente novos.

Âmbitos

Os âmbitos definem a que dados a sua aplicação pode aceder. Solicite apenas os âmbitos de que a sua aplicação necessita. Múltiplos âmbitos são separados por espaços no parâmetro scope.

Âmbitos de Leitura

Âmbitos de Escrita

Especificação OpenAPI

A especificação completa da API, incluindo definições de segurança OAuth 2.0, está disponível em:

https://api.jumpseller.com/swagger.json

Próximos passos

Agora que compreende o fluxo de código de autorização do OAuth 2, é altura de aprender mais sobre a API da Jumpseller e utilizá-la com o seu access token.