Estrutura de dados do usuário

Os usuários são as entidades centrais no serviço de identidade. No Logto, eles incluem dados básicos de autenticação baseados no protocolo OpenID Connect, juntamente com dados personalizados.

Perfil do usuário

Cada usuário possui um perfil contendo todas as informações do usuário.

Consiste nos seguintes tipos de dados:

• Dados básicos: são as informações básicas do perfil do usuário. Armazena todas as outras propriedades do usuário, exceto por identities sociais e custom_data, como ID do usuário, nome de usuário, email, número de telefone e quando o usuário fez login pela última vez.
• Identidades sociais: armazena as informações do usuário recuperadas do login social (ou seja, login com um conector social), como Facebook, GitHub e WeChat.
• Dados personalizados: armazena informações adicionais do usuário não listadas nas propriedades predefinidas do usuário, como cor e idioma preferidos pelo usuário.

Aqui está um exemplo de dados de um usuário que foi recuperado de um login no 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": "johndoe@logto.io",
        "avatar": "https://example.com/avatar.png"
      }
    }
  },
  "lastSignInAt": 1655799453171,
  "applicationId": "admin_console"
}

Você pode consultar o perfil do usuário usando Logto Console ou Logto Management API, como GET /api/users/:userId.

Dados básicos

Vamos percorrer todas as propriedades dos dados básicos do usuário.

id

id é uma chave única gerada automaticamente para identificar o usuário no Logto.

username

username é usado para login com username e senha.

Seu valor é do nome de usuário com o qual o usuário se registrou pela primeira vez. Pode ser null. Seu valor não nulo não deve ter mais de 128 caracteres, conter apenas letras, números e sublinhados (_), e NÃO começar com um número. É sensível a maiúsculas e minúsculas.

primary_email

primary_email é o endereço de email do usuário, usado para login com email e senha / código de verificação.

Seu valor geralmente é do endereço de email com o qual o usuário se registrou pela primeira vez. Pode ser null. Seu comprimento máximo é 128.

primary_phone

primary_phone é o número de telefone do usuário, usado para login com o número de telefone e senha / código de verificação do SMS.

Seu valor geralmente é do número de telefone com o qual o usuário se registrou pela primeira vez. Pode ser null. Seu valor não nulo deve conter números prefixados com o código de chamada do país (excluindo o sinal de mais +).

name

name é o nome completo do usuário. Seu comprimento máximo é 128.

avatar

avatar é o URL apontando para a imagem do avatar do usuário. Seu comprimento máximo é 2048.

Se o usuário se registrar com um conector social como Google e Facebook, seu valor pode ser recuperado das informações sociais do usuário.

nota:

Esta propriedade é mapeada para a reivindicação picture no padrão OpenID Connect.

profile

profile armazena reivindicações padrão adicionais do OpenID Connect que não estão incluídas nas propriedades do usuário.

Sua definição de tipo pode ser encontrada neste arquivo. Aqui está uma cópia da definição 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 as propriedades são opcionais.

Uma diferença em relação às outras reivindicações padrão é que as propriedades em profile só serão incluídas no Token de ID (ID token) ou na resposta do endpoint userinfo quando seus valores não estiverem vazios, enquanto outras reivindicações padrão retornarão null se os valores estiverem vazios.

application_id

O valor de application_id é do aplicativo em que o usuário fez login pela primeira vez. Pode ser null.

last_sign_in_at

last_sign_in_at é o timestamp com o fuso horário quando o usuário fez login pela última vez.

created_at

created_at é o timestamp com o fuso horário quando o usuário registrou a conta.

updated_at

updated_at é o timestamp com o fuso horário quando as informações do perfil do usuário foram atualizadas pela última vez.

has_password

has_password é um valor booleano que indica se o usuário tem uma senha. Você pode visualizar e gerenciar esse status, incluindo definir uma nova senha ou redefinir a senha na página de detalhes de Console > Gerenciamento de usuários.

password_encrypted

password_encrypted é usado para armazenar a senha criptografada do usuário.

Seu valor é da senha com a qual o usuário se registrou pela primeira vez. Pode ser null. Se seu valor não for nulo, seu conteúdo original antes da criptografia deve ter pelo menos seis caracteres.

password_encryption_method

password_encryption_method é usado para criptografar a senha do usuário. Seu valor é inicializado quando o usuário se registra com nome de usuário e senha. Pode ser null.

Logto usa a implementação node-argon2 do Argon2 como método de criptografia por padrão; veja a referência para detalhes se estiver interessado.

Exemplo de password_encrypted e password_encryption_method de um usuário cuja senha é 123456:

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

is_suspended

is_suspended é um valor booleano que indica se um usuário está suspenso ou não. O valor pode ser gerenciado chamando a Logto Management API ou usando o Logto Console.

Uma vez que um usuário é suspenso, os tokens de atualização pré-concedidos serão revogados imediatamente e o usuário não poderá mais ser autenticado pelo Logto.

mfa_verification_factors

