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.

Ele 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 dos dados de um usuário que foram recuperados 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": "[email protected]",
        "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.

primary_email

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

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 código de acesso 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 standard claims 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_signed_in_at

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

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 o 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 o Logto Management API ou usando o Admin Console.

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

Referência de propriedades

As seguintes propriedades (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	❌	❌
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	❌	✅

Ú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.

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": "[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"
    }
  }
}

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.

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 fazer isso 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 Admin 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 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.

Recursos relacionados

Hub seguro para dados de usuário em movimento

Perfil do usuário​

Dados básicos​

id​

username​

primary_email​

primary_phone​

name​

avatar​

profile​

application_id​

last_signed_in_at​

password_encrypted​

password_encryption_method​

is_suspended​

Referência de propriedades​

Identidades sociais​

Dados personalizados​

Recursos relacionados​