libcdm v1.0.9

SDK CDM libcdm

Este SDK proporciona una forma sencilla de integrar el inicio de sesión con Ciudadania Digital Misionera en tu aplicación. Además, te permite implementar métodos de autenticación facial y OTP para proteger las rutas de tu aplicación.

Instalación

Para instalar el SDK, primero debes agregarlo a tu proyecto como una dependencia. Puedes hacerlo a través de tu gestor de paquetes favorito:

npm install libcdm

Uso

Para utilizar el SDK, debes de tener instalado un gestor de cookies, en el caso de Express.js por ejemplo podemos usar cookie-parser como en el ejemplo a continuacion. Luego para empezar a usar el SDK debes inicializarlo con tus credenciales de: clientId, clientSecret, redirectUri, apiKey(opcional). El valor api es un objeto que contiene dos valores: otp, facetec. Ambos opcionales

Ejemplo con Express.js, usando un middleware global:

const express = require('express');
const cookieparser = require('cookie-parser'); // IMPORTATE: un gestor de cookies
const libcdm = require('libcdm')

class Server {
    constructor(){
        this.app = express();
        this.middleware();
        this.routs();
    }

    middleware(){     
        this.app.use(cookieparser());
        // incializa la libreria como middleware global
        this.app.use(libcdm.inicializarCDM({
            clientId: process.env.clientId,
            clientSecret: process.env.clientSecret,
            redirectUri:process.env.redirectUri,
            apiKey:{
               otp:process.env.apiKeyOtp,
               facetec:process.env.apiKeyFacetec,
           }
        }));
    }
    routs(){
        this.app.use('/', require('../tuRuta'));
    }
    listen(){
         this.app.listen(this.port,() =>{
             console.log('Servidor corriendo en puerto', this.port);
         });       
    }
}

Una vez que has inicializado el SDK, puedes utilizar los middlewares proporcionados para autenticar a un usuario:

Ejemplo de rutas para login:

const { Router } = require('express');
const miControlador = require('../controllers/miControlador');
const libcdm = require('libcdm')
const router = Router();

// ruta de login (se encarga de iniciar el proceso de login)
// el middleware de autoriza redirige al usuario a la pantalla de autenticacion del sdk
router.get('/login', [libcdm.autoriza],miControlador.login);

// ruta de callback, en esta ruta vendrán los datos del login (perfil del usuario) luego de completar la validacion.
// el middleware de callback obtiene los datos enviados luego de la autenticion
router.get('/callback', [libcdm.callback],miControlador.callback);


module.exports = router;

Para iniciar realizar un inicio de session debes añadir el login y el callback a tu desarrollo importando el SDK y del mismo obtener los middlewares de: autoriza (encargada del login) y callback (encargada de la respuesta de las validaciones)

Para obtener los datos que retorna el middleware podras acceder a ellos en un objeto declarado en el request (req.cdm.data).

Ejemplo para obtener el perfil del ciudadano luego de autenticarse

// controlador de callback
const callback = async (req, res) =>{
    // En el request viene la propiedad cdm que es un objeto: req.cdm
    // Para obtener los datos del perfil obtenidos luego de que el usuario se autentica se busca en el objeto req.cdm.data la propiedad (getPerfil)
    let idDelCiudadano = req.cdm.data.getPerfil.id // retorna el id del perfil
    let datosDelPerfil = req.cdm.data.getPerfil.data // retorna un objeto con la informacion del usuario
    let origenUri = req.cdm.data.origenUri // retorna la ruta desde donde se realizo la peticion de inicio de session

    return res.redirec(origenUri)  // vuelvo a la ruta desde donde se disparo el inicio de session.
}

Middlewares

IMPORTANTE: Siempre que llames a alguno de estos middlewares el valor que retorne este sera cargado en el objeto req.cdm.data seguido del nombre del middleware ej: req.cdm.data.getPerfil

Ademas de tener el middleware de autoriza y callback que son esenciales para un funcionamento correcto, el SDK proporciona otros middlewares para proteger tus rutas mediante OTP (One time password) y mediante la validacion facial. Estos metodos el ciudadano los debe tener habilitados para poder usarlos. Para saber si el ciudadano los tiene habilitados o no, hace falta verificar el perfil del mismo, este contiene los datos de OTP y facetec (validacion Facial).

