keycloak-sso-lib

v1.1.0

Published

3 years ago

Repositorio para la librería del Single Sign On implementada con keycloak

Downloads

0High
0Medium
0Low

dcelis

Keycloak SSO lib

keycloak SSO lib es una librería desarrollada con el objetivo de distribuir los métodos usados para facilitar la integración y conexión del Single Sign On (SSO) con las diferentes aplicaciones desarrolladas para Comfenalco Antioquia.

Contenido

Prerrequisitos

Keycloak SSO lib requiere Node.js v16.4.2 o superior.
Si estás desarrollando un proyecto nuevo, debes crear primero un directorio (carpeta) del proyecto, y en el interior de este, debes ejecutar el siguiente comando para crear el archivo package.json:

npm init

Agregar la siguiente linea de texto en el archivo hosts de nuestro dispositivo:

192.168.1.95	gitlab.comfenalcoantioquia.com

Nota: La ruta donde esta ubicado el archivo hosts en windows es la siguiente: C:\Windows\System32\drivers\etc

En la raíz del proyecto, debes crear un archivo llamado .npmrc, el contenido de este archivo es el siguiente:

@soter:registry=http://gitlab.comfenalcoantioquia.com/api/v4/packages/npm/
//gitlab.comfenalcoantioquia.com/api/v4/packages/npm/:_authToken=<NPM_TOKEN>

Nota: Debes solicitar el token de autenticidad (NPM_TOKEN) a la persona encargada de Comfenalco y reemplazarlo en el archivo .npmrc

Instalación

Este es un módulo de JavaScript disponible a través de GitLab Package Registry. La instalación se realiza con el siguiente comando:

npm install @soter/keycloak-sso-lib

Implementación

En el interior de la carpeta public del proyecto, crear una nueva carpeta llamada soter y en el interior de esta carpeta, crear dos archivos llamados client.json y silent-check-sso.html. Estos son los archivos base para permitir la conexión con la librería.

public dir

Nota: Si no posees una carpeta public, debes crearla en la raíz del proyecto y seguir los pasos anteriores.

El contenido del archivo client.json será proporcionado por la persona encargada de Comfenalco.

// Ejemplo de la estructura del archivo client.json (recuerda solicitar la información a la persona encargada)

{
  "realm": "nombre del realm",
  "auth-server-url": "url del servicio",
  "ssl-required": "external",
  "resource": "ID del cliente",
  "public-client": true,
  "confidential-port": 0
}

El archivo silent-check-sso.html debe contener en su interior el siguiente fragmento de código:

<html>
  <body>
    <script>
      parent.postMessage(location.href, location.origin);
    </script>
  </body>
</html>

En el archivo index.js ubicado en la carpeta src del proyecto, importar los módulos HttpService y UserService desde la librería @soter/keycloak-sso-lib.

import keycloak-sso-lib

Creamos una constante llamada renderApp y esta va a contener la aplicación que se quiere renderizar.

const renderApp

Desde el módulo UserService llamamos su método initKeycloak y le pasamos como parámetro la variable creada anteriormente (renderApp), este método nos permite generar la conexión con la librería, y desde el módulo HttpService llamamos su método configure, con este método permitimos que la librería valide si un usuario está autenticado y da manejo a las credenciales de autenticidad.

methods init lib

Finalmente, la estructura de nuestro index.js debe parecerse al siguiente fragmento de código:

// Ejemplo de la estructura del archivo index.js

import React from "react";
import ReactDOM from "react-dom";
import App from "./App";
import { HttpService, UserService } from "@soter/keycloak-sso-lib";

const renderApp = () =>
  ReactDOM.render(
    <React.StrictMode>
      <App />
    </React.StrictMode>,
    document.getElementById("root")
  );

UserService.initKeycloak(renderApp);
HttpService.configure();

Métodos

Los siguientes son los métodos proporcionados por la librería keycloak SSO lib. Como paso inicial, para hacer uso de ellos debemos importar el módulo UserService desde la librería @soter/keycloak-sso-lib, en la parte superior del archivo en el cual vamos a implementar alguno de los métodos, así:

import { UserService } from "@soter/keycloak-sso-lib";

getClientId

El método getClientId() es usado para obtener el ID del cliente (aplicación) que esta consumiendo el SSO.

// Ejemplo de implementación del método getClientId() visualizando el resultado a través de la consola

console.log("getClientId: ", UserService.getClientId());
// El output es: el ID del cliente (aplicación)

createAccount

El método createAccount(uri, clientId) es usado para crear una cuenta. Este método recibe como parámetros obligatorios la variable uri en la cual debemos especificar la ruta a la cual queremos redireccionar al usuario después de crear la cuenta y la variable clientId que representa el ID del cliente (aplicación).

// Ejemplo de implementación del método createAccount(uri, clientId) en un botón (la uri para este ejemplo es el localhost en el puerto 3000 que es donde se ejecutan por default las aplicaciones de React en ambiente local)

// Primero creamos una constante que contenga la uri a la cual debemos redireccionar
const uri = "http://localhost:3000";

