:= Identity Resolution
Identity Resolution es una aplicación que proporciona funciones para comparar nombres y direcciones proporcionados por el usuario con nombres y direcciones conocidos, y proporcionar una respuesta que indique si las comparaciones coinciden o no. Normalmente se utiliza cuando el nombre y la dirección del Acreedor proporcionados por un tercero son comparados por el Banco del Acreedor con el nombre y la dirección asociados a la Cuenta del Acreedor indicada, aunque puede utilizarse en cualquier situación en la que se necesite una comparación.
Funcionalidades
Comparison
Comparison es donde podemos tomar dos valores, un valor real conocido y un valor de comparación enviado por el usuario, y compararlos. Estos valores pueden ser el nombre de una persona o una dirección, y cada consulta de comparación puede contener una o más comparaciones de cada tipo. Se devuelve una respuesta que indica si la consulta en su conjunto coincide, incluyendo puntuaciones para cada comparación que muestran qué tan bien coinciden esas dos cosas.
Esta comparación se logra llamando a un producto de netowl llamado Namematcher. A pesar del nombre, este producto es capaz de comparar tipos de datos más allá de los nombres de personas, incluyendo direcciones, nombres de organizaciones, lugares y más.
Una sola consulta de comparación a Identity Resolution puede contener muchas comparaciones y, dependiendo del producto NetOwl utilizado, esto puede dividirse en muchas solicitudes de comparación de NetOwl.
Las consultas de comparación de IPF a Identity Resolution normalmente se realizarían usando la biblioteca de cliente, pero el transporte es basado en http y también podría ser un enfoque personalizado siempre que la consulta de comparación cumpla con la especificación del API.
Las consultas de comparación de Identity Resolution a NetOwl Namematcher también son http que hablan con la API de NetOwl.
Funcionalidad principal
Las comparaciones pueden realizarse en campos de diferentes tipos, por ejemplo el nombre de una persona o su dirección. Una sola consulta de comparación puede incluir cualquier número de comparaciones de cada tipo.
La implementación de la comparación se realiza utilizando NetOwl Namematcher, que dará una puntuación (0..1) para cada campo que se compare.
Se esperan umbrales para cada campo junto con los campos de la consulta de comparación, y si cualquiera de las puntuaciones de comparación para una sola consulta está por debajo del umbral, entonces la coincidencia de la comparación es falsa.
Comparaciones basadas en tablas
NetOwl admite tablas de datos para rendimiento, así como para agregar cosas como alias y reglas de coincidencia personalizadas. La API de Identity Resolution admite comparaciones basadas en tablas y no basadas en tablas. Esto se habilita/deshabilita estableciendo o no los campos "tableName" y "fieldName" como se ve en la documentación de Open API.
NOTA: Identity Resolution no maneja la creación o inserción de datos en tablas de NetOwl; esto debe ser gestionado por la implementación del lado del cliente.
Implementación de NetOwl
NetOwl Namematcher nos permite comparar un solo campo de un solo tipo en una sola solicitud y devuelve una puntuación entre 0 y 1 que indica cuán similares son esos valores, donde 1 es una coincidencia exacta y 0 no hay coincidencia.
Restricciones de licencia
La licencia actual nos restringe a NetOwl Namematcher, que solo admite una comparación de un solo campo a la vez por solicitud, y también nos restringe a comparaciones de texto latino.
Namematcher sí admite comparar un solo valor contra más de un valor real conocido, lo cual actualmente no usamos. Esto es potencialmente útil al admitir comparaciones de nombres para cuentas conjuntas donde solo se ha proporcionado un único nombre para el pago.
Client Library
El cliente de comparación envía consultas de comparación vía http a Identity Resolution y recibe respuestas de comparación, manejando el marshalling/unmarshalling de las cargas útiles json.
Los clientes podrían llamar a los endpoints http directamente, pero deberían preferir usar este cliente ya que abstrae y simplifica gran parte de la configuración requerida.
La biblioteca de cliente es configurable y, como mínimo, necesita saber cómo acceder a Identity Resolution para hacer consultas de comparación.
identity-resolution.comparison.http.client {
host = "localhost"
port = 8080
}TLS
One-way
Si cacerts de Java ya existe, es posible que solo necesite aplicar la siguiente configuración del cliente de comparación.
identity-resolution.comparison.http.client {
host = null
port = null
endpoint-url = "https://host:port/identity/compare"
}NOTA: host y port deben establecerse en null, y la ruta completa de comparación /identity/compare debe establecerse en endpoint-url
Alternativamente, necesitará un trust-store, y no necesitará sobrescribir endpoint-url.
identity-resolution.comparison.http.client {
host = "localhost"
port = 8443
ssl {
trust-store-location = "/absolute/path/to/trust-store.p12"
trust-store-password = "password"
trust-store-type = "PKCS12"
}
}Mutual
identity-resolution.comparison.http.client {
host = "localhost"
port = 8443
ssl {
trust-store-location = "/absolute/path/to/trust-store.p12"
trust-store-password = "password"
trust-store-type = "PKCS12"
key-store-location = "/absolute/path/to/key-store.p12"
key-store-password = "password"
key-store-type = "PKCS12"
key-password = "password"
}
}NOTA: Identity Resolution, o su ingress, también debe configurarse para aceptar Mutual TLS.
Metrics
Las siguientes métricas se exponen para la comparación de identidad.
| Key | Type | Description |
|---|---|---|
|
Counter |
Recuento del número de solicitudes de comparación recibidas a través del API. No cuenta el número de campos para comparación, por lo que una comparación de un Name y un Address se considera una sola solicitud. |
|
Counter |
Recuento del número de coincidencias de solicitudes de comparación. Una sola solicitud para comparar tanto un Name como un Address tendría una única respuesta indicando coincidencia o no. |
Estas métricas están habilitadas en el back-end (identity-resolution), pero en teoría también podrían funcionar del lado del cliente, cuando el cliente usa el comparison-client para comparaciones. Depend on com.iconsolutions.ipf.identityresolution:comparison-metrics junto con com.iconsolutions.ipf.identityresolution:comparison-client. La aplicación que use este cliente también deberá ser una aplicación Spring Boot, con micrometer y aop habilitados.
NetOwl
Comparison
NetOwl Namematcher se utiliza para cumplir la funcionalidad de comparación. La configuración mínima requerida para el conector es:
identity-resolution.comparison.netowl {
default.http.client {
host = "localhost"
port = 8080
}
table.http.client {
host = "localhost"
port = 8080
}
}Se espera que NetOwl Namematcher se despliegue dentro del mismo pod que Identity Resolution, en cuyo caso la configuración anterior puede no ser requerida ya que también es la predeterminada.
Manejo especial
La API de netowl actualmente no maneja comparaciones que solo contienen caracteres especiales. Por ejemplo, la siguiente solicitud fallaría en NetOwl:
{
"actual": {
"type": "FULL_ADDRESS",
"value": "10 Downing Street, SW1A 2AA"
},
"comparison": ".",
"minimumScoreToMatch": 0.75
}Para manejar esto filtramos cualquiera de estas comparaciones antes de enviar a NetOwl y en su lugar devolvemos una puntuación de 0.0.
Los caracteres especiales pueden configurarse proporcionando una lista de caracteres al parámetro de configuración identity-resolution.comparison.netowl.exclusion.special-characters. La lista predeterminada consiste en caracteres especiales del Latín básico:
identity-resolution.comparison.netowl.exclusion.special-characters =
[
"/", "\\", "!", "@", "#", "$", "%", "^", "&", "*", "(", ")", "\"", "{", "}", "_", "[", "]" ,"|", "?", "<", ">", ",", "."," "
]NOTA: Para agregar o eliminar elementos de la lista anterior, deberá volver a definir la lista completa con sus adiciones u omisiones, ya que no hay una forma simple de modificar una lista en HOCON.
TLS
One-way
Si cacerts de Java ya existe, es posible que solo necesite aplicar la siguiente configuración del cliente de comparación de NetOwl (usando el endpoint predeterminado como ejemplo).
identity-resolution.comparison.netowl.default.http.client {
host = null
port = null
endpoint-url = "https://host:port/api/v2/_compare"
}NOTA: host y port deben establecerse en null, y la ruta completa de comparación /api/v2/_compare debe establecerse en endpoint-url
Alternativamente, necesitará un trust-store, y no necesitará sobrescribir endpoint-url.
identity-resolution.comparison.netowl.default.http.client {
host = "localhost"
port = 8443
ssl {
trust-store-location = "/absolute/path/to/trust-store.p12"
trust-store-password = "password"
trust-store-type = "PKCS12"
}
}Mutual
identity-resolution.comparison.netowl.default.http.client {
host = "localhost"
port = 8443
ssl {
trust-store-location = "/absolute/path/to/trust-store.p12"
trust-store-password = "password"
trust-store-type = "PKCS12"
key-store-location = "/absolute/path/to/key-store.p12"
key-store-password = "password"
key-store-type = "PKCS12"
key-password = "password"
}
}NOTA: NetOwl Namematcher, o su ingress, también debe configurarse para aceptar Mutual TLS.
Documentación oficial
Una vez que NetOwl se haya iniciado, puede acceder a la documentación del producto visitando la URL de NetOwl en un navegador.
Por ejemplo, si se despliega localmente (usando local-e2e-test como ejemplo) entonces puede apuntar su navegador a localhost:8081/docs/index.html
Actuator
El módulo netowl-actuator está incluido en la aplicación identity-resolution y agrega un info contributor y un health indicator de Spring Boot al aplicativo.
Los componentes de actuator funcionan listos para usar con valores predeterminados, pero como mínimo, identity-resolution debe saber dónde encontrar NetOwl. Esta URL probablemente será la misma que la utilizada para el conector de comparación.
IMPORTANTE: Esta configuración debe proporcionarse si health y/o info están habilitados.
netowl {
base-url = "http://localhost:8080"
}| Property | Example | Description |
|---|---|---|
|
La URL base requerida para poder comunicarse con NetOwl. |
Info
El endpoint /actuator/info incluye los detalles del producto NetOwl (nombre y versión) si NetOwl es alcanzable. También incluye cualquier error con la conectividad hacia la aplicación NetOwl, incluyendo problemas específicos de NetOwl, como licencias y configuración.
El endpoint de info contendrá una sección netowl
{
"netowl": {
"error": "system is unlicensed",
"product": "NameMatcher",
"version": "4.9.11.0"
}
}Configuración
CONSEJO: Esta es la configuración predeterminada del info contributor; no necesita agregar explícitamente esta configuración a menos que necesite valores diferentes.
management.info.netowl {
enabled = true
timeout = "2S"
}| Property | Example | Description |
|---|---|---|
|
|
NetOwl info está habilitado de forma predeterminada, pero puede deshabilitarse con esta propiedad. Cuando está deshabilitado, los detalles del producto NetOwl no se incluyen en la info. |
|
|
El tiempo de espera predeterminado es de 2 segundos, que es la duración que esperaremos a que NetOwl responda al comprobar los detalles del producto. Si se excede el tiempo de espera, la info incluirá el nombre y la versión del producto NetOwl, pero se marcarán como |
Health
El endpoint /actuator/health incluye la misma información que proporciona el info contributor y también incluye la salud del producto NetOwl utilizado para comparaciones. El estado general de la aplicación indicará DOWN si NetOwl se considera DOWN. Para que NetOwl se considere UP debe responder a una solicitud /api/v2 con un estado 200 y los detalles del producto.
El endpoint de health contendrá una sección netowl
{
"netowl": {
"details": {
"error": "system is unlicensed",
"product": "NameMatcher",
"version": "4.9.11.0"
},
"status": "DOWN"
}
}Configuración
CONSEJO: Esta es la configuración predeterminada del health indicator; no necesita agregar explícitamente esta configuración a menos que necesite valores diferentes.
management.health.netowl {
enabled = true
timeout = "2S"
}| Property | Example | Description |
|---|---|---|
|
|
NetOwl health está habilitado de forma predeterminada, pero puede deshabilitarse con esta propiedad. Cuando está deshabilitado, no se considera el estado de NetOwl, y health indicará |
|
|
El tiempo de espera predeterminado es de 2 segundos, que es la duración que esperaremos a que NetOwl responda al comprobar el estado. Si se excede el tiempo de espera, NetOwl se considera |
Licencing
Las licencias son proporcionadas por NetOwl, y actualmente usamos una licencia de desarrollo para NetOwl Namematcher, que nos restringe a un solo hilo de comparación y tres instancias. La licencia de desarrollo actual se incluye con el módulo netowl-testcontainer para pruebas de integración.
{
"product": "NameMatcher",
"type": "Development",
"thread limit": 1,
"*": {
"lifespan": [
"2022-01-01 00:00Z",
"2023-01-01 00:00Z"
],
"features": [
"Latin"
]
},
"verification": 1778757171272520714
}La licencia debe existir dentro del contenedor en ejecución en /var/local/netowl-data/license.key para que NetOwl Namematcher funcione, incluida la documentación alojada. Para el testcontainer, se monta directamente en el contenedor desde el classpath; al desplegar con docker compose la licencia puede montarse desde un volumen del sistema de archivos local. En un despliegue de kubernetes la licencia podría provenir de un config map, como se ve en identity-resolution-deployments.
Alternativamente, la licencia puede enviarse por POST vía http, por ejemplo:
curl --request POST \
--url http://localhost:8081/api/v2/license-key \
--header 'Content-Type: application/json' \
--data '{
"product": "NameMatcher",
"type": "Development",
"thread limit": 1,
"*": {
"lifespan": [
"2022-01-01 00:00Z",
"2023-01-01 00:00Z"
],
"features": [
"Latin"
]
},
"verification": 1778757171272520714
}'La licencia podría enviarse desde un init container, o incluso enviarse manualmente utilizando la UI de NetOwl.
Después de enviar la licencia, la UI cambiará e incluirá enlaces a la documentación oficial.
Actualizar NetOwl
La documentación de NetOwl tiene una guía de instalación que incluye una sección sobre actualización desde versiones anteriores. También hay una página de historial de versiones que lista los principales cambios en cada versión.
Los pasos típicos para absorber una nueva versión de NetOwl Namematcher son:
-
Los binarios y licencias de NetOwl se obtienen de NetOwl, y el binario debe subirse manualmente a Nexus.
-
Ejecute el trabajo de Jenkins de netowl-namematcher, que extrae y ejecuta el pipeline de Jenkins de netowl-namematcher. Esto produce imágenes docker
registry.ipf.iconsolutions.com/netowl-namematcheretiquetadas conlatesty la versión usada para ejecutar el trabajo. -
Actualice el módulo netowl-testcontainer con la versión correcta; las pruebas de integración ahora usarán la última versión y se pueden usar para verificar que Identity Resolution funciona con la actualización de Namematcher.
-
Actualice el e2e_functional.yml en local-e2e-test con la versión correcta y ejecute las pruebas e2e para estar realmente seguro de que todo está funcionando correctamente.
NetOwl Application TLS
NetOwl Namematcher es una aplicación web basada en Apache Tomcat; por lo tanto, habilitar TLS deberá hacerse antes de construir la imagen docker, o después reemplazando el archivo server.xml de Tomcat por uno configurado correctamente para TLS. También se deberá colocar un keystore en el directorio de instalación de NetOwl.
Para más información consulte la documentación oficial, que tiene una sección sobre TLS.
Incluir la configuración TLS en la imagen docker
Antes de construir la imagen docker de NetOwl Namematcher, coloque un archivo de keystore en el directorio de instalación bajo /server/. Luego edite el server.xml de Tomcat en el directorio de instalación, bajo /server/conf/server.xml. Necesitará lo siguiente:
<Connector port="8443" keystoreFile="keystore.jks" keystorePass="password"
scheme="https" secure="true" clientAuth="false" maxThreads="150"
SSLEnabled="true" sslProtocol="TLS" protocol="org.apache.coyote.http11.Http11NioProtocol" />Construya la imagen docker.
Montar la configuración TLS en el contenedor
Monte el keystore en el contenedor de NetOwl Namematcher bajo /usr/local/netowl-inst/server. Luego monte un server.xml, reemplazando el que está dentro del contenedor en /usr/local/netowl-inst/server/conf/server.xml, y que contenga lo siguiente.
CONSEJO: Copie el server.xml del directorio de instalación como referencia de configuración
<Connector port="8443" keystoreFile="keystore.jks" keystorePass="password"
scheme="https" secure="true" clientAuth="false" maxThreads="150"
SSLEnabled="true" sslProtocol="TLS" protocol="org.apache.coyote.http11.Http11NioProtocol" />En un archivo docker compose, esto podría verse así:
netowl-namematcher:
image: releases-registry.ipfdev.co.uk/thirdparty/netowl-namematcher:4.9.11.0
container_name: netowl-namematcher
ports:
- "8081:8080"
- "8443:8443"
volumes:
- ./config/netowl-namematcher/license.key:/var/local/netowl-data/license.key
- ./config/netowl-namematcher/keystore.jks:/usr/local/netowl-inst/server/keystore.jks
- ./config/netowl-namematcher/server.xml:/usr/local/netowl-inst/server/conf/server.xmlIdentity Resolution Application
Identity Resolution es una aplicación basada en Spring Boot y está destinada a desplegarse junto con Namematcher para satisfacer la funcionalidad de comparación. Como es una aplicación Spring Boot, se admiten todas las propiedades habituales de las aplicaciones Spring.
Hocon es la forma principal de configurar identity-resolution, aunque los archivos application.properties también son compatibles.
Para la configuración de la conectividad con NetOwl, consulte la sección NetOwl.
Metrics
Las métricas de la aplicación compatibles con Prometheus se exponen en /actuator/prometheus
Las métricas específicas de características e implementación (por ejemplo, comparison o netowl) también pueden exponerse bajo este endpoint y se documentan en las secciones relevantes.
Actuator
Los endpoints de health e info también incluyen la dependencia NetOwl. Vea la sección NetOwl Actuator para más información.
Identity Resolution viene con la siguiente configuración de endpoints de actuator predeterminada.
management.endpoints.web.exposure.include = [health, info, prometheus]Si desea deshabilitar los endpoints de health y/o info, deberá hacerlo explícitamente, cambiando el arreglo de includes en un application.conf.
management.endpoints.web.exposure.include = [prometheus] //Look ma, no healthTLS
Identity Resolution es una aplicación Spring Boot, que acepta un conjunto de propiedades server.ssl.* para configurar TLS.
si el TLS del servidor está habilitado, también configure comparison client tls