Estructura de datos del conector
Introducción
¿Qué es un conector?
Los conectores juegan un papel fundamental en Logto. Con su ayuda, Logto permite a los usuarios finales utilizar el registro o inicio de sesión sin contraseña y las capacidades de iniciar sesión con cuentas sociales. Con la creciente popularidad de los sitios web y aplicaciones, los inicios de sesión sin contraseña y sociales permiten a los usuarios evitar gestionar numerosas cuentas y contraseñas.
Sigue nuestras guías de conectores si quieres configurar un conector existente. Si no encuentras el conector que deseas configurar, puedes desarrollarlo siguiendo las guías en desarrolla tu conector.
Composiciones
Existen muchas propiedades en los datos del conector.
Para hacer que la carga y actualización de datos sea más eficiente, almacenamos parte de los datos del conector que se modificarán con frecuencia en la base de datos y el resto localmente.
- Almacenamiento local, también conocido como ConnectorMetadata, es un objeto que contiene propiedades fijas como el logo, tipo de conector, etc. (:face_with_monocle: ¿Tienes problemas para entender estas propiedades? ¡No te preocupes, una explicación detallada viene más adelante!)
- Almacenamiento remoto se guarda en la base de datos debido a los cambios relativamente frecuentes en esos datos.
Almacenamiento local del conector: ConnectorMetadata
id
id es una clave de tipo cadena única para identificar un conector en Logto.
Es asignada por los desarrolladores de cada conector y se subirá a la base de datos.
target (Nombre del proveedor de identidad)
target es una cadena en minúsculas para distinguir la fuente de identidades sociales del conector social.
Los usuarios de Logto pueden considerar esta variable como "Nombre del proveedor de identidad" para una mejor comprensión.
Por ejemplo, tu target debe ser google si inicias sesión en Logto con tu cuenta de Google. El valor de target puede ser cualquier cadena no vacía, pero te animamos a mantenerlo sencillo ya que no puedes cambiarlo. NO permitimos la existencia de múltiples conectores con el mismo target y plataforma. Por otro lado, puedes tener conectores sociales para diferentes plataformas que compartan el mismo target. Por ejemplo, si los usuarios quieren iniciar sesión vía WeChat en su teléfono, se requiere una app nativa de WeChat según los Términos de Uso de WeChat; al mismo tiempo, también se necesita una app web de WeChat para habilitar el inicio de sesión en aplicaciones web. Estas dos apps de WeChat comparten el mismo proveedor de identidad y deben tener el mismo target.
Hemos resumido diferentes casos de uso y sugerencias para los usuarios, ya que target es un concepto complicado.
| Ejemplo | Escenario | Resultado | ¿Recomendado? | |
|---|---|---|---|---|
| Diferentes IdP y diferentes targets | 1. Conector de GitHub (target: github) 2. Conector de Google (target: google) | Una app que admite inicio de sesión con cuenta de GitHub y Google. | Casos de uso más comunes. | ✅ |
| Diferentes IdP y el mismo target | 1. Conector de GitHub (target: github) 2. Conector de Google (target: github) | N/A | Es posible que un usuario inicie sesión en una cuenta Logto que fue creada usando la cuenta de GitHub de otro usuario. | ❌ |
| El mismo IdP y diferentes targets | 1. Conector de GitHub (target: github) 2. Conector OAuth de GitHub (target: github_oauth) | El conector de GitHub se usa para la Aplicación A, mientras que el conector OAuth de GitHub se creó específicamente para la Aplicación B. | Iniciar sesión en Logto usando estos dos conectores diferentes siempre creará cuentas Logto separadas, incluso si el usuario usa la misma cuenta de GitHub. | Dividir tu grupo de usuarios es el único escenario donde necesitarías usar ambos conectores. Sin embargo, generalmente se considera mejor práctica crear dos inquilinos separados para este caso. |
| El mismo IdP y el mismo target | 1. Conector de GitHub (target: github) 2. Conector OAuth de GitHub (target: github) | N/A | Usar cualquiera de estos dos conectores puede resultar en exactamente el mismo resultado. | Crear dos conectores que esencialmente hacen lo mismo puede ser confuso para los usuarios finales y no tiene mucho sentido. Es mejor usar un conector que se ajuste a tu caso de uso específico. |
type
type es la propiedad que registra el tipo de conector.
Definimos los conectores en tres tipos diferentes, según sus funcionalidades:
- Social: Conectores que pueden acceder a la información del usuario desde cualquier red social de terceros con la autorización del usuario final.
- SMS: Conectores que permiten a los usuarios finales recibir mensajes de texto en sus teléfonos.
- Email: Conectores que pueden ayudar a enviar correos electrónicos a los usuarios finales.
platform
platform se utiliza para identificar para qué plataforma se construyó el conector.
platform debe ser null o uno de los siguientes valores de tipo cadena:
- Native: Conectores que SOLO funcionan para aplicaciones móviles nativas.
- Web: Conectores que SOLO funcionan en aplicaciones web de escritorio.
- Universal: Conectores que pueden funcionar tanto en aplicaciones web móviles como en aplicaciones web de escritorio.
El platform de los conectores de email y conectores de SMS siempre debe ser null.
SOLO los conectores sociales pueden tener valores de platform distintos de NULL.
name
name es un objeto cuyas claves son códigos de país i18n y los valores son el nombre para mostrar de los conectores.
description
description también es un objeto cuyas claves son códigos de país i18n y los valores son descripciones breves del conector.
Para soportar la visualización i18n en el lado del cliente, almacenamos las propiedades name (así como description) como un mapa, que utiliza los códigos de país como clave y el nombre (o descripción) en caracteres locales como valor.
logo
logo es una URL o ruta relativa del logo del conector.
logoDark
logoDark es una URL o ruta relativa nullable del logo del conector en modo oscuro.
logo siempre es obligatorio, y logoDark es opcional.
Mostramos logo en modo claro y logoDark en modo oscuro si existe. De lo contrario, se mostrará logo en modo oscuro.
isStandard
isStandard es un atributo booleano OPCIONAL para identificar si el conector social es un conector "estándar". Puedes identificar un conector "estándar" por su atributo isStandard verdadero.
Logto solo admite conectores sociales "estándar". Es decir, todos los conectores de Email o SMS de Logto NO son "estándar".
Logto llama conectores "estándar" a los que están construidos sobre protocolos abiertos y estándar (por ejemplo, OAuth, OIDC, SAML, etc.). Se espera que los usuarios de Logto construyan múltiples instancias en cada conector estándar en este contexto. Por ejemplo, supón que Logto ya ha proporcionado un conector estándar OAuth, los usuarios pueden crear instancias como "conector OAuth de GitHub", "conector OAuth de Google" y "conector OAuth de Facebook". Todos ellos se basan en el conector estándar OAuth de Logto.
Si estás familiarizado con el diseño de conectores de Logto, como máximo puede existir UN conector de Email o SMS al mismo tiempo, lo que significa que Logto no necesita conectores de Email o SMS "estándar" en la etapa actual.
readme
readme es una ruta relativa del archivo README markdown del conector cuyos contenidos se mostrarán en la "Consola de administración" durante la configuración de los conectores.
configTemplate
configTemplate es una ruta relativa de un ejemplo de configuración del conector.
Almacenamiento remoto del conector: Connector DB {#connectors-remote-storage-connector-db}
id
id, que funciona como clave primaria de la base de datos del conector, es una clave de tipo cadena generada aleatoriamente para identificar el conector en la base de datos.
connectorId
connectorId es una clave de tipo cadena y es el ÚNICO puente para alinear Connector DB y ConnectorMetadata. Para cada par de datos de conector DB y módulo de código de conector coincidente, connectorId siempre es igual a metadata.id del módulo de código.
metadata
metadata es un subconjunto de ConnectorMetadata, que contiene atributos configurables como logo, logoDark, target y name.
syncProfile
syncProfile es un valor booleano para determinar el esquema de actualización del perfil de usuario, por defecto es FALSE.
Si syncProfile es FALSE, la información básica del usuario de Logto (incluyendo nombre y avatar) solo se actualizará cuando el usuario se registre por primera vez en Logto a través de este conector. De lo contrario, cada vez que los usuarios inicien sesión en Logto a través del conector, el perfil de la cuenta Logto se actualizará.
config
config puede ser cualquier objeto no vacío.
Es donde un conector almacena su configuración. Cada conector tiene diferentes propiedades en config y está obligado a ser válido (los conectores tienen diferentes estándares para "válido") antes de ser guardado en la base de datos. SOLO aquellos config que pasen la verificación de validez pueden actualizarse en la base de datos, de lo contrario se lanzará un error.
Se requiere que los desarrolladores implementen una protección de config al desarrollar sus propios conectores, consulta desarrolla tu conector para más detalles.
¿Quieres ver ejemplos de config? Ve a conectores o a la página de configuración de cada conector.
En la versión actual de Logto, solo puede existir un conector de Email/SMS al mismo tiempo, todos los demás conectores del mismo tipo se eliminan automáticamente.
La regla, un único conector de Email o SMS funcionando, no es aplicable a los conectores Social.
En otras palabras, puedes añadir múltiples conectores Social.
createdAt
createdAt es una cadena de marca de tiempo generada automáticamente para rastrear el momento en que se crea un conector en la base de datos.