Estrutura de dados do usuário

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 as 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 recuperados de um login pelo 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 passar por 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 nome de usuário e senha.

Seu valor vem do nome de usuário com o qual o usuário se registrou pela primeira vez. Pode ser null. Seu valor não nulo deve ter no máximo 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 vem 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 por SMS.

Seu valor geralmente vem 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 discagem do país (excluindo o sinal de mais +).

name

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

avatar

avatar é a URL que aponta 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 ou 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 vem 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 de quando o usuário fez login pela última vez.

created_at

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

updated_at

updated_at é o timestamp com o fuso horário de 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 possui 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 vem 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.

O Logto usa a implementação node-argon2 do Argon2 como método de criptografia 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 previamente 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 de aplicativo autenticador), 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 normalmente incluem o seguinte:

• target do provedor de identidade, como "facebook" ou "google"
• Identificador único do usuário para esse 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 recuperadas desses provedores serão armazenadas no objeto identities.

Exemplo de identities de um usuário que fez login tanto com Google quanto com 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 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 requisiçã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 as seguintes finalidades:

• 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 idioma e aparência preferidos 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.

Os dados personalizados podem ser acessados por meio de Reivindicações personalizadas de token JWT após o login do usuário, e os tokens JWT são codificados em base64 (não criptografados) e frequentemente transmitidos pela rede, tornando qualquer dado sensível facilmente exposto.

Você pode buscar um perfil de usuário contendo custom_data usando a 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 ainda assim quiser colocar informações sensíveis em custom_data, recomendamos criptografá-las primeiro. Só criptografe / descriptografe em uma parte confiável, como seus serviços backend, e evite fazer isso em aplicativos frontend. Isso minimizará a perda caso o custom_data de seus usuários seja vazado por engano.

Como coletar e atualizar dados personalizados do usuário

• Use o recurso Coletar perfil do usuário para reunir dados personalizados durante o cadastro do usuário.
• Use a Account API para implementar configurações de perfil ou conta do usuário final.
  • Use GET /api/my-account para recuperar todos os dados do usuário.
  • Use PATCH /api/my-account para atualizar o custom_data de um usuário.
• Use a Management API para gerenciamento de usuários ou fluxos personalizados avançados:
  • Use GET /api/users/{userId} para recuperar todos os dados do usuário.
  • Use PATCH /api/users/{userId}/custom-data para atualizar o custom_data de um usuário.
• Sua equipe de suporte pode atualizar diretamente o custom_data do usuário em Console > Gerenciamento de usuários. Saiba mais sobre visualizar e atualizar perfis de usuário.

Atualize com cuidado. Atualizar o custom_data de um usuário sobrescreverá completamente seu conteúdo original no armazenamento.

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

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

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

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

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

Referência de propriedades

As seguintes colunas da tabela de usuários do banco de dados (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 a 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 do avatar do usuário	❌	❌
profile	object	Perfil do usuário	❌	✅
identities	object	Informações do usuário do login social	❌	✅
custom_data	object	Informações adicionais em propriedades customizáveis	❌	✅
application_id	string	ID do aplicativo em que o usuário se registrou primeiro	❌	✅
last_sign_in_at	date time	Timestamp do último login do usuário	❌	✅
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 do banco de dados.
• Obrigatório: Garante que os valores inseridos em uma propriedade de uma tabela do banco de dados NÃO podem ser null.

Recursos relacionados

Hub seguro para dados de usuários em movimento