Guía de Instalación – 4Identity Server

1. Visión general

El objetivo de este documento es describir el procedimiento de instalación y configuración de la solución 4Identity de Bit4id, utilizada para procesos de firma digital y autenticación fuerte basada en certificados.

Arquitectura del sistema

Un escenario típico de 4Identity está compuesto por los siguientes elementos:

🖥️ Servidor de Aplicaciones

El servidor de aplicaciones aloja las aplicaciones web del cliente que integran la funcionalidad de 4Identity. Estas aplicaciones pueden ser de dos tipos:

Aplicación de firma
Permite al usuario acceder a documentos (por ejemplo, PDF) y ejecutar el proceso de firma digital mediante la integración con el SDK de 4Identity.
Una vez firmado, el documento puede visualizarse con cualquier lector de PDF estándar.
ℹ️ Nota: 4Identity permite la firma digital de cualquier tipo de archivo, no solo PDF.
Aplicación de autenticación
Gestiona el proceso de autenticación del usuario mediante un mecanismo de doble factor:
- Algo que el usuario sabe (credenciales)
- Algo que el usuario posee (certificado digital)

🌐 4Identity Server (SmartEngine)

El componente SmartEngine, desplegado en el servidor web, es el núcleo de la solución.

Sus funciones principales son:

Establecer y gestionar el canal seguro entre el navegador del usuario y el 4Identity Client
Intervenir en el proceso de autenticación
Gestionar completamente el ciclo de vida del proceso de firma digital

Este componente actúa como intermediario entre la aplicación web y el entorno local del usuario.

💻 Cliente (4Identity Client)

El 4Identity Client se instala en el equipo del usuario final.

Desde el navegador, el usuario accede a la aplicación web, que a su vez interactúa con el cliente local para:

Ejecutar operaciones de firma digital
Realizar procesos de autenticación con certificados

Componentes de la instalación

La solución se compone de dos elementos principales:

4Identity Server: componente servidor que gestiona los servicios de firma y autenticación
4Identity Client: componente cliente instalado en los equipos de usuario

El servidor está diseñado para:

Gestionar múltiples servicios de firma
Atender solicitudes de distintos clientes
Asociar cada servicio a una licencia específica

⚠️ Importante:
Una licencia debe estar correctamente vinculada a un servicio de firma. En caso contrario, no será posible realizar firmas digitales.

Gestión de servicios y acceso

Cada servicio de firma configurado en 4Identity se expone a través de un puerto específico.

Esto permite:

Diferenciar distintos servicios o clientes
Gestionar múltiples configuraciones en un mismo servidor
Controlar el acceso a cada servicio de forma independiente

2. Requisitos previos (Onboarding)

Antes de comenzar con la instalación de 4Identity, verifique los siguientes puntos. Esto garantizará un despliegue correcto desde el primer intento.

✅ Paso 1: Accesos necesarios

Asegúrese de disponer de:

Acceso administrador al servidor donde se instalará 4Identity Server
Acceso a los equipos cliente donde se instalará 4Identity Client
Permisos para:
- Ejecutar instaladores
- Abrir puertos en firewall

🌐 Paso 2: Configuración de red

Valide los siguientes aspectos:

Puerto disponible para el servicio (por defecto: 8081)
Conectividad entre:
- Cliente ↔ Servidor
- Navegador ↔ SmartEngine
Resolución DNS correcta del dominio configurado

🔐 Paso 3: Licencia

Debe disponer de:

Archivo de licencia proporcionado por Namirial / Bit4id
Dominio configurado en la licencia

⚠️ Importante
El dominio de la licencia, la aplicación y el servicio deben coincidir.
Si no coinciden, el proceso de firma no funcionará.

💻 Paso 4: Descarga del software

Descargue los componentes necesarios según su entorno:

🖥️ 4Identity Server (Connector)

Seleccione el instalador correspondiente al sistema operativo del servidor:

