Introducción

Este documento intenta apoyar al lector en el proceso de interactuar con el Identity Provider (IdP) de la plataforma de Recepción de Comprobantes Electrónicos del Ministerio de Hacienda. Le guiará por un paso a paso con información como ¿dónde se encuentra el IdP?, ¿cómo consumirlo?, ¿cuáles estándares se utilizan?. Le explicará con imágenes y ejemplos que le permitirán tener una mayor claridad del funcionamiento.

IMPORTANTE: Esta no es una guía oficial del Ministerio de Hacienda y de ninguna manera se relaciona directamente con ellos. Los puntos de vista y recomendaciones son nuestros únicamente, basados en la documentación y estándares indicados en la documentación de la plataforma de Recepción de Comprobantes Electrónicos.

Se le recomienda al lector leer primero la documentación de la plataforma antes de continuar con esta guía. La documentación oficial se encuentra en el URL:

La última versión al momento de escribir este documento es la 4.2, dar principal atención al Anexo #3 del documento de Anexos.

mh guia idp 17b50
Figura 1. Documentación oficial MH

¿Qué es el IdP de Comprobantes Electrónicos?

Un IdP en inglés significa Identity Provider, este se encarga de los procesos de autenticación en la plataforma. Hay varios tipos de IdP y para varias funciones, por ejemplo el IdP se podría utilizar para proteger un sitio web, en este caso, al tratar de accesar el sitio web este redireccionaría al IdP para que le solicite los credenciales y luego el IdP lo envía de regreso al sitio web ya con una sesión creada.

El funcionamiento con el servicio REST API de Recepción de Comprobantes Electrónicos sería similar, para poder consumir el servicio se necesita previamente tener una sesión en el IdP. Esta sesión no sería con una pantalla de login, sino que es para interacción con APIs.

