Saltar al contenido principal

Token con flujo de authorization code

¡Bienvenido, desarrollador! En esta sección vamos a aprender a generar nuestro primer Access Token! con Authorization Code para consumir las APIs de BTG PACTUAL EMPRESAS. ¡Espero que ya haya creado su primer Aplicativo para que pueda seguir el contenido de forma satisfactoria!

El Access Token obtenido por medio del Auth Code Flow da acceso a la información que el usuario acepte compartir, por lo tanto, es el token NECESARIO para consumir las APIs de banking.

Este tutorial es válido para ambos ambientes de Sandbox y Producción, así que no se preocupe si aún no ha tenido su Aplicativo verificado.

Seguridad​

Recuerde siempre que cierta información es confidencial y en ningún momento será necesaria para que podamos resolver cualquier problema que pueda encontrar. Por lo tanto, es extremadamente importante que siempre ofusque información como el Secret, Access Token...

Toda la información sensible en este tutorial estará ofuscada.

Área del Desarrollador​

Nuestra primera parada es en el Área del desarrollador, donde se espera que ya tenga un aplicativo creado según Creación de Aplicativos para consumir el servicio de APIs.

Con su aplicativo ya creado, deberá encontrar un aplicativo similar a este en sus aplicativos:

Aquí navegaremos hasta los tres puntos a la derecha y haremos clic en ellos:

Al hacer clic en detalles, encontraremos la siguiente página:

Aquí algunas cosas nos interesan en este primer momento de desarrollo

  • Claves: Aquí es donde estarán el Client Id y Client Secret de su aplicativo.
  • Versiones: Aquí es donde verá las ediciones realizadas en su aplicativo y los detalles de la versión actual de su aplicativo. Al hacer clic en "ver detalles" de la versión actual, encontrará un resumen del estado de su aplicativo. Aquí queremos la URI de redirección que registramos y los Scopes que seleccionamos en la creación.

Scopes​

El scope openid es obligatorio, pero los demás usted deberá elegirlos según las necesidades de su sistema, pues definen a qué APIs tendrá acceso su sistema.

Habiendo definido nuestros scopes y nuestra URI de redirección, ¡vamos a comenzar a preparar nuestro ambiente para realizar nuestras solicitudes!

Flujos de autenticación​

Es interesante que visite nuestras páginas sobre los Flujos que utilizaremos aquí para que entienda mejor cuáles son los protocolos, ¡pero básicamente nuestros servidores utilizan Oauth2.0!

Postman​

Muchas herramientas pueden utilizarse, desde más genéricas como Insomnia y Postman hasta herramientas específicas como Oauth tools. Aquí en el tutorial voy a utilizar la extensión de Postman para VS code, ¡pero el mismo proceso puede realizarse en cualquiera de esas herramientas!

Configurando el ambiente​

Vamos a crear variables de ambiente para facilitar nuestro proceso y al mismo tiempo facilitar la visualización de qué información está yendo a dónde. Opté por crear un ambiente llamado "Tutorial-Access_token_ambiente" y allí creé las siguientes variables:

Y las completé de la siguiente forma:

  • base_uri: https://id.sandbox.btgpactual.com
  • client_id: Client Id que está en el Área del Desarrollador
  • scope: scopes que seleccioné en el Área del Desarrollador, en este caso openid
  • prompt: por defecto mantuve login
  • redirect_uri: https://localhost.com nuestra URI ficticia

Nuestro ambiente, entonces, quedó así:

¡Con esto podemos dar inicio a nuestro flujo!

Authorization code​

Este es el primer paso para obtener nuestro tan ansiado Access Token y finalmente acceder a las APIs. En esta etapa enviamos al servidor de autenticación cierta información y él nos devuelve un authorization code referente a ello.
En postman, montamos la URI de acuerdo con la descrita en nuestra página sobre el flujo de Authorization Code y queda de la siguiente forma:

Después de eso, tomamos el cURL haciendo clic en "code":

Y utilizaremos la url en el navegador, como si hubiera hecho clic en un link o bien un botón en su sistema. Así, damos inicio al flujo de access grant:

Solo debe iniciar sesión con su cuenta de BTG Pactual Empresas.

Aquí es donde aparecen los scopes que incluyó en el flujo. A cada scope agregado, un ítem referente a él aparecerá en el flujo. En este observe que tenemos el Open Id referente al scope openId y un scope adicional que incluimos solo para demostrar cómo funciona cuando poseemos más de un scope.

Después de confirmar, será llevado a su redirect_uri, que será en nuestro caso una página no encontrada, pero al mirar la URL del navegador:

Tenemos nuestro Authorization Code (todo lo que está entre "?code=" y "&"). Este lo copiamos y podremos dar inicio al flujo del Access Token.

Consentimiento​

El consentimiento es un punto que diferencia el ambiente de sandbox del ambiente de producción. En sandbox, al no poseer el ambiente conexión con las bases de datos reales, tendrá solo la empresa de sandbox de BTG Pactual Empresas para seleccionar.

En el ambiente de producción, por otro lado, es posible y obligatorio que se emita un consentimiento para una empresa real.

Una lista de empresas en las que usted es usuario aparecerá justo después de la confirmación de los scopes. En esta lista es posible seleccionar solo una empresa. Por lo tanto, la relación entre token y empresa es de Uno a Uno. Si tiene más de una empresa que desea operar, deberá administrar un token por empresa.

Access Token​

El Access Token lo obtenemos al realizar una solicitud POST enviando el Authorization Code y algunas de nuestras credenciales según nuestra página sobre el flujo:

Después de eso, necesitamos configurar el protocolo de autenticación:

Utilizamos el esquema básico de autenticación:

  • Username es nuestro client_id configurado en el ambiente
  • Password es nuestro Secret que está allá en el Área del Desarrollador

Si opta por hacerlo de manera programática es necesario_codificar_ en base64 una string que consista de client_id:client_secret.

Ahora, configuramos el body de la request:

¡Es extremadamente importante que se envíe como form-urlencoded!
El campo code es donde colocamos nuestro Authorization code obtenido anteriormente y del campo grant_type no necesitamos preocuparnos, basta con ponerlo como muestra la documentación.

Basta con enviar la request para que recibamos de vuelta nuestro Access Token:

¡Y es así, desarrollador, como obtenemos el Access Token por medio del Authorization Code Flow!

Postman​

Tenemos una collection de postman con todas las requests más utilizadas y demandadas por nuestros clientes. Para encontrarla basta con visitar nuestra página Postman Collections