🪟 Windows
👉 Descargar: 4Identity Connector Setup.zip
🐧 Linux
👉 Descargar: connector-2.4.4.tar.gz

ℹ️ El paquete Linux se distribuye como archivo .tar.gz

👤 4Identity Client

El 4Identity Client debe instalarse en cada equipo de usuario final que vaya a realizar operaciones de firma o autenticación.

⚠️ Importante
Existen diferentes versiones del 4Identity Client en función del entorno y la integración.
Para garantizar la compatibilidad, es necesario instalar la versión adecuada.

👉 Para obtener la versión correcta, contacte con el departamento técnico:
📧 soporte@namirial.com

🧩 Paso 5: Preparación de la aplicación

Antes de continuar, asegúrese de que:

La aplicación web:
- Puede acceder a documentos a firmar
- Está integrada con el SDK de 4Identity
Se utilizará HTTPS en entorno productivo
(Opcional) Se dispone de reverse proxy si se requiere unificar dominios

3. Instalación del servidor (4Identity Server)

En este apartado se describe la instalación del componente 4Identity Server (Connector), encargado de gestionar los servicios de firma y autenticación.

🖥️ Paso 1: Seleccionar entorno

Antes de comenzar, identifique el sistema operativo del servidor:

🐧 Linux
🪟 Windows

🐧 3.1. Instalación en Linux

📁 1. Crear directorio de instalación

mkdir /opt/bit4id

📦 2. Copiar el paquete descargado

Copiar el archivo del conector en la ruta /opt/:

cp connector.tar.gz /opt/

📂 3. Descomprimir el paquete

tar -xvzf connector.tar.gz -C /opt/bit4id

✅ Resultado esperado

El conector queda instalado en:

/opt/bit4id

🪟3.2. Instalación en Windows

▶️ 1. Ejecutar instalador

Ejecutar el archivo:

4IdentityConnectorSetup.exe

🧭 2. Seguir el asistente de instalación

Durante el proceso:

Hacer clic en Next
Seleccionar la carpeta de instalación (o dejar la ruta por defecto)
Hacer clic en Install
Finalizar con Finish

✅ Resultado esperado

El 4Identity Server queda instalado en el sistema y disponible para su configuración.

Ruta por defecto:

C:\Program Files (x86)\Bit4id\4Identity Connector\

⚠️ Importante

Tras la instalación, es necesario crear y configurar un servicio para habilitar la firma digital
La instalación por sí sola no activa el servicio de firma

👉 Continúe con el siguiente apartado: Configuración del servicio

4. Creación del servicio

Para poder utilizar 4Identity, es necesario crear al menos un servicio de firma, que será el encargado de procesar las solicitudes provenientes de la aplicación.

El procedimiento varía ligeramente en función del sistema operativo del servidor.

🐧 Linux

Paso 1: Acceder a la consola

Acceder a la ruta donde está instalado el conector:

cd /opt/bit4id/connector/bin

Paso 2: Crear el servicio

Ejecutar el siguiente comando:

./license utils add --name <<FRIENDLY_NAME>> --port <<SERVICE_LISTEN_PORT>> --license <<LICENSE_FILE>>

🪟 Windows

Paso 1: Acceder a la consola

Existen dos opciones:

Opción 1 (recomendada):

Ir a:
Inicio → Todos los programas → 4Identity Connector → Command Prompt

Opción 2 (manual):

Abrir una consola de Windows como administrador
Acceder a la ruta de instalación:

cd "C:\Program Files (x86)\Bit4id\4Identity Connector\bin"

Paso 2: Crear el servicio

Ejecutar el siguiente comando:

license utils add --name <<FRIENDLY_NAME>> --port <<SERVICE_LISTEN_PORT>> --license "<<LICENSE_FILE>>"

🧾 Parámetros del comando

Parámetro	Descripción	Ejemplo