Ejemplo para saber si tiene habilitado los metodos de validacion

    // Si OTPDelCiudadano es = a "S" lo tiene habilitado
    let OTPDelCiudadano = req.cdm.data.getPerfil.data.validacionOTP
    // Si validacionVidaCiudadano es != "N" lo tiene habilitado 
    let validacionVidaCiudadano = req.cdm.data.getPerfil.data.validacionVida

Es importante que verifiques que el ciudadano tenga estos metodos, por el contrario dara un error. Para volver a obtener los datos del ciudadano autenticado en cualquier ruta fura del callback que ya los devuelve al terminar de hacer un login, puede usar el middleware verificaSesionToken junto al de getPerfil, el primero es muy importante, el mismo verificara que el token obtenido en el al iniciar una session siga siendo valido, y el middleware getPerfil obtendra los datos del perfil del usuario.

Si el usuario se dirige a una cualquier ruta que tenga el middleware de verificaSesionToken y no se encuentra autenticado, automaticamente se le redirige a la ruta de autenticacion de del sdk y al termina la validacion vuelve a la ruta desde donde fue llamado, ej: /rutaProtegidaOTP

Ejemplo de ruta para obtener perfil del usuario

// el middleware verificaSesionToken se encarga de verificar el estado de la session 
// el middleware getPerfil obtiene el perfil y lo almacena en req.cdm.data.getPerfil
router.get('/miPerfil',[libcdm.verificaSesionToken,libcdm.getPerfil]miControlador.perfilDelCiudadano);

El getPerfil va a cargar el perfil del ciudadano en el req.cdm.data.getPerfil

Ejemplo de respuesta de get perfil en req.cdm.data.getPerfil

status: 200,
  data: {
    id: '123456', // id del ciudadano
    data: { // obj con los datos del ciudadano 
      nombre: 'test', 
      apellido: 'test', 
      validacionVida: 'N',
      email: 'test@test.com',
      validacionOTP: 'S',
    }
  },
  msg: 'ok'

Middlewares de validacion Facial o por OTP

IMPORTANTE: Para usar estos middlewares es necesario que tengas tus api key cargadas en el middleware global.

Estos middlewares generan una solictud(identificador unico de la validacion) la cual está anclada al ciudadano que la genero y al resultado de la validacion usada, ejemplo: OTP. Esa solicitud será devuelta en el req.cdm.data para que la puedas relacionarla con tus usuarios.

Recordatorio: Siempre que llames a uno de estos middleware el valor que retorne este será cargado en el objeto req.cdm.data seguido del nombre del middleware ej: req.cdm.data.validacionOTP

Ejemplo de uso de middlewares

// el middleware verificaSesionToken se encarga de verificar el estado de la session 

// el middleware validacionOTP le redireccionara al usuario a una vista para que valide su otp. Este middleware requiere 2 parametros "rutaError" y "ventanaVida"
router.get('/rutaProtegidaOTP',[libcdm.verificaSesionToken,libcdm.validacionOTP({rutaError:"/error",ventanaVida:true})],miControlador.rutaProtegidaOtp);


// el middleware validacionFacial le redireccionara al usuario a una vista para que realiza su validacion facial. Este middleware requiere 2 parametros "rutaError" y "ventanaVida"
router.get('/rutaProtegidaFacial',[libcdm.verificaSesionToken,libcdm.validacionFacial({rutaError:"/error",ventanaVida:false})],miControlador.rutaProtegidaFacial);

// el middleware analizaSolicitud se encarga de analizar la solicitud generada al momento de realizar un tipo de validacion sea OTP o Facial, y cargar en el req.cdm.data.analizaSolicitud los datos de la misma, este middleware se debe colocar en la vista de error para analizar que salio mal en esa solicitud
router.get('/error',[libcdm.verificaSesionToken, libcdm.analizaSolicitud],miControlador.error);

Estos middlewares se encargan de redireccionar al usuario a una vista que le pedira completar su validacion. Los mismos requieren dos parametros:

• rutaError: En el cual espera un string de tu ruta de error a la cual será redireccionada cuando surga un problema al realizar el metodo de validacion.

• ventanaVida: La ventana de vida es un booleano que permite al desarrollador darle un tiempo de vida a la autenticacion del usuario por 30 minutos. Ejemplo: El usuario ingresa su OTP y se valida, si el usuario va a otra ruta y la ventanaVida esta en true no tendra que validar su OTP si ya lo hizo anteriormente y no pasaron 30 minutos desde que lo realizó, por el contrario le volverá a pedir la validacion (esto está ligado al metodo de autenticacion utilizado: facial o OTP , son independientes uno del otro). En cambio si la ventanaVida está en false, siempre que el usuario entre a esa ruta le pedira que se valide.

