Estructura de datos de usuario

Los usuarios son las entidades principales en el servicio de identidad. En Logto, incluyen datos básicos de autenticación basados en el protocolo OpenID Connect, junto con datos personalizados.

Perfil de usuario

Cada usuario tiene un perfil que contiene toda la información del usuario.

Consiste en los siguientes tipos de datos:

Datos básicos: es la información básica del perfil del usuario. Almacena todas las demás propiedades del usuario excepto las identities sociales y custom_data, como el id de usuario, nombre de usuario, correo electrónico, número de teléfono y cuándo fue la última vez que inició sesión.
Identidades sociales: almacena la información del usuario obtenida del inicio de sesión social (es decir, inicio de sesión con un conector social), como Facebook, GitHub y WeChat.
Datos personalizados: almacena información adicional del usuario que no está listada en las propiedades predefinidas del usuario, como el color y el idioma preferidos por el usuario.

Aquí tienes un ejemplo de los datos de un usuario obtenidos de un inicio de sesión en Facebook:

{
  "id": "iHXPuSb9eMzt",
  "username": null,
  "primaryEmail": null,
  "primaryPhone": null,
  "name": "John Doe",
  "avatar": "https://example.com/avatar.png",
  "customData": {
    "preferences": {
      "language": "en",
      "color": "#f236c9"
    }
  },
  "identities": {
    "facebook": {
      "userId": "106077000000000",
      "details": {
        "id": "106077000000000",
        "name": "John Doe",
        "email": "[email protected]",
        "avatar": "https://example.com/avatar.png"
      }
    }
  },
  "lastSignInAt": 1655799453171,
  "applicationId": "admin_console"
}

Puedes consultar el perfil de usuario usando Logto Console o Logto Management API, como GET /api/users/:userId.

Datos básicos

Vamos a repasar todas las propiedades de los datos básicos del usuario.

id

id es una clave única autogenerada para identificar al usuario en Logto.

username

username se utiliza para iniciar sesión con username y contraseña.

Su valor proviene del nombre de usuario con el que el usuario se registró por primera vez. Puede ser null. Su valor no nulo no debe superar los 128 caracteres, solo puede contener letras, números y guiones bajos (_), y NO debe comenzar con un número. Es sensible a mayúsculas y minúsculas.

primary_email

primary_email es la dirección de correo electrónico del usuario, utilizada para iniciar sesión con el correo electrónico y contraseña / código de verificación.

Su valor suele provenir de la dirección de correo electrónico con la que el usuario se registró por primera vez. Puede ser null. Su longitud máxima es 128.

primary_phone

primary_phone es el número de teléfono del usuario, utilizado para iniciar sesión con el número de teléfono y contraseña / código de verificación por SMS.

Su valor suele provenir del número de teléfono con el que el usuario se registró por primera vez. Puede ser null. Su valor no nulo debe contener números precedidos por el código de país (excluyendo el signo más +).

name

name es el nombre completo del usuario. Su longitud máxima es 128.

avatar

avatar es la URL que apunta a la imagen de avatar del usuario. Su longitud máxima es 2048.

Si el usuario se registra con un conector social como Google o Facebook, su valor puede obtenerse de la información social del usuario.

nota:

Esta propiedad se asigna al reclamo picture en el estándar OpenID Connect.

profile

profile almacena reclamos estándar adicionales de OpenID Connect que no están incluidos en las propiedades del usuario.

Su definición de tipo se puede encontrar en este archivo. Aquí tienes una copia de la definición de tipo:

type UserProfile = Partial<{
  familyName: string;
  givenName: string;
  middleName: string;
  nickname: string;
  preferredUsername: string;
  profile: string;
  website: string;
  gender: string;
  birthdate: string;
  zoneinfo: string;
  locale: string;
  address: Partial<{
    formatted: string;
    streetAddress: string;
    locality: string;
    region: string;
    postalCode: string;
    country: string;
  }>;
}>;

nota:

Partial significa que todas las propiedades son opcionales.

Una diferencia en comparación con otros reclamos estándar es que las propiedades en profile solo se incluirán en el Token de ID (ID token) o en la respuesta del endpoint userinfo cuando sus valores no estén vacíos, mientras que otros reclamos estándar devolverán null si los valores están vacíos.

application_id

El valor de application_id proviene de la aplicación en la que el usuario inició sesión por primera vez. Puede ser null.

last_sign_in_at

last_sign_in_at es la marca de tiempo con la zona horaria cuando el usuario inició sesión por última vez.

created_at

created_at es la marca de tiempo con la zona horaria cuando el usuario registró la cuenta.

