PCP

Esta sección guía a los desarrolladores de los PCPs en el proceso de integración con el flujo de consentimiento. Aquí se detallan los requisitos y pasos necesarios para la obtención y manejo de tokens de autenticación y refresh.

El flujo utilizado es el de OAuth2 authorization code flow + PKCE, siguiendo los estándares internacionales establecidos.

Requisitos Previos

Antes de comenzar con la integración, asegúrate de cumplir con los siguientes requisitos:

• Familiaridad con OAuth2 y PKCE.
• Conocimientos de JSON Web Tokens (JWT).

Referencias:

• RFC 7636

• RFC 6749

Documentación de la API PCP

Para obtener detalles completos sobre los endpoints disponibles como PCP, consulta el swagger de la API PCP.

Consideraciones Iniciales

Tokens

El servicio de autorización del PCP debe emitir access_token y refresh_token en formato JSON Web Token (JWT), cumpliendo con los estándares establecidos en RFC 7519 y RFC 9068.

Claims en los Tokens

Los siguientes claims deben estar presentes en el JWT al final del flujo de autorización:

Claims Registrados

Claim	Descripción
iss	Este campo se dejará de utilizar para las validaciones, dejándolo solo en dominio del servidor de autorización.
exp	Tiempo de expiración del token.
iat	Fecha de emisión del token, en formato numérico.
scope	Scopes con los cuales fue emitido el token, separados por espacios.

Claims Específicos

Claim	Descripción
iss_bcra_id	Emisor del JWT (Código de la entidad de 5 dígitos). Se recomienda agregar este claim específico para dejar el claim estándar iss sin adulterar.
aud_bcra_id	Cliente a quien se emitió (Código de la entidad de 5 dígitos).
user_cuit	Sujeto del JWT (CUIT del usuario).
accounts	Formato de array con las claves únicas (CBU/CVU) de las cuentas que fueron consentidas. Se utilizará en la parte transaccional para su validación.
trace_id	Utilizado para contar con una trazabilidad de las operaciones. Longitud de 16 posiciones, alfanumérico. Obligatorio. (Número aleatorio para el momento de solicitud de access).

Importante

Recomendamos agregar el claim iss_bcra_id para mantener el claim estándar iss sin modificaciones.

Referencias:

• RFC 7519 - JWT
• RFC 9068 - Best Current Practice
• JWT IO: Online JWT Debugger

---

Configuración del Endpoint /authorize

Para implementar correctamente el flujo de autorización, el endpoint debe aceptar los siguientes parámetros:

Parámetro	Descripción
response_type=code	Indica el tipo de credencial que se devolverá. En este caso, se solicita un código de autorización (code).
code_challenge=CODE_CHALLENGE	Desafío generado a partir del code_verifier. Se utiliza para implementar el flujo PKCE (Proof Key for Code Exchange).
code_challenge_method=S256	Método utilizado para generar el desafío (code_challenge). La especificación PKCE define dos métodos: S256 y plain. Se recomienda usar S256.
client_id=YOUR_CLIENT_ID	Identificador único generado por el PCP para el Cliente que está solicitando autorización.
redirect_uri=YOUR_CALLBACK_URL	URL a la que se redirigirá el navegador después de que el usuario haya otorgado la autorización. El código de autorización estará disponible en el parámetro code. La URL de callback debe estar registrada en el servidor de autorización del PCP.
scope=SCOPE	Especifica los permisos solicitados.
state=STATE	Valor alfanumérico generado por el Cliente para prevenir ataques CSRF. Este valor debe ser enviado de vuelta en la URL de redirección como parámetro state.

Importante

Los parámetros se recibirán como query parameters en la URL, conforme a los estándares de OAuth2.

El PCP debe asegurarse de configurar estos parámetros en su endpoint para cumplir con los estándares de seguridad y autorización necesarios.

Configuración de Scopes

El PCP debe asegurarse de que el endpoint acepte y gestione los siguientes scopes por defecto:

• offline_access: Permite el uso de tokens de actualización (refresh tokens).
• accounts.debit: Permite la autorización para realizar débitos en la cuenta.

Es importante que estos scopes estén habilitados y configurados correctamente para cada cliente. La configuración debe permitir la adición de nuevos scopes según las funcionalidades futuras.

