Flujo de Autorizacion OAuth 2

OAuth 2 es el protocolo estandar de la industria para autorizacion. En general, OAuth proporciona a los clientes un acceso delegado y seguro a los recursos del servidor en nombre del propietario del recurso. Especifica un proceso para que los propietarios de recursos autoricen el acceso de terceros a sus recursos del servidor sin compartir sus credenciales. Disenado especificamente para funcionar con HTTP, OAuth esencialmente permite que los tokens de acceso sean emitidos a clientes de terceros por un servidor de autorizacion, con la aprobacion del propietario del recurso. El tercero luego usa el token de acceso para acceder a los recursos protegidos alojados por el servidor de recursos.

En Jumpseller, este flujo de autorizacion genera un access token que puedes usar para solicitar informacion de la API de Jumpseller.

Flujos de Autorizacion Soportados

El servicio OAuth 2 de Jumpseller soporta el flujo de Authorization Code, es decir, usa tu client id para solicitar un codigo y luego intercambiar este codigo por un access token y un refresh token. Por defecto, el access token expira en 1 hora, pero puedes obtener uno nuevo con el refresh token.

El access token es usado por el cliente para acceder a la API de Jumpseller.

La idea de los refresh tokens es que si un access token es comprometido, como tiene una vida corta, el atacante tiene una ventana limitada para abusar de el.

Los refresh tokens, si son comprometidos, son inutiles porque el atacante requiere el client id y el secret ademas del refresh token para obtener un access token.

El flujo de Authorization Code

Entre los diferentes flujos soportados por OAuth 2, el Authorization Code Flow es el utilizado por Jumpseller. La mayoria de los lenguajes de programacion ya proporcionan bibliotecas que abstraen el flujo OAuth 2 mostrado a continuacion y pueden facilitar tu trabajo.

Estos son los pasos del flujo de authorization code:

1. El Cliente solicita una autorizacion.
2. Se le pide al Usuario que autorice el acceso dentro de los scopes.
3. El Usuario es redirigido de vuelta a tu URI especificada.
4. El Cliente solicita los access y refresh tokens usando el codigo recibido.
5. El Cliente recibe los tokens.
6. El Cliente usa el access token para hacer solicitudes a la API de Jumpseller.
7. El Cliente recibe la respuesta de la API.
8. El Cliente solicita nuevos tokens cuando estan expirados o revocados.
9. El Cliente recibe los nuevos tokens.

Comencemos a entender cada uno de ellos.

El Cliente solicita una autorizacion

Este paso comienza con la aplicacion solicitando autorizacion al servicio OAuth 2 de Jumpseller:

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

Esta solicitud debe incluir los siguientes parametros en el query string:

Una solicitud tipica se ve asi:

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

Se le pide al Usuario que autorice el acceso dentro de los scopes

Despues de solicitar el endpoint /oauth/authorize, el servicio OAuth 2 de Jumpseller le presentara al usuario los detalles sobre los scopes para los cuales se esta solicitando acceso. Luego se le pide al usuario que autorice el acceso a los conjuntos de datos definidos en los scopes.

El Usuario es redirigido de vuelta a tu URI especificada

Sin importar si el usuario autoriza o deniega, el servicio OAuth 2 de Jumpseller redirige de vuelta a la redirect_uri informada. Desde nuestro ejemplo en el paso 1, esta direccion es http://localhost:8000/callback.

Si el usuario autoriza la solicitud, el query string de la respuesta contendra el parametro code. El parametro code es un codigo de autorizacion que puede usarse para intercambiarlo por un access token y un refresh token. Por ejemplo:

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

El Cliente solicita los access y refresh tokens usando el codigo recibido

Cuando tengas el codigo de autorizacion, necesitaras hacer una solicitud POST e intercambiarlo por un access token. Esta solicitud POST se hace al endpoint:

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

El cuerpo de esta solicitud POST debe tener los siguientes parametros:

Este es el formato cURL para solicitar tus tokens usando el codigo:

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

El Cliente recibe los tokens

En una respuesta exitosa para esta solicitud, el servicio OAuth 2 de Jumpseller retorna un codigo HTTP 200 OK en el encabezado de la respuesta y los siguientes datos JSON:

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

Entendamos cada clave-valor:

Recomendamos almacenar estas credenciales en la base de datos de tu aplicacion.

El Cliente usa el access token para hacer solicitudes a la API de Jumpseller

Con este access token puedes comenzar a hacer solicitudes a la API de Jumpseller. Hagamos una simple solicitud GET al endpoint /store/info.json:

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

El Cliente recibe la respuesta de la API

La respuesta de esta solicitud retorna los siguientes datos JSON:

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

Ve a la pagina de la API de Jumpseller para conocer nuestros endpoints.

El Cliente solicita nuevos tokens cuando estan expirados o revocados

El access token es valido por solo 1 hora, asi que cuando estes construyendo tu aplicacion web es tu responsabilidad verificar si el access token actual esta expirado y luego usar el refresh token para solicitar un nuevo access token.

OBS: Guarda los access y refresh tokens asi como una fecha de expiracion creada a partir del valor expires_in en tu base de datos. De esta forma puedes verificar si esta expirado y luego refrescarlo cada vez que sea necesario.

Para refrescar tu access token, debes hacer una solicitud POST al siguiente endpoint:

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

El cuerpo de esta solicitud POST debe tener los siguientes parametros:

Este es el formato cURL para solicitar tus tokens refrescados:

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

El Cliente recibe los nuevos tokens

La respuesta tendra la misma estructura JSON del paso 5 pero con tokens completamente nuevos.

Scopes

Los scopes definen a que datos puede acceder tu aplicacion. Solicita solo los scopes que tu aplicacion necesita. Multiples scopes se separan por espacios en el parametro scope.

Scopes de Lectura

Scopes de Escritura

Especificacion OpenAPI

La especificacion completa de la API incluyendo las definiciones de seguridad OAuth 2.0 esta disponible en:

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

Proximos pasos

Ahora que entiendes el flujo de authorization code de OAuth 2, es momento de aprender mas sobre la API de Jumpseller y usarla con tu access token.