Fluxo de Autorização OAuth 2

OAuth 2 é o protocolo padrão da indústria para autorização. De forma geral, o OAuth fornece aos clientes um acesso delegado e seguro a recursos do servidor em nome do proprietário do recurso. Especifica um processo para que os proprietários de recursos autorizem o acesso de terceiros aos seus recursos do servidor sem compartilhar 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 autorização, com a aprovação do proprietário do recurso. O terceiro usa então o token de acesso para acessar os recursos protegidos alojados no servidor de recursos.

Na Jumpseller, este fluxo de autorização gera um token de acesso que você pode usar para solicitar informações 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, usa o seu client id para solicitar um código e depois trocar esse código por um access token e um refresh token. Por padrão, o access token expira em 1 hora, mas você pode obter um novo com o refresh token.

O access token é usado pelo cliente para acessar a 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 usá-lo 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 usado 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 Usuário é convidado a autorizar o acesso dentro dos âmbitos.
3. O Usuário é redirecionado de volta para o URI especificado.
4. O Cliente solicita os tokens de acesso e de atualização usando o código recebido.
5. O Cliente recebe os tokens.
6. O Cliente usa 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 solicitando 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 Usuário é convidado a autorizar o acesso dentro dos âmbitos

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

O Usuário é redirecionado de volta para o URI especificado

Independentemente da autorização ou recusa por parte do usuário, 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 usuário 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 usado 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 usando o código recebido

Quando tiver o código de autorização, você precisará 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 usando 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 Usuário 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 salvar estas credenciais na base de dados da sua aplicação.

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

Com este access token você 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"
    }
  }

Acesse a 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, é sua responsabilidade verificar se o access token atual expirou e depois usar o refresh token para solicitar um novo access token.

NOTA: Salve 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, você pode verificar se expirou e atualizá-lo sempre que necessário.

Para atualizar o seu access token, você 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 acessar. 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 você compreende o fluxo de código de autorização do OAuth 2, é hora de aprender mais sobre a API da Jumpseller e usá-la com o seu access token.