updated_at

updated_at es la marca de tiempo con la zona horaria cuando la información del perfil del usuario fue actualizada por última vez.

has_password

has_password es un valor booleano que indica si el usuario tiene una contraseña. Puedes ver y gestionar este estado, incluyendo establecer una nueva o restablecer la contraseña en la página de detalle de Consola > Gestión de usuarios.

password_encrypted

password_encrypted se utiliza para almacenar la contraseña cifrada del usuario.

Su valor proviene de la contraseña con la que el usuario se registró por primera vez. Puede ser null. Si su valor no es nulo, su contenido original antes del cifrado debe tener al menos seis caracteres.

password_encryption_method

password_encryption_method se utiliza para cifrar la contraseña del usuario. Su valor se inicializa cuando el usuario se registra con nombre de usuario y contraseña. Puede ser null.

Logto utiliza la implementación node-argon2 de Argon2 como método de cifrado por defecto; consulta la referencia para más detalles si te interesa.

Ejemplo de password_encrypted y password_encryption_method de un usuario cuya contraseña es 123456:

{
  "password_encryption_method": "Argon2i",
  "password_encrypted": "$argon2i$v=19$m=4096,t=10,p=1$aZzrqpSX45DOo+9uEW6XVw$O4MdirF0mtuWWWz68eyNAt2u1FzzV3m3g00oIxmEr0U"
}

is_suspended

is_suspended es un valor booleano que indica si un usuario está suspendido o no. El valor puede ser gestionado llamando a la Logto Management API o usando Logto Console.

Una vez que un usuario es suspendido, los tokens de actualización previamente otorgados serán revocados inmediatamente y el usuario ya no podrá autenticarse con Logto.

mfa_verification_factors

mfa_verification_factors es un array que lista los métodos de autenticación multifactor (MFA) asociados a la cuenta del usuario. Los valores posibles incluyen: Totp (OTP de app autenticadora), WebAuthn (Passkey) y BackupCode.

mfaVerificationFactors: ("Totp" | "WebAuthn" | "BackupCode")[];

identities contiene la información del usuario obtenida del inicio de sesión social (es decir, inicio de sesión con un conector social). Cada identities de usuario se almacena en un objeto JSON individual.

La información del usuario varía según el proveedor de identidad social (es decir, la plataforma de red social), y normalmente incluye lo siguiente:

target del proveedor de identidad, como "facebook" o "google"
Identificador único del usuario para este proveedor
Nombre del usuario
Correo electrónico verificado del usuario
Avatar del usuario

La cuenta del usuario puede estar vinculada a varios proveedores de identidad social mediante inicio de sesión social; la información correspondiente obtenida de estos proveedores se almacenará en el objeto identities.

Ejemplo de identities de un usuario que inició sesión con Google y Facebook:

{
  "facebook": {
    "userId": "5110888888888888",
    "details": {
      "id": "5110888888888888",
      "name": "John Doe",
      "email": "[email protected]",
      "avatar": "https://example.com/avatar.png"
    }
  },
  "google": {
    "userId": "111000000000000000000",
    "details": {
      "id": "111000000000000000000",
      "name": "John Doe",
      "email": "[email protected]",
      "avatar": "https://example.com/avatar.png"
    }
  }
}

Identidades SSO

sso_identities contiene la información del usuario obtenida del SSO empresarial (es decir, inicio de sesión único con un conector empresarial). Cada ssoIdentities de usuario se almacena en un objeto JSON individual.

Los datos sincronizados desde el proveedor de identidad SSO dependen de los alcances configurados en el conector empresarial para solicitar. Aquí tienes una copia de la definición de tipo TypeScript:

type SSOIdentity = {
  issuer: string;
  identityId: string;
  detail: JsonObject; // Ver https://github.com/withtyped/withtyped/blob/master/packages/server/src/types.ts#L12
};

Datos personalizados

custom_data almacena información adicional del usuario que no está listada en las propiedades predefinidas del usuario.

Puedes usar custom_data para hacer lo siguiente:

Registrar si el usuario ha realizado acciones específicas, como haber visto la página de bienvenida.
Almacenar datos específicos de la aplicación en el perfil del usuario, como el idioma y la apariencia preferidos por el usuario por aplicación.
Mantener otros datos arbitrarios relacionados con el usuario.

Ejemplo de custom_data de un usuario administrador en Logto:

{
  "adminConsolePreferences": {
    "language": "en",
    "appearanceMode": "system",
    "experienceNoticeConfirmed": true
  },
  "customDataFoo": {
    "foo": "foo"
  },
  "customDataBar": {
    "bar": "bar"
  }
}