// Luego debemos crear una constante con la información obtenida del método getClientId()
const clientId = UserService.getClientId();

// Uso del método createAccount con sus respectivos parámetros
<button className="btn btn-success" onClick={() => UserService.createAccount(uri, clientId)} >
  Crear cuenta
</button>

doLogin

El método doLogin(uri, clientId) es usado para iniciar sesión. Este método recibe como parámetros obligatorios la variable uri en la cual debemos especificar la ruta a la cual queremos redireccionar al usuario después de iniciar sesión y la variable clientId que representa el ID del cliente (aplicación).

// Ejemplo de implementación del método doLogin(uri, clientId) en un botón (la uri para este ejemplo es el localhost en el puerto 3000 que es donde se ejecutan por default las aplicaciones de React en ambiente local)

// Primero creamos una constante que contenga la uri a la cual debemos redireccionar
const uri = "http://localhost:3000";

// Luego debemos crear una constante con la información obtenida del método getClientId()
const clientId = UserService.getClientId();

// Uso del método doLogin con sus respectivos parámetros
<button className="btn btn-success" onClick={() => UserService.doLogin(uri, clientId)} >
  Iniciar sesión
</button>

doLogout

El método doLogout(uri) es usado para cerrar sesión. Este método recibe como parámetro obligatorio la variable uri en la cual debemos especificar la ruta a la cual queremos redireccionar al usuario después de cerrar sesión.

// Ejemplo de implementación del método doLogout(uri) en un botón (la uri para este ejemplo es el localhost en el puerto 3000 que es donde se ejecutan por default las aplicaciones de React en ambiente local)

// Primero creamos una constante que contenga la uri a la cual debemos redireccionar
const uri = "http://localhost:3000";

// Uso del método doLogout con sus respectivo parámetro
<button className="btn btn-success" onClick={() => UserService.doLogout(uri)} >
  Cerrar sesión
</button>

getToken

El método getToken() es usado para obtener el token de un usuario.

// Ejemplo de implementación del método getToken() visualizando el resultado a través de la consola

console.log("getToken: ", UserService.getToken());
// El output es: el token del usuario

isLoggedIn

El método isLoggedIn() es usado para verificar si un usuario está autenticado.

// Ejemplo de implementación del método isLoggedIn() visualizando el resultado a través de la consola

console.log("isLoggedIn: ", UserService.isLoggedIn());
// El output es: un boolean (true indicando que el usuario está autenticado o false cuando no está autenticado)

getUsername

El método getUsername() es usado para obtener el username del usuario.

// Ejemplo de implementación del método getUsername() visualizando el resultado a través de la consola

console.log("getUsername: ", UserService.getUsername());
// El output es: el username del usuario

getUserDocNumber

El método getUserDocNumber() es usado para obtener el número de documento del usuario.

// Ejemplo de implementación del método getUserDocNumber() visualizando el resultado a través de la consola

console.log("getUserDocNumber: ", UserService.getUserDocNumber());
// El output es: el número de documento del usuario

getUserDocType

El método getUserDocType() es usado para obtener el tipo de documento del usuario.

// Ejemplo de implementación del método getUserDocType() visualizando el resultado a través de la consola

console.log("getUserDocType: ", UserService.getUserDocType());
// El output es: el tipo de documento del usuario

getUserFullName

El método getUserFullName() es usado para obtener el nombre completo del usuario.

// Ejemplo de implementación del método getUserFullName() visualizando el resultado a través de la consola

console.log("getUserFullName: ", UserService.getUserFullName());
// El output es: el nombre completo del usuario

getUserRoles

El método getUserRoles() es usado para obtener la lista de roles del usuario.

// Ejemplo de implementación del método getUserRoles() visualizando el resultado a través de la consola

console.log("getUserRoles: ", UserService.getUserRoles());
// El output es: un array listando los roles del usuario

hasRole

El método hasRole([roles]) es usado para validar si un usuario tiene un rol específico. Lo podemos usar por ejemplo para validar si un usuario cuenta con las credenciales necesarias para acceder a páginas que tienen ciertas restricciones como las páginas de acceso administrativo. Este método recibe como parámetro obligatorio el array [roles] en el cual podemos especificar uno o varios roles, para validar si el usuario posee al menos uno de los roles del array.

// Ejemplo1 de implementación del método hasRole([roles]) visualizando el resultado a través de la consola (el array de roles para este ejemplo tiene un único rol especificado en string)

console.log("hasRole: ", UserService.hasRole(["user-role"]));
// El output es: un boolean (true indicando que el usuario posee al menos uno de los roles del array o false cuando no posee ninguno)


// Ejemplo2 de implementación del método hasRole([roles]) visualizando el resultado a través de la consola (el array de roles para este ejemplo tiene dos roles especificados en string)

console.log("hasRole: ", UserService.hasRole(["user-role", "admin-role"]));
// El output es: un boolean (true indicando que el usuario posee al menos uno de los roles del array o false cuando no posee ninguno)