Estructura de datos del conector
Introducción
¿Qué es un conector?
Los Conectores juegan un papel crítico 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 deseas configurar un conector existente. Si no puedes encontrar el conector que deseas configurar, puedes desarrollar esos conectores siguiendo las guías en desarrolla tu conector.
Composiciones
Hay 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 frecuentemente 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, el 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 almacena en la base de datos debido a los cambios relativamente frecuentes en esos datos.
Almacenamiento local del conector: ConnectorMetadata
id
id es una clave única de tipo cadena para identificar un conector en Logto.
Es asignada por los desarrolladores de cada conector y se cargará en 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 debería ser google si inicias sesión en Logto con tu cuenta de Google. El valor de target puede ser una cadena no vacía arbitraria, 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 compartiendo el mismo target. Por ejemplo, si los usuarios quieren iniciar sesión a través de WeChat en su teléfono, se requiere una aplicación nativa de WeChat por los TOU de WeChat; al mismo tiempo, también se necesita una aplicación web de WeChat para habilitar el inicio de sesión en aplicaciones web. Estas dos aplicaciones de WeChat comparten el mismo proveedor de identidad y deberían tener el mismo target.
Hemos concluido diferentes casos de uso y sugerencias para los usuarios ya que target es un concepto complicado.
| Ejemplo | Escenario | Resultado | ¿Recomendado? | |
|---|---|---|---|---|
| Diferentes IdPs y diferentes targets | 1. Conector de GitHub (target: github) 2. Conector de Google (target: google) | Una aplicación que admite tanto el inicio de sesión con cuenta de GitHub como de Google. | Casos de uso más comunes. | ✅ |
| Diferentes IdPs 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 de 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 fue creado específicamente para la Aplicación B. | Iniciar sesión en Logto usando estos dos conectores diferentes siempre creará cuentas de Logto separadas, incluso si el usuario está usando 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 una mejor práctica crear dos inquilinos separados para manejar este caso de uso. |
| 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 el mismo resultado exacto. | 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 del conector.
Definimos los conectores en tres tipos diferentes, basados en sus funcionalidades:
- Social: Conectores que pueden acceder a la información del usuario desde redes sociales de terceros con la autorización de los usuarios finales.
- 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 está construido 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 funcionan SOLO 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 correo electrónico y conectores de SMS siempre debe ser null.
SOLO los conectores sociales pueden tener valores de platform no nulos.
name
name es un objeto cuyas claves son códigos de país i18n y los valores son el nombre de visualización de los conectores.
description
description también es un objeto cuyas claves son códigos de país i18n y los valores son breves descripciones del conector.
Para admitir la visualización i18n en el lado del cliente, almacenamos las propiedades name (así como description) como un mapa, que utiliza códigos de país como su clave, y el nombre (o descripción) en caracteres locales como el valor.
logo
logo es una URL o ruta relativa del logo del conector.
logoDark
logoDark es una URL o ruta relativa nula del logo del conector en modo oscuro.
logo siempre es requerido, 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 correo electrónico o SMS de Logto NO son "estándar".
Logto llama conectores construidos sobre protocolos abiertos y estándar (por ejemplo, OAuth, OIDC, SAML, etc.) como conectores "estándar". Se espera que los usuarios de Logto construyan múltiples instancias en cada conector estándar basado en este contexto. Por ejemplo, supongamos que Logto ya ha proporcionado un conector estándar OAuth, los usuarios pueden construir instancias de "conector OAuth de GitHub", "conector OAuth de Google" y "conector OAuth de Facebook". Todos están basados 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 correo electrónico o SMS al mismo tiempo, lo que significa que Logto no necesita conectores de correo electrónico o SMS "estándar" en la etapa actual.
readme
readme es una ruta relativa del archivo README en formato markdown del conector cuyos contextos aparecerán en "Admin Console" durante la configuración de los conectores.
configTemplate
configTemplate es una ruta relativa del ejemplo de configuración del conector.
Almacenamiento remoto del conector: 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 base de datos de conector y módulo de código de conector emparejado, connectorId siempre es igual a metadata.id del módulo de código.
metadata
metadata es un subconjunto de ConnectorMetadata, que contiene atributos configurables, es decir, logo, logoDark, target y name.
syncProfile
syncProfile es un valor booleano para determinar el esquema de actualización del perfil del usuario, por defecto es FALSE.
Si syncProfile es FALSE, la información básica del usuario de Logto (incluyendo nombre y avatar) se actualizará solo 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 de Logto se actualizará.
config
config podría ser un objeto no vacío arbitrario.
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 ser actualizados en la base de datos, o se lanzará un error.
Se requiere que los desarrolladores implementen un guardián de config al desarrollar sus propios conectores, consulta desarrolla tu conector para más detalles.
¿Quieres echar un vistazo a 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, conector único de correo electrónico o SMS en funcionamiento, no se aplica a los conectores Social.
En otras palabras, puedes agregar 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.