Parámetro	Descripción	Ejemplo
`<<FRIENDLY_NAME>>`	Nombre identificador del servicio	`firma`
`<<SERVICE_LISTEN_PORT>>`	Puerto en el que el servicio escuchará	`8081`
`<<LICENSE_FILE>>`	Ruta completa del archivo de licencia	`/opt/licenses/licencia.dat`

🧪 Ejemplos de uso

Linux

./license utils add --name firma --port 8081 --license /opt/licenses/nombreENTIDAD.com

Windows

license utils add --name firma --port 8081 --license "C:\licenses\nombreENTIDAD.com"

✅ Resultado esperado

Si la ejecución es correcta, se mostrará una salida similar a:

Generating SK...
SK Generated...

Installing service...
Service installed

Starting service...
Service started

⚠️ Importante

El servicio se inicia automáticamente tras su creación
Se generará un identificador interno (SK) necesario para la configuración
Es obligatorio configurar el servicio antes de utilizarlo

El sistema indicará las rutas a configurar, por ejemplo:

/opt/bit4id/connector/etc/connector/<FRIENDLY_NAME>/config.ini
/opt/bit4id/connector/etc/smartengine/<FRIENDLY_NAME>/certificates

5. Configuración del servicio

Una vez creado el servicio, es necesario configurarlo correctamente para habilitar los procesos de firma digital y autenticación.

🗂️ Paso 1: Acceder al directorio del servicio

Diríjase a la carpeta correspondiente al servicio creado:

🐧 Linux

/opt/bit4id/connector/etc/connector/<<FRIENDLY_NAME>>/

🪟 Windows

C:\Program Files (x86)\Bit4id\4Identity Connector\etc\connector\<<FRIENDLY_NAME>>\

⚙️ Paso 2: Editar el archivo `config.ini`

Abra el archivo:

config.ini

Y configure los siguientes parámetros:

[main]
debug=1
sk=XXXXX

[urls]
authentication=https://midominio.com:8081/smartengine/authenticate
connector=https://midominio.com:8081/smartengine

🧾 Descripción de parámetros

Parámetro	Descripción	Ejemplo

Parámetro	Descripción	Ejemplo
`debug`	Activa el logging detallado (solo recomendado en pruebas)	`1`
`sk`	Clave generada automáticamente al crear el servicio (no modificar)	`WJD1oFmjYlV...`
`authentication`	URL utilizada en el proceso de autenticación	`https://midominio.com:8081/smartengine/authenticate`
`connector`	URL utilizada en el proceso de firma	`https://midominio.com:8081/smartengine`

⚠️ Configuración crítica (muy importante)

Para que el sistema funcione correctamente:

El dominio debe ser exactamente el mismo en:
- La aplicación web
- El servicio 4Identity
- La licencia

👉 Ejemplo correcto:

https://app.midominio.com
https://app.midominio.com:8081

👉 Ejemplo incorrecto:

https://app.midominio.com
https://firma.midominio.com   ❌

🌐 Uso de reverse proxy (recomendado)

En muchos escenarios, es necesario utilizar un reverse proxy para:

Unificar el dominio
Evitar problemas de cookies y sesión
Cumplir con los requisitos de licenciamiento

Ejemplo típico:

https://app.midominio.com/smartengine → redirige a http://localhost:8081/smartengine

❗ Errores comunes

❌ Dominio distinto entre aplicación y servicio
❌ Puerto bloqueado o no accesible
❌ Modificar el valor sk manualmente
❌ No usar HTTPS en entorno productivo
❌ No reiniciar el servicio tras cambios

🔄 Aplicar cambios

Después de modificar el archivo config.ini, es obligatorio reiniciar el servicio:

license utils reload --name <<FRIENDLY_NAME>>

6. Publicación del servicio

Una vez configurado el servicio, es necesario exponerlo correctamente para que pueda ser consumido por la aplicación web y los usuarios finales.