Cada custom_data de usuario se almacena en un objeto JSON individual.

nota:

NO pongas datos sensibles en custom_data.

Los datos personalizados pueden ser accedidos a través de Reclamos personalizados de token JWT después del inicio de sesión del usuario, y los tokens JWT están codificados en base64 (no cifrados) y se transmiten frecuentemente a través de redes, lo que hace que cualquier dato sensible sea fácilmente expuesto.

Puedes obtener un perfil de usuario que contenga custom_data usando Management API y enviarlo a las aplicaciones frontend o servicios backend externos. Por lo tanto, poner información sensible en custom_data puede causar filtraciones de datos.

Si aún deseas poner información sensible en custom_data, recomendamos cifrarla primero. Solo cifra/descifra en una parte confiable como tus servicios backend, y evita hacerlo en las aplicaciones frontend. Esto minimizará la pérdida si el custom_data de tus usuarios se filtra por error.

Cómo recopilar y actualizar datos personalizados del usuario

Utiliza la función Recopilar perfil de usuario para reunir datos personalizados durante el registro del usuario.
Utiliza la Account API para implementar el perfil del usuario final o la configuración de la cuenta.
- Usa GET /api/my-account para obtener todos los datos del usuario.
- Usa PATCH /api/my-account para actualizar el custom_data de un usuario.
Utiliza la Management API para la gestión de usuarios o flujos personalizados avanzados:
- Usa GET /api/users/{userId} para obtener todos los datos del usuario.
- Usa PATCH /api/users/{userId}/custom-data para actualizar el custom_data de un usuario.
Tu equipo de soporte puede actualizar directamente el custom_data del usuario en Consola > Gestión de usuarios. Aprende más sobre ver y actualizar perfiles de usuario.

Actualiza con cuidado. Actualizar el custom_data de un usuario sobrescribirá completamente su contenido original en el almacenamiento.

Por ejemplo, si tu entrada al llamar a la API de actualización de custom_data se ve así (supón que el custom_data original es el ejemplo mostrado anteriormente):

{
  "customDataBaz": {
    "baz": "baz"
  }
}

entonces el nuevo valor de custom_data después de la actualización será:

{
  "customDataBaz": {
    "baz": "baz"
  }
}

Es decir, el valor del campo actualizado no tiene relación con el valor anterior.

Referencia de propiedades

Las siguientes columnas de la tabla de usuarios de la base de datos (excepto password_encrypted y password_encryption_method) son visibles en el perfil del usuario, lo que significa que puedes consultarlas usando Management API.

Nombre	Tipo	Descripción	Único	Requerido
id	string	Identificador único	✅	✅
username	string	Nombre de usuario para iniciar sesión	✅	❌
primary_email	string	Correo electrónico principal	✅	❌
primary_phone	string	Número de teléfono principal	✅	❌
name	string	Nombre completo	❌	❌
avatar	string	URL del avatar del usuario	❌	❌
profile	object	Perfil de usuario	❌	✅
identities	object	Información obtenida del inicio de sesión social	❌	✅
custom_data	object	Información adicional en propiedades personalizables	❌	✅
application_id	string	ID de la aplicación en la que el usuario se registró primero	❌	✅
last_sign_in_at	date time	Marca de tiempo del último inicio de sesión	❌	✅
password_encrypted	string	Contraseña cifrada	❌	❌
password_encryption_method	string	Método de cifrado de contraseña	❌	❌
is_suspended	bool	Marca de suspensión del usuario	❌	✅
mfa_verifications	object[]	Factores de verificación MFA	❌	✅

Único: Garantiza la unicidad de los valores ingresados en una propiedad de una tabla de base de datos.
Requerido: Garantiza que los valores ingresados en una propiedad de una tabla de base de datos NO pueden ser null.

Centro seguro para datos de usuario en movimiento

Perfil de usuario​

Datos básicos​

id​

username​

primary_email​

primary_phone​

name​

avatar​

profile​

application_id​

last_sign_in_at​

created_at​

updated_at​

has_password​

password_encrypted​

password_encryption_method​

is_suspended​

mfa_verification_factors​

Identidades sociales​

Identidades SSO​

Datos personalizados​

Referencia de propiedades​

Recursos relacionados​

Perfil de usuario

Datos básicos

id

username

primary_email

primary_phone

name

avatar

profile

application_id

last_sign_in_at

created_at

updated_at

has_password

password_encrypted

password_encryption_method

is_suspended

mfa_verification_factors

Identidades sociales

Identidades SSO

Datos personalizados

Referencia de propiedades

Recursos relacionados