Estrutura de dados do conector

Introdução

O que é um conector?

Conectores (Connectors) desempenham um papel fundamental no Logto. Com a ajuda deles, o Logto permite que os usuários finais utilizem registro ou login sem senha e as capacidades de login com contas sociais. Com a crescente popularidade de sites e aplicativos, logins sem senha e sociais permitem que os usuários evitem gerenciar inúmeras contas e senhas.

Siga nossos guias de conectores se você deseja configurar um conector existente. Se não encontrar o conector que deseja configurar, você pode desenvolvê-lo seguindo os guias em desenvolva seu conector.

Composições

Existem várias propriedades nos dados do conector.

Para tornar o carregamento e a atualização dos dados mais eficientes, armazenamos parte dos dados do conector que serão modificados frequentemente no banco de dados (DB) e o restante localmente.

• Armazenamento local, também conhecido como ConnectorMetadata, é um objeto que contém propriedades fixas como logo, tipo de conector, etc. (:face_with_monocle: Está com dificuldade para entender essas propriedades? Não se preocupe, uma explicação detalhada vem a seguir!)
• Armazenamento remoto é armazenado no DB devido à frequência relativamente alta de alterações nesses dados.

Armazenamento local do conector: ConnectorMetadata

id

id é uma chave do tipo string única para identificar um conector no Logto.

Ela é atribuída pelos desenvolvedores de cada conector e será enviada para o DB.

target (Nome do provedor de identidade)

target é uma string em minúsculas para distinguir a fonte de identidades sociais do conector social.

Os usuários do Logto podem considerar essa variável como "Nome do provedor de identidade (Identity provider name)" para melhor compreensão.

Por exemplo, seu target deve ser google se você fizer login no Logto com sua conta do Google. O valor de target pode ser qualquer string não vazia, mas recomendamos que seja direto, pois não é possível alterá-lo. NÃO permitimos a existência de múltiplos conectores com o mesmo target e plataforma. Por outro lado, você pode ter conectores sociais para diferentes plataformas compartilhando o mesmo target. Por exemplo, se os usuários quiserem fazer login via WeChat no celular, é necessário um app WeChat nativo conforme os Termos de Uso do WeChat; ao mesmo tempo, um app WeChat web também é necessário para permitir login em aplicações web. Esses dois apps WeChat compartilham o mesmo provedor de identidade e devem ter o mesmo target.

Concluímos diferentes casos de uso e sugestões para os usuários, já que target é um conceito complicado.

	Exemplo	Cenário	Resultado	Recomenda?
Diferentes IdPs e diferentes targets	1. Conector GitHub (target: github) 2. Conector Google (target: google)	Um app que suporta login tanto com GitHub quanto com conta Google.	Casos de uso mais comuns.	✅
Diferentes IdPs e mesmo target	1. Conector GitHub (target: github) 2. Conector Google (target: github)	N/A	É possível que um usuário faça login em uma conta Logto criada usando a conta GitHub de outro usuário.	❌
Mesmo IdP e diferentes targets	1. Conector GitHub (target: github) 2. Conector OAuth GitHub (target: github_oauth)	O conector GitHub é usado para o Aplicativo A, enquanto o conector OAuth GitHub foi criado especificamente para o Aplicativo B.	Fazer login no Logto usando esses dois conectores diferentes sempre criará contas Logto separadas - mesmo que o usuário use a mesma conta GitHub.	Dividir seu pool de usuários é o único cenário em que você precisaria usar ambos os conectores. No entanto, geralmente é considerado melhor criar dois tenants separados para esse caso de uso.
Mesmo IdP e mesmo target	1. Conector GitHub (target: github) 2. Conector OAuth GitHub (target: github)	N/A	Usar qualquer um desses dois conectores pode resultar exatamente no mesmo resultado.	Criar dois conectores que essencialmente fazem a mesma coisa pode ser confuso para os usuários finais e não faz muito sentido. É melhor usar um conector que atenda ao seu caso de uso específico.

type

type é a propriedade que registra o tipo do conector.

Definimos os conectores em três tipos diferentes, com base em suas funcionalidades:

• Social: Conectores que podem acessar informações do usuário de qualquer mídia social de terceiros com autorização do usuário final.
• SMS: Conectores que permitem aos usuários finais receber mensagens de texto em seus telefones.
• Email: Conectores que podem ajudar a enviar emails para os usuários finais.

platform

platform é usado para identificar para qual plataforma o conector foi construído.

platform deve ser null ou um dos seguintes valores do tipo string:

• Native: Conectores que funcionam SOMENTE para aplicativos móveis nativos.
• Web: Conectores que funcionam SOMENTE em aplicações web desktop.
• Universal: Conectores que funcionam tanto em apps web móveis quanto em apps web desktop.

nota:

platform de conectores de email e conectores SMS deve sempre ser null.
SOMENTE conectores sociais podem ter valores de platform diferentes de NULL.

name

name é um objeto cujas chaves são códigos de país i18n e os valores são o nome de exibição dos conectores.

description

description também é um objeto cujas chaves são códigos de país i18n e os valores são descrições breves do conector.

nota:

Para suportar exibição i18n no lado do cliente, armazenamos as props name (assim como description) como um mapa, que usa códigos de país como chave e o nome (ou descrição) em caracteres locais como valor.

logo

logo é uma URL ou caminho relativo do logo do conector.

logoDark

logoDark é uma URL ou caminho relativo opcional do logo do conector para modo escuro.

nota:

logo é sempre obrigatório, e logoDark é opcional.

Exibimos logo no modo claro e logoDark no modo escuro, se existir. Caso contrário, será exibido logo no modo escuro.

isStandard

isStandard é um atributo booleano OPCIONAL para identificar se o conector social é um conector "padrão". Você pode identificar um conector "padrão" pelo atributo isStandard verdadeiro.

nota:

O Logto só suporta conectores sociais "padrão". Ou seja, todos os conectores de Email ou SMS do Logto NÃO são "padrão".

O Logto chama de conectores "padrão" aqueles construídos sobre protocolos abertos e padronizados (por exemplo, OAuth, OIDC, SAML, etc.). Os usuários do Logto devem construir múltiplas instâncias em cada conector padrão com base nesse contexto. Por exemplo, suponha que o Logto já forneça um conector padrão OAuth, os usuários podem criar instâncias "OAuth GitHub connector", "OAuth Google connector" e "OAuth Facebook connector". Todos são baseados no conector padrão OAuth do Logto.

Se você está familiarizado com o design de conectores do Logto, no máximo UM conector de Email ou SMS pode existir ao mesmo tempo, o que significa que o Logto não precisa de conectores "padrão" de Email ou SMS no estágio atual.

readme

readme é um caminho relativo do arquivo README markdown do conector, cujo conteúdo será exibido no "Admin Console" durante a configuração dos conectores.

configTemplate

configTemplate é um caminho relativo de um exemplo de configuração do conector.

Armazenamento remoto do conector: Connector DB {#connectors-remote-storage-connector-db}

id

id, que funciona como chave primária do banco de dados do conector, é uma chave do tipo string gerada aleatoriamente para identificar o conector no DB.

connectorId

connectorId é uma chave do tipo string e é a ÚNICA ponte para alinhar Connector DB e ConnectorMetadata. Para cada par de dados do banco de dados do conector e módulo de código do conector correspondente, connectorId sempre é igual ao metadata.id do módulo de código.

metadata

metadata é um subconjunto de ConnectorMetadata, que contém atributos configuráveis, ou seja, logo, logoDark, target e name.

syncProfile

syncProfile é um valor booleano para determinar o esquema de atualização do perfil do usuário, sendo FALSE por padrão.

Se syncProfile for FALSE, as informações básicas do usuário Logto (incluindo nome e avatar) serão atualizadas apenas quando o usuário se cadastrar pela primeira vez no Logto via esse conector. Caso contrário, toda vez que os usuários fizerem login no Logto através do conector, o perfil da conta Logto será atualizado.

config

config pode ser qualquer objeto não vazio.

É onde um conector armazena sua configuração. Cada conector possui propriedades diferentes em config e é obrigatório que seja válido (os conectores têm padrões diferentes para "válido") antes de ser salvo no DB. SOMENTE os config que passarem na verificação de validade podem ser atualizados no DB, caso contrário, será lançado um erro.

Os desenvolvedores devem implementar uma proteção (guard) de config ao desenvolver seus próprios conectores, veja desenvolva seu conector para mais detalhes.

Quer ver exemplos de config? Acesse conectores ou a página de configurações de cada conector.

nota:

Na versão atual do Logto, apenas um conector Email/SMS pode existir ao mesmo tempo, todos os outros conectores do mesmo tipo são automaticamente excluídos.

A regra, conector único de Email ou SMS em funcionamento, não se aplica a conectores Sociais.
Ou seja, você pode adicionar vários conectores Sociais.

createdAt

createdAt é uma string de timestamp gerada automaticamente para rastrear o momento em que um conector é criado no DB.