Segundo Factor de Autenticación (2FA)

El segundo factor de autenticación (2FA) es una medida de seguridad obligatoria en el flujo. El PCP puede elegir el método de 2FA más adecuado. (token, SMS, OTP, etc.)

Opciones de Autenticación

Al configurar el endpoint, el PCP debe ofrecer las siguientes opciones de autenticación:

1. App to App: Es un método que permite al usuario autorizar la vinculación de cuentas sin necesidad de ingresar sus credenciales manualmente, siempre que ya esté autenticado en la app del PCP.

   

Nota

Este enfoque no solo mejora la conversión de consentimiento, sino que también optimiza la experiencia del usuario al reducir el tiempo y esfuerzo necesarios para completar el proceso de autenticación.

2. App to Web: Este es el método donde el usuario ingresa sus credenciales manualmente en una webview proporcionada por el PCP.

   

Requisitos para App to App

El servicio de autorización del PCP debe ser capaz de manejar un paso adicional en el flujo de autorización para permitir la autenticación App to App.

Payload de Sesión: El PCP debe permitir que su aplicación envíe un payload de sesión a su servicio backend. Este payload será un conjunto de datos que indican que el usuario ya ha iniciado sesión en la app del PCP. El backend se comunicará con el servidor de autorización del PCP para validar este payload. Si el payload es válido, el servidor de autorización redirigirá al usuario de vuelta a la app del cliente con un código de autorización.

Si el payload de sesión no está disponible o la autenticación App to App no está configurada, el proceso de autorización continuará utilizando el método App to Web.

Importante

La implementación de App to App puede requerir la integración de un módulo en el servidor de autorización para soportar esta funcionalidad. La forma específica en la que se implementa App to App dependerá del servicio de autorización utilizado por el PCP.

Para ver un ejemplo detallado de cómo implementar el flujo de autenticación App to App, pueden dirigirse al ejemplo de implementación con Keycloak.

Authorization Code Redirect URI

El PCP debe configurar una URL de redirección para manejar la respuesta del servidor de autorización. Esta URL se utilizará para redirigir al usuario después de que se haya completado el proceso de autorización.

La URL de redirección será la misma para todos los Clientes, y será proporcionada por MODO Conexiones.

Para cada Cliente, el PCP debe registrar esta URL de redirección en el servidor de autorización, añadiendo al final del path el BCRA ID del Cliente.

https://<DOMINIO>/connections/callback/{client_id}

---

Configuración del Endpoint /token

Este endpoint se utiliza para intercambiar el Authorization Code por un access_token y refresh_token.

curl --request POST \
  --url '/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'grant_type=authorization_code' \
  --data 'code_verifier=YOUR_GENERATED_CODE_VERIFIER' \
  --data 'code=YOUR_AUTHORIZATION_CODE' \
  --data 'user_identifier=CUIL' \
  --data 'redirect_uri=URI'

Parámetro	Descripción
client_id	Identificador único generado para el Client que está solicitando el token.
client_secret	Secreto asociado al client_id, utilizado para autenticar la solicitud.
grant_type	Tipo de concesión utilizado en esta solicitud. En este caso, debe ser authorization_code, indicando que se está intercambiando un código de autorización.
code_verifier	Clave criptográfica generada por el Cliente para verificar el code_challenge enviado en el primer paso del flujo PKCE (Proof Key for Code Exchange).
code	Código de autorización recibido del endpoint /authorize, que será intercambiado por el token de acceso.
user_identifier	Identificador del usuario (como CUIL) asociado con el código de autorización. Este parámetro se utiliza para validar que el código de autorización fue emitido para el usuario correcto.
redirect_uri	URL de redirección que debe coincidir con la URL registrada en el servidor de autorización. Este parámetro debe ser el mismo que se utilizó en la solicitud inicial al endpoint /authorize.

Validación de Titularidad

Para garantizar que el usuario en el Cliente es el mismo que autorizó la solicitud en el PCP, es esencial incluir el parámetro user_identifier al intercambiar el código de autorización. Este parámetro debe contener el CUIL del usuario registrado en el Cliente; si no coincide, se denegará la emisión del token.

Refresco del access_token