🎯 Objetivo

Permitir el acceso al servicio SmartEngine mediante una URL accesible desde el navegador, cumpliendo los requisitos de:

Dominio único
Acceso por HTTP/HTTPS
Compatibilidad con la licencia

🌐 Escenario típico

Supongamos:

Aplicación web:
https://app.midominio.com
Servicio 4Identity (SmartEngine):
http://localhost:8081

👉 El objetivo es exponer el servicio como:

https://app.midominio.com/smartengine

⚠️ Recomendación

Se recomienda utilizar un reverse proxy para:

Unificar el dominio
Evitar problemas de cookies/sesión
Simplificar la configuración del cliente

🔧 Ejemplo con NGINX

server {
    listen 443 ssl;
    server_name app.midominio.com;

    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;

    location /smartengine/ {
        proxy_pass http://localhost:8081/smartengine/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

🔧 Ejemplo con Apache

<VirtualHost *:443>
    ServerName app.midominio.com

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/cert.pem
    SSLCertificateKeyFile /etc/ssl/private/key.pem

    ProxyPreserveHost On
    ProxyPass /smartengine http://localhost:8081/smartengine
    ProxyPassReverse /smartengine http://localhost:8081/smartengine
</VirtualHost>

🔧 Ejemplo con IIS (Windows Server)

Requisitos

IIS instalado
Módulo URL Rewrite
Módulo Application Request Routing (ARR)

Configuración

Abrir IIS Manager
Seleccionar el sitio web (ej: app.midominio.com)
Ir a URL Rewrite
Crear una nueva regla → Reverse Proxy

Regla de reescritura (web.config)

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="SmartEngine Proxy" stopProcessing="true">
          <match url="^smartengine/(.*)" />
          <action type="Rewrite" url="http://localhost:8081/smartengine/{R:1}" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

✅ Resultado esperado

El servicio será accesible desde:

https://app.midominio.com/smartengine

🔄 Validación del servicio publicado

Validar el correcto funcionamiento accediendo a las siguientes URLs:

https://app.midominio.com/smartengine/bit4id-sign.min.js
https://app.midominio.com/smartengine/htdocs/test/test.pdf
https://app.midominio.com/smartengine/test-sign

⚠️ Importante (licencia)

La validación debe realizarse utilizando el dominio licenciado.

Si se accede mediante IP:

http://ip:puerto/smartengine/test-sign

La página puede cargar
Pero el botón de firma no se activará
La firma fallará, ya que la licencia está asociada al dominio

🔐 Consideraciones de seguridad

Usar siempre HTTPS en producción
Configurar correctamente los certificados SSL
Limitar accesos si es necesario (IP, firewall, etc.)

⚠️ Errores comunes

❌ No usar el mismo dominio que la aplicación
❌ No redirigir correctamente /smartengine
❌ Problemas de CORS o cookies por dominios distintos
❌ Proxy mal configurado (headers faltantes)

📌 Relación con config.ini

Las URLs definidas en config.ini deben coincidir con la URL publicada:

[urls]
authentication=https://app.midominio.com/smartengine/authenticate
connector=https://app.midominio.com/smartengine

7. Administración de servicios

Una vez creado y configurado un servicio de 4Identity, es posible administrarlo mediante comandos desde el servidor.

Estas operaciones permiten:

Consultar servicios activos
Ver licencias cargadas
Reiniciar servicios
Eliminar servicios

📋 7.1 Listado de servicios

Permite visualizar todos los servicios configurados en el servidor.

🐧 Linux

./license utils list-services

🪟 Windows

license utils list-services

✅ Resultado esperado

Se mostrará una tabla con los servicios disponibles:

| FRIENDLY NAME | SERVICE NAME            | PORT | STATUS  |
|---------------|--------------------------|------|---------|
| devel         | bit4-devel-connector     | 8081 | running |
| test          | bit4-test-connector      | 8082 | running |
| local         | bit4-localhost-connector | 8083 | stopped |

🔎 Interpretación

FRIENDLY NAME → Nombre definido al crear el servicio
SERVICE NAME → Nombre interno del sistema
PORT → Puerto asignado
STATUS → Estado del servicio (running / stopped)

🔐 7.2 Listado de licencias

Permite visualizar las licencias cargadas en el sistema.

🐧 Linux

./license utils list-licenses

🪟 Windows

license utils list-licenses

✅ Resultado esperado

*** dominioENTIDAD.com ***
start date : 18/03/2015
end date   : 18/03/2018

*** devel.connector.com ***
start date : 10/03/2015
end date   : 10/03/2018

🔎 Interpretación

Dominio asociado a la licencia
Fecha de inicio y expiración
Permite verificar rápidamente si una licencia está vigente

🔄 7.3 Recarga de servicios

Permite reiniciar un servicio ya existente, aplicando cambios de configuración (por ejemplo, en config.ini).

🐧 Linux

./license utils reload --name <<FRIENDLY_NAME>>

🪟 Windows

license utils reload --name <<FRIENDLY_NAME>>

Guía de Instalación – 4Identity Server

1. Visión general

Arquitectura del sistema

🖥️ Servidor de Aplicaciones

🌐 4Identity Server (SmartEngine)

💻 Cliente (4Identity Client)

Componentes de la instalación

Gestión de servicios y acceso

2. Requisitos previos (Onboarding)

✅ Paso 1: Accesos necesarios

🌐 Paso 2: Configuración de red

🔐 Paso 3: Licencia

💻 Paso 4: Descarga del software

🖥️ 4Identity Server (Connector)

👤 4Identity Client

🧩 Paso 5: Preparación de la aplicación

3. Instalación del servidor (4Identity Server)

🖥️ Paso 1: Seleccionar entorno

🐧 3.1. Instalación en Linux

📁 1. Crear directorio de instalación

📦 2. Copiar el paquete descargado

📂 3. Descomprimir el paquete

✅ Resultado esperado

🪟3.2. Instalación en Windows

▶️ 1. Ejecutar instalador

🧭 2. Seguir el asistente de instalación

✅ Resultado esperado

⚠️ Importante

4. Creación del servicio

🐧 Linux

Paso 1: Acceder a la consola

Paso 2: Crear el servicio

🪟 Windows

Paso 1: Acceder a la consola

Paso 2: Crear el servicio

🧾 Parámetros del comando

🧪 Ejemplos de uso

Linux

Windows

✅ Resultado esperado

⚠️ Importante

5. Configuración del servicio

🗂️ Paso 1: Acceder al directorio del servicio

🐧 Linux

🪟 Windows

⚙️ Paso 2: Editar el archivo config.ini

🧾 Descripción de parámetros

⚠️ Configuración crítica (muy importante)

🌐 Uso de reverse proxy (recomendado)

❗ Errores comunes

🔄 Aplicar cambios

6. Publicación del servicio

🎯 Objetivo

🌐 Escenario típico

⚠️ Recomendación

🔧 Ejemplo con NGINX

🔧 Ejemplo con Apache

🔧 Ejemplo con IIS (Windows Server)

Requisitos

Configuración

Regla de reescritura (web.config)

✅ Resultado esperado

🔄 Validación del servicio publicado

⚠️ Importante (licencia)

🔐 Consideraciones de seguridad

⚠️ Errores comunes

📌 Relación con config.ini

7. Administración de servicios

📋 7.1 Listado de servicios

🐧 Linux

🪟 Windows

✅ Resultado esperado

🔎 Interpretación

🔐 7.2 Listado de licencias

🐧 Linux

🪟 Windows

✅ Resultado esperado

🔎 Interpretación

🔄 7.3 Recarga de servicios

🐧 Linux

⚙️ Paso 2: Editar el archivo `config.ini`