keycloak-sso-lib v1.1.0
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.comNota: 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-libImplementació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.
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.
Creamos una constante llamada renderApp y esta va a contener la aplicación que se quiere renderizar.
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.
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 usuarioisLoggedIn
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 usuariogetUserDocNumber
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 usuariogetUserDocType
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 usuariogetUserFullName
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 usuariogetUserRoles
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 usuariohasRole
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)Licencia
2 years ago