Para mantener la sesión activa sin requerir reautenticación del usuario, se debe utilizar el refresh_token para obtener un nuevo access_token cuando el anterior expire.

Rotación de Refresh Token:

Se debe implementar una política de rotación de refresh_token para asegurar que cada vez que se solicite un nuevo access_token, se emita un nuevo refresh_token.

• Duración: El refresh_token deberá tener una duración de 90 días en caso de inactividad. Este período es suficiente para mantener la sesión del usuario sin necesidad de una nueva autenticación mientras el usuario sigue activo.

• access-offline: Los servidores de autorización deben almacenar los refresh_token de manera offline para evitar riesgos de exposición y asegurar su integridad.

---

Configuración del Endpoint /revoke

Para permitir que los usuarios gestionen y den de baja el consentimiento otorgado a diferentes clientes, es fundamental implementar un endpoint de revocación conforme a RFC 7009.

curl --request POST \
--url '/revoke' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'client_secret=YOUR_CLIENT_SECRET' \
--data 'token_type_hint=refresh_token' \
--date 'token=YOUR_REFRESH_TOKEN'

Parámetro	Descripción
client_id	Identificador único generado para el Client que está solicitando la revocación.
client_secret	Secreto asociado al client_id, utilizado para revocar la solicitud.
token_type_hint	refresh_token o access_token (campo OPCIONAL).
token	Token a revocar.

El endpoint debe estar diseñado para ofrecer a los usuarios la posibilidad de revocar el consentimiento de manera sencilla y segura.

Exposición de Aplicaciones Vinculadas

Se debe proporcionar una interfaz o sección donde los usuarios puedan ver todas las aplicaciones de clientes a las que han otorgado consentimiento. Esta sección debe mostrar claramente cada aplicación vinculada, permitiendo al usuario identificar fácilmente cuál desea revocar.

Proceso de Revocación

El usuario debe poder seleccionar de manera individual el cliente para revocar el consentimiento. Al seleccionar la aplicación del cliente, se procederá a revocar el refresh_token correspondiente.

Referencias:

• RFC 7009

---

Validación de Tokens

Para la ejecución de cualquier flujo de negocio que involucre la autorización mediante Token, es necesario validar los mismos para asegurar la identidad del usuario. Este proceso tiene tres variantes, que detallamos a continuación:

Por parte del PCP

El token viaja con la solicitud al PCP y es responsabilidad del mismo validar la autenticidad de este, utilizando su propio proveedor de identidad. Esta es la manera más segura, ya que no queda responsabilidad alguna del lado de MODO Conexiones. Este proceso requiere la creación de nuevos endpoints que soporten la autenticación mediante token por parte de los PCPs.

Token introspection

Los PCPs exponen a MODO Conexiones el endpoint de introspección de token que los proveedores de identidad proveen. El mismo le indica a MODO Conexiones si un token dado es válido o no. Este endpoint sería invocado por MODO Conexiones al recibir la petición de un usuario, para luego invocar a los endpoints existentes no asegurados mediante la primera variante. Como nos basamos en el estándar Oauth2, solo necesitamos los campos obligatorios de la respuesta para verificar la validez del token.

Verificación de firma

Los PCPs se encargan de proveer a MODO Conexiones los certificados públicos con los cuales firman los tokens, y MODO Conexiones se responsabiliza por validar la integridad y validez de los tokens, para luego invocar a los endpoints existentes no asegurados mediante la primera variante.

---

Alta de Clientes de Prueba en Homologación

Para facilitar la integración y pruebas en el ambiente de staging/homologación, sigue estos pasos:

Formulario de Alta

Completa el formulario de alta PCP con la información solicitada para coordinar el acceso al entorno de pruebas.

Registro de Clientes

Registra los siguientes clientes en tu servidor de autorización y proporciona el client_id y client_secret generados a nuestro equipo de soporte.

Nombre	BCRA ID	Callback/Redirect URI
Banco MODO	00999	https://staging.api.modo.com.ar/connections/callback/00999
Credicoop	00191	https://staging.api.modo.com.ar/connections/callback/00191
Naranja	00453	https://staging.api.modo.com.ar/connections/callback/00453
Bancor	00020	https://staging.api.modo.com.ar/connections/callback/00020

Estos pasos aseguran que puedan realizarse las pruebas como PCP.