Métodos de autenticación

Sólo se puede acceder a la API de Open Data junto con un token de autorización que debe estar presente en cada solicitud, en una cabecera especial. Actualmente, ofrecemos dos esquemas de seguridad para la autorización, el token OAuth y el token de clave de API. Tendrá la opción de usar uno u otro en cualquier momento, pero no ambos simultáneamente. Si llama a cualquier servicio sin autenticar la solicitud, obtendrá un error 401.

Atención

Durante los próximos meses se retirará el soporte para el uso de claves API, y la única forma de autorización válida será con el uso de Bearer tokens. Se avisará oportunamente la fecha definitiva.

Esto significa:

  • Todas las solicitudes deberán usar el encabezado Authorization Bearer con el valor JWT. El encabezado x-api-key estará prohibido.
  • Se eliminarán todos los endpoints tipo "AccountLink".
  • Si una solicitud usa el parámetro AccountCredential en la carga útil (JSON payload), se ignorará.
  • Si necesita llamar a endpoints que requieren autenticación (bancos, por ejemplo), debe redirigir al usuario al formulario de inicio de sesión del servidor de autorización de Khipu y luego completar el flujo authorization code para generar un JWT.

🔐 Token OAuth

OAuth 2.0 es un protocolo estándar de la industria para la autorización, que permite a las aplicaciones obtener acceso limitado a las cuentas de usuario en un servicio HTTP. Proporciona un método seguro y escalable para obtener la autorización del usuario al mismo tiempo que protege las credenciales del usuario. Utilizamos tokens web JSON (JWT) para transmitir información de forma segura entre las partes, lo que garantiza que los datos se puedan verificar y sean confiables. JWT es un medio compacto y seguro para representar información (claims) entre dos partes, que generalmente consta de un encabezado, una carga útil y una firma. Se utiliza comúnmente en escenarios de OAuth debido a su capacidad para verificarse fácilmente y su compatibilidad con claims autónomos y a prueba de manipulaciones. Además, se puede revocar fácilmente si se ha visto comprometido.

Flujos OAuth

Dos partes (Client Credentials Flow)

El enfoque de dos partes, también conocido como flujo de credenciales del cliente, se utiliza para interacciones de servidor a servidor donde la aplicación accede a los recursos en su propio nombre sin la participación del usuario. En el caso de las API Open Data de Khipu, se utilizará para el acceso a fuentes de datos públicas.

Tres partes (Authorization Code Flow)

El enfoque de tres partes, o flujo de código de autorización, implica el consentimiento del usuario y se utiliza cuando una aplicación necesita acceder a recursos en nombre de un usuario. En este flujo, la aplicación cliente redirige al usuario al servidor de autorización para obtener el consentimiento. La interfaz gráfica será similar a la de un pago normal en Khipu, pero al finalizar el proceso, la redirección se realizará inmediatamente a la dirección de callback redirect_uri especificada al iniciar la autenticación.

Es responsabilidad del cliente implementar la URI de redirección para recibir el código de autorización después del consentimiento del usuario.

Hemos implementado este flujo utilizando el protocolo OpenId Connect, por lo que, si necesario, podemos incluir claims con información del usuario en forma de id_token.

Obtener JWT utilizando Client Credentials Flow

Para obtener un JWT utilizando el flujo de credenciales del cliente, siga estos pasos:

Solicitar el Token

Copy
Copied
curl -X POST https://auth-server.khipu.com/oauth2/token \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -d "grant_type=client_credentials"
  • grant_type : el tipo de concesión que se utiliza. Para este flujo, es client_credentials .
  • Authorization : encabezado de autenticación básica que contiene el ID y el secreto del cliente, codificado en base64.

Respuesta

Copy
Copied
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "bearer",
  "expires_in": 31536000,
  "scope": "openid"
}
  • access_token : el JWT que se utilizará para acceder a los recursos protegidos.
  • token_type : el tipo de token ("bearer").
  • expires_in : el período de validez del token en segundos.
  • scope : los alcances otorgados al token.

Obtención de JWT mediante el flujo de código de autorización

Importante

Para generar un token JWT para acceder a datos pertenecientes a un tercero, debes proporcionar los recursos que normalmente requiere este flujo:

  • una interfaz de usuario (para realizar la incorporación de tu usuario y realizar la llamada a /authorize ).
  • un callback/webhook (parámetro redirect_uri ) para recibir el código de autorización después de una autenticación exitosa. Debes configurar este valor en la sección privada del sitio web de Khipu.
  • un backend encargado de solicitar el token y almacenarlo.

Khipu no almacenará claims confidenciales del JWT, el único claim que persiste es el identificador único (jti) que permite la validación y revocación del token.

Para obtener un JWT utilizando el flujo de código de autorización, siga estos pasos:

Paso 1: Redireccionamiento del usuario para obtener el consentimiento

Redireccionar al usuario al servidor de autorización:

Copy
Copied
https://auth-server.khipu.com/oauth2/authorize
?client_id=<your_client_id>
&redirect_uri=https://your-app.com/callback
&response_type=code
&response_mode=query
&scope=openid
&state=<random_string>
&nonce=<random_string>
&custom=<optional_value>
&institution_id=<institution_for_consent_process>
  • client_id : El ID de cliente de tu aplicación.
  • redirect_uri : La URI donde se enviará el código de autorización luego del consentimiento del usuario.
  • response_type : El tipo de respuesta. Para este flujo, es "code".
  • response_mode : Elige cómo quieres recibir el código de autorización en tu redirect_uri . Puede ser query o form_post .
  • scope : Los permisos que solicita tu aplicación. Para la API de Khipu, usa siempre openid .
  • state y nonce son valores opcionales, pero recomendados para mayor seguridad.
  • custom : puedes usar este campo para enviar un valor que quieras asociar con el JWT (se agregará como un claim ). Por ejemplo, puedes configurar su valor para indicar una unidad o departamento en tu empresa donde se usará el JWT. Este valor además se devolverá en la respuesta, en el encabezado x-custom .
  • institution_id : consulte el listado de instituciones que respaldamos actualmente. Debe incluir una institución válida para que pueda comenzar el proceso de consentimiento.

Paso 2: Intercambio de código de autorización por token

Después de que el usuario da su consentimiento, el servidor de autorización lo redirecciona a la URL de redireccionamiento especificada con un código de autorización. Utilice este código para solicitar un token:

Copy
Copied
curl -X POST https://auth-server.khipu.com/oauth2/token \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -d "grant_type=authorization_code" \
  -d "code=<authorization_code_recibido>" \
  -d "redirect_uri=https://your-app.com/callback"
  • grant_type : el tipo de concesión que se está utilizando. Para este flujo, es authorization_code .
  • code : el código de autorización recibido del servidor de autorización.
  • redirect_uri : el mismo URI utilizado durante la solicitud de autorización.

Respuesta

Copy
Copied
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "bearer",
  "expires_in": 31536000,
  "id_token": "tGzv3JOkF0XG5Qx2TlKWIA...",
  "scope": "openid"
}
  • id_token : En la primera fase de la implementación de OAuth, no se incluirán datos del usuario, solo declaraciones estándar básicas como: sub , aud , iss .

Dónde encontrar tus credenciales de cliente

Para autenticarte contra nuestro endpoint /token (y también /revoke), debes enviar credenciales que se pueden obtener en tu página privada en khipu.com. Ve a la configuración de tu cuenta ("Opciones de la cuenta") y desplázate hacia abajo hasta encontrar los valores en la sección "Para integrar Khipu a tu sitio web", como se muestra a continuación.

client_credentials

  • client_id : Será el valor del campo "Id de cobrador".
  • client_secret : Será el valor del campo "Llave".

Uso del JWT para acceder a recursos protegidos

Para acceder a recursos protegidos mediante el JWT obtenido, inclúyalo en el encabezado de autorización de su solicitud:

Copy
Copied
curl -X POST https://api.khipu.com/resource \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR..."
  <payload>

Consulte la sección "API de datos abiertos" en este sitio para ver la documentación y los ejemplos de cada endpoint disponible.

Acerca de la caducidad de los tokens y otras características

Los tokens JWT emitidos por nuestros servidores de autorización tendrán una validez de un año completo. La posibilidad de utilizar tokens de actualización ("refresh_token") está deshabilitada. Si un token se ve comprometido, puede revocarlo y generar uno nuevo. Después de cada cambio de credenciales (por ejemplo, cuando un banco obliga a su cliente a cambiar la contraseña), el JWT actual ya no debe utilizarse y el usuario debe pasar por el proceso de autenticación nuevamente.

Revocar un JWT

Para revocar un JWT y ponerlo en una lista negra, utilice el siguiente endpoint:

Copy
Copied
curl -X POST https://auth-server.khipu.com/oauth2/revoke \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -d "token=eyJhbGciOiJIUzI1NiIsInR..."
  • token : el token portador de JWT que desea revocar.

Debería recibir un código de estado HTTP 200 para indicar que el token fue revocado.

🔑 Clave API

IMPORTANTE

La posibilidad de usar una clave API se eliminará en breve. Se le recordará con anticipo para que pueda preparar su migración al esquema OAuth/JWT.

Api key es el método más sencillo, ya que sólo tienes que pasar la clave única de tu cuenta como parámetro en una cabecera especial de tu petición HTTP, llamada x-api-key.

Inicialmente este valor te será proporcionado cuando habilites tu cuenta de Khipu, por lo que es tu responsabilidad guardar tu clave y mantenerla a salvo en todo momento, teniendo cuidado de no compartirla con usuarios no deseados o consignarla en tu repo de código fuente.

Recordatorio de seguridad

Recuerda que tu clave tiene pleno acceso y privilegios para interactuar con la API, y cada petición cuenta para la facturación de tu cuenta.

Llamada a la API

Una llamada de ejemplo utilizando su clave API se vería así:

Copy
Copied
curl --request POST \
  --url https://api.khipu.com/target-resource \
  --header 'x-api-key: <valor de su clave Api asignada>' \
  --header 'Content-type: application/json'
  --data-raw '{
    "RequestData": {
      <payload>
    }
  }'