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.

🔐 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

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

{
  "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

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:

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 api (dos "scope" separados por un espacio).
• state y nonce son valores opcionales, pero recomendados para mayor seguridad. De enviar nonce , éste será devuelto en un claim del JWT.
• 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:

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

{
  "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_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:

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

Consulte la sección "API Open Data" 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:

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.

Compatibilidad con PKCE

Nuestro servidor de autenticación es compatible con Proof Key for Code Exchange (PKCE), una extensión del flujo de código de autorización OAuth 2.0 diseñada para mejorar la seguridad de los clientes públicos, como las aplicaciones móviles o de una sola página. PKCE mitiga el riesgo de interceptación del código de autorización al exigir al cliente que genere un secreto aleatorio, conocido como verificador de código, antes de iniciar la solicitud de autorización. Luego, el cliente convierte este verificador de código en un hash (usando SHA-256, por ejemplo) para crear un desafío de código, que se envía al servidor de autorización junto con la solicitud de autorización. Al recibir el código de autorización, el cliente debe enviar el verificador de código original al endpoint /token. El servidor verifica el desafío de código con el verificador de código antes de emitir el token de acceso. Para usar PKCE en el flujo de código de autorización, asegúrese de que su cliente genere un verificador de código, cree un desafío de código e incluya el desafío de código en la solicitud de autorización inicial (usando los parámetros code_challenge y code_challenge_method). Luego se debe enviar el verificador de código (parámetro code_verifier) al intercambiar el código de autorización por un token de acceso.

Errores en flujo de código de autorización

Si ocurre un error durante el flujo de autenticación en relación a los parámetros enviados al endpoint /authorization, el navegador del usuario será redirigido al valor entregado en el parámetro redirect_uri (desde que exista y sea válido) con detalles sobre el error en los parámetros de la cadena de consulta. Su servidor backend puede detectar la existencia de estos parámetros para realizar las correcciones pertinentes o entregarle mejor información al usuario. Esta es la estructura de los parámetros de error:

• error_code : Código interno para clasificar el error. Ver la tabla a continuación.
• error_type : Categoría asociada al código de error. Indica si es posible reiniciar el flujo o se debe realizar algún ajuste en la petición.
• error_description : Mensaje descriptivo sobre el error.
• state : Valor del parámetro state , desde que haya sido enviado en la solicitud original.

🔑 Clave API

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.

Llamada a la API

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

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>
    }
  }'