Al completar la validacion los middlewares cargaran en el req.cdm.data.(nombre del middleware, ej: validacionFacial) los datos de la solicitud de validacion, como fue el proceso y el estado de la misma.

Ejemplo de una respuesta de solicitud

// los datos se obtienen del req.cdm.data en este ejemplo el middleware de validacion facial seria : req.cdm.data.validacionFacial.data

    solicitud: '123456', // id de la solicitud
    resultadoProceso: 'correcto', // resultado del proceso
    resultadoMensaje: '', // mensaje del resultado
    estado: 'finalizado', // estado de la solicitud 
    idColeccion: '123456' // id del ciudadano que emitio esa solicitud
 

Middleware para iniciar tu desarrollo desde Ciudadania Digital Misionera

Este middleware va a permitir a los usuarios que puedan iniciar session en tu desarrollo desde la aplicacion Ciudadania Digital Misionera, en tu ruta tienes que agregar el middleware de ingresoDesdeCdm este detectara si el ingreso a tu desarrollo es desde Ciudadania Digital Misionera y autenticara al usuario, los datos del mismo vendran en tu ruta de callback para que hagas con ellos lo que necesites.

Ejemplo de la ruta habilitada para el inicio desde CDM

// el middleware verificaSesionToken se encarga de verificar el estado de la session 

// En la ruta de inicio agrego el middleware que verifique si vengo desde CDM 
router.get('/',[libcdm.ingresoDesdeCdm],inicioController.getInicio);

Middleware Cerrar session

Para cerrar la session de un ciudadano existe el middleware cerrarSesion, este al finalizar devolvera un ok en el req.cdm.data.cerrarSesion si el proceso salio correctamente.

Ejemplo de una ruta para cerrar session

// el middleware verificaSesionToken se encarga de verificar el estado de la session 

// el middleware cerrarSesion cerraá la session del usuario y devolvera el resultado del proceso en req.cdm.data.cerrarSesion
router.get('/cerrarSession',[libcdm.verificaSesionToken,libcdm.cerrarSesion],miControlador.cerrarSession);

Ejemplo de una respuesta a cerrar session en req.cdm.data.cerrarSession

    {
        status: 200, 
        data: {}, 
        msg: 'ok'
    }    

Valores del req.cdm

En el req.cdm pueden existir estos valores:

• idColecion: Este valor es igual al id del ciudadano que a iniciado session, esto no significa que su sesion o token esten activos, por eso siempre debes consumir el middleware de verificaSesionToken si quieres validar el estado de autenticacion de tu usuario. Este middleware irá automaticamente a iniciar session de nuevo si el usuario no llega a estar autenticado o ocurrio un error al verificar su inicio de session.

• status: Este es el status de la ultima solicitud realizada, un 200 si salio todo correctamente o un 500 o 400, si existieron problemas al momento de realizarla

• msg: El msg contiene el mensaje de la ultima solicitud realizada.

• data: La propiedad data es un objeto que contiene el nombre de los diferentes middlewares que fuiste añadiendo a tu ruta, ejemplo: getPerfil, esté internamente tendra a su vez las propiedades: status, msg, data.

Ejemplo de ruta

    // ruta de ejemplo con middlewares verificaSesionToken, getPerfil y validacionOTP
    router.get('/miRuta',[libcdm.verificaSesionToken,libcdm.getPerfil,libcdm.validacionOTP({rutaError:"/error",ventanaVida:true})],miCOntrolador.inicio);

Ejemplo de un objeto req.cdm despues de pasar por la ruta nombrada anteriormente

    req.cdm = {
        idColeccion: '123456', // id del ciudadano 
        status: 200, // status de la ultima solicitud realizada, en esté ejemplo es: validacionOTP 
        msg: 'ok', // msg de la ultima solicitud realizada, en esté ejemplo es: validacionOTP 
        data: {
          verificaSesionToken: { status: 200, data: [Object], msg: 'ok' }, // datos de la respuesta del middleware verificaSesionToken
          getPerfil: { status: 200, data: [Object], msg: 'ok' }, // datos de la respuesta del middleware getPerfil
          validacionOTP: { status: 200, msg: 'ok', data: [Object] } // datos de la respuesta del middleware validacionOTP
        }
    }