mfa_verification_factors é um array que lista os métodos de autenticação multifatorial (MFA) associados à conta do usuário. Os valores possíveis incluem: Totp (OTP do aplicativo Authenticator), WebAuthn (Passkey) e BackupCode.

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

Identidades sociais

identities contém as informações do usuário recuperadas do login social (ou seja, login com um conector social). Cada identities de usuário é armazenado em um objeto JSON individual.

As informações do usuário variam de acordo com o provedor de identidade social (ou seja, plataforma de rede social), e geralmente incluem o seguinte:

• target do provedor de identidade, como "facebook" ou "google"
• Identificador único do usuário para este provedor
• Nome do usuário
• Email verificado do usuário
• Avatar do usuário

A conta do usuário pode estar vinculada a vários provedores de identidade social via login social; as informações correspondentes do usuário recuperadas desses provedores serão armazenadas no objeto identities.

Exemplo de identities de um usuário que fez login com Google e Facebook:

{
  "facebook": {
    "userId": "5110888888888888",
    "details": {
      "id": "5110888888888888",
      "name": "John Doe",
      "email": "johndoe@logto.io",
      "avatar": "https://example.com/avatar.png"
    }
  },
  "google": {
    "userId": "111000000000000000000",
    "details": {
      "id": "111000000000000000000",
      "name": "John Doe",
      "email": "johndoe@gmail.com",
      "avatar": "https://example.com/avatar.png"
    }
  }
}

Identidades SSO

sso_identities contém as informações do usuário recuperadas do SSO corporativo (Enterprise SSO) (ou seja, login de Autenticação única com um conector corporativo). Cada ssoIdentities de usuário é armazenado em um objeto JSON individual.

Os dados sincronizados do provedor de identidade SSO dependem dos escopos configurados no conector corporativo para solicitação. Aqui está uma cópia da definição de tipo TypeScript:

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

Dados personalizados

custom_data armazena informações adicionais do usuário não listadas nas propriedades predefinidas do usuário.

Você pode usar custom_data para fazer as seguintes coisas:

• Registrar se ações específicas foram realizadas pelo usuário, como ter visto a página de boas-vindas.
• Armazenar dados específicos do aplicativo no perfil do usuário, como o idioma e a aparência preferidos pelo usuário por aplicativo.
• Manter outros dados arbitrários relacionados ao usuário.

Exemplo de custom_data de um usuário administrador no Logto:

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

Cada custom_data de usuário é armazenado em um objeto JSON individual.

Nota: NÃO coloque dados sensíveis em custom_data.

Você pode buscar um perfil de usuário contendo custom_data usando Management API e enviá-lo para aplicativos frontend ou serviços backend externos. Portanto, colocar informações sensíveis em custom_data pode causar vazamento de dados.

Se você ainda quiser colocar informações sensíveis em custom_data, recomendamos criptografá-las primeiro. Apenas criptografe / descriptografe em uma parte confiável, como seus serviços backend, e evite fazê-lo em aplicativos frontend. Isso minimizará a perda se o custom_data dos seus usuários for vazado por engano.

Você pode atualizar o custom_data do usuário usando Logto Console ou Logto Management API, como PATCH /api/users/:userId.

Atualize com cuidado

Atualizar o custom_data de um usuário substituirá completamente seu conteúdo original no armazenamento.

Por exemplo, se sua entrada ao chamar a API de atualização de custom_data for assim (suponha que o custom_data original seja o exemplo de dados mostrado anteriormente):

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

então o novo valor de custom_data após a atualização deve ser:

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

Ou seja, o valor do campo atualizado não tem relação com o valor anterior.

Referência de propriedades

As seguintes colunas da tabela de usuários do DB (exceto password_encrypted e password_encryption_method) são visíveis no perfil do usuário, o que significa que você pode consultá-las usando Management API.

Nome	Tipo	Descrição	Único	Obrigatório
id	string	Identificador único	✅	✅
username	string	Nome de usuário para login	✅	❌
primary_email	string	Email principal	✅	❌
primary_phone	string	Número de telefone principal	✅	❌
name	string	Nome completo	❌	❌
avatar	string	URL apontando para a imagem do avatar do usuário	❌	❌
profile	object	Perfil do usuário	❌	✅
identities	object	Informações do usuário recuperadas do login social	❌	✅
custom_data	object	Informações adicionais em propriedades personalizáveis	❌	✅
application_id	string	ID do aplicativo em que o usuário se registrou pela primeira vez	❌	✅
last_sign_in_at	date time	Timestamp quando o usuário fez login pela última vez	❌	✅
password_encrypted	string	Senha criptografada	❌	❌
password_encryption_method	string	Método de criptografia da senha	❌	❌
is_suspended	bool	Marca de suspensão do usuário	❌	✅
mfa_verifications	object[]	Fatores de verificação MFA	❌	✅

• Único: Garante a unicidade dos valores inseridos em uma propriedade de uma tabela de banco de dados.
• Obrigatório: Garante que os valores inseridos em uma propriedade de uma tabela de banco de dados NÃO podem ser null.

Recursos relacionados

Hub seguro para dados de usuários em movimento