La plataforma trabaja utilizando un modelo de seguridad con OpenID Connect (OIDC) (http://openid.net/connect/), este es una capa de identidad arriba del estándar RFC6749 The OAuth 2.0 Authorization Framework (https://tools.ietf.org/html/rfc6749). El OIDC utiliza el estándar RFC7519 JSON Web Token (JWT) (https://tools.ietf.org/html/rfc7519), para almacenar la información de la sesión dentro del token del OAuth 2.0. El Grant Type utilizado por el IdP para autenticar usuarios es el Resource Owner Password Credential.

Ahora si, ¿qué quiere decir el párrafo anterior? Básicamente lo que nos interesa entender es que el modelo de seguridad utilizado en la plataforma es una extensión del OAuth 2.0, y que para la mayoría de los casos se comporta como un OAuth 2.0. El hecho de que sea OpenID Connect agrega funcionalidad interesante pero lo único que nos importa de este es usar la función de logout y utilizar los JWT dentro de los token del OAuth 2.0.

OAuth 2.0

El OAuth 2.0 tiene varios tipos de Grants y funcionalidades, como lo indica la documentación del Anexo #3, necesitamos utilizar el Resource Owner Password Credential Grant del Auth 2.0. En este es que debemos concentrarnos, sin embargo, si les recomiendo por cultura general leer el documento del estándar para que tengan una idea más completa, y porque toda la documentación no va a estar solamente en la sección de este grant, hay flujos y términos que se encuentran en otras secciones y se van complementando conforme se lee el estándar.

Resource Owner Password Credential Grant

El OAuth 2.0 tiene varios tipos de Grants, el que se debe utilizar es el Resource Owner Password Credential Grant.

La documentación del OAuth 2.0 indica que para el Resource Owner Password Credential Grant se deben utilizar unos credenciales, estos son los credenciales que se generan desde el sistema ATV del Ministerio de Hacienda, serían usuario y contraseña. Hay dos ambientes, producción y sandbox, los credenciales son diferentes para cada ambiente y se deben generar para cada uno.

Utilizando la documentación del OAuth 2.0 y el Anexo #3 de la documentación de la plataforma, se obtiene que para obtener un token se debe enviar un payload de tipo application/x-www-form-urlencoded que contenga los campos:

  • grant_type

  • client_id

  • username

  • password

Este debe responder con un payload en application/json;charset=UTF-8 donde se indicará al menos los atributos:

  • access_token

  • refresh_token

Estos dos token son realmente un JSON Web Token, esto es parte de lo que se extiende al utilizar el OpenID Connect.

En una sección más adelante ya se mostrará con ejemplos reales como quedaría este payload y la respuesta que se obtiene.

JSON Web Token

JSON Web Token es un estándar abierto (RFC 7519) que define una forma segura de transmitir información como un JSON Object. La información puede ser validada y confiable porque esta firmada digitalmente, el IdP se encarga de firmarlos.

Una ventaja muy importante de utilizar JWT es que este contiene toda la información requerida del usuario, evitando que sea necesario consultar un repositorio de datos cada vez.

En este caso para la plataforma, el JWT se utiliza principalmente de forma interna, pero es importante entender como funciona en caso de querer obtener alguna información del JWT como el tiempo de expiración del token, que igualmente se puede obtener al momento de generarlo el token en la respuesta del OAuth 2.0.

Ejemplo de un JWT
eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJlNmE3MDczZS01MjUzLTQyMWEtYjA5ZS1hZmI2NjQ2NmU3YzQiLCJleHAiOjE1MTQ0MDM5MzAsIm5iZiI6MCwiaWF0IjoxNTE0NDAzNjMwLCJpc3MiOiJodHRwczovL2lkcC5jb21wcm9iYW50ZXNlbGVjdHJvbmljb3MuZ28uY3IvYXV0aC9yZWFsbXMvcnV0LXN0YWciLCJhdWQiOiJhcGktc3RhZyIsInN1YiI6IjBlMjZlZGIzLTk5Y2YtNDg5Zi1iY2VkLWE5OGRkNTE2NzRmMSIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFwaS1zdGFnIiwic2Vzc2lvbl9zdGF0ZSI6Ijc4MWNhMDU3LTE4NGYtNDNjZS1iMzdkLWY3NjY1ZDVhYzA4ZCIsImNsaWVudF9zZXNzaW9uIjoiM2RkYjQzMzYtMWEzMS00ZWJkLTg2OWEtMWE1N2NjOTNjNTlhIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJ2aWV3LXByb2ZpbGUiXX19LCJuYW1lIjoiRkxFQ0hBIFJPSkEgVEVDSE5PTE9HSUVTIFNPQ0lFREFEIEFOT05JTUEgIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiY3BqLTMtMTAxLTI2MTUwNkBzdGFnLmNvbXByb2JhbnRlc2VsZWN0cm9uaWNvcy5nby5jciIsImdpdmVuX25hbWUiOiJGTEVDSEEgUk9KQSBURUNITk9MT0dJRVMgU09DSUVEQUQgQU5PTklNQSIsInBvbGljeS1pZCI6IjU4YTYyMDMzNzZlYWUxNDA4Y2U1ZTdkZCIsImVtYWlsIjoiY3BqLTMtMTAxLTI2MTUwNkBzdGFnLmNvbXByb2JhbnRlc2VsZWN0cm9uaWNvcy5nby5jciJ9.GTZ7WXY5bCsBAU-E1OsFglkA38XwmZ82AkAAS4RrMM8VKWJxZG4HvMVm44MMzBmciwBJI6Uu94lp-PRYMGYtoARK3V43SKdx_QLqPEWXa0wkrkNRRhHtimTIX6pvY_e7v6b6UOrPhxBPFyNLiNitW2IsR-o4bQMtEB4d7gJ_Gengw5Ii_y-Y78eBL2fFGXEQJN-6UFMllmY8oNdTZbq6p-bKhfoqOJ5OAEwbqK5cOXnHUK91POz5axWHyvxGl879wSFaN98CXG_6XdbpiYLNAd_NsDH7Aza1Z40F_Zx1nimIf9Na_1KAKhRW_NbRbwoTKeRx1Z3Y3YuKhHFpfvjMAA

Para ver la información del JWT se puede utilizar el decoder del sitio web https://jwt.io/ .