Estrutura de dados do conector

Introdução

O que é um conector?

Connectors desempenham um papel crítico no Logto. Com a ajuda deles, o Logto permite que os usuários finais usem 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ê quiser configurar um conector existente. Se você não encontrar o conector que deseja configurar, pode desenvolvê-los seguindo os guias em desenvolver seu conector.

Composições

Existem muitas 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 DB e o restante localmente.

• Armazenamento local, também conhecido como ConnectorMetadata, é um objeto que contém propriedades fixas, como logotipo, tipo de conector, e assim por diante. (: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 às mudanças relativamente frequentes nesses dados.

Armazenamento local do conector: ConnectorMetadata

id

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

É atribuída pelos desenvolvedores de cada conector e será carregada para o DB.

target

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" 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 uma string não vazia arbitrária, mas incentivamos você a mantê-la direta, pois não pode ser alterada. 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 em seu telefone, um aplicativo nativo WeChat é necessário conforme o TOU do WeChat; ao mesmo tempo, um aplicativo web WeChat também é necessário para permitir o login em aplicativos web. Esses dois aplicativos 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 aplicativo que suporta login com conta do GitHub e do Google.	Casos de uso mais comuns.	✅
Diferentes IdPs e o 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 que foi criada usando a conta GitHub de outro usuário.	❌
O 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 esteja usando 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 uma boa prática criar dois locatários separados para lidar com esse caso de uso.
O mesmo IdP e o mesmo target	1. Conector GitHub (target: github) 2. Conector OAuth GitHub (target: github)	N/A	Usar qualquer um desses dois conectores pode resultar no mesmo resultado exato.	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 se encaixe no 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 mídias sociais de terceiros com autorização dos usuários finais.
• SMS: Conectores que permitem que os usuários finais recebam 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 aplicativos web de desktop.
• Universal: Conectores que podem funcionar em aplicativos web móveis e aplicativos web de desktop.

nota

platform de conectores de email e conectores de SMS deve sempre ser null.
SOMENTE conectores sociais podem ter valores platform não nulos.

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 breves descrições do conector.

nota

Para suportar a exibição i18n no lado do cliente, armazenamos as propriedades 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 logotipo do conector.

logoDark

logoDark é uma URL ou caminho relativo do logotipo do conector em 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

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

Logto chama conectores construídos com base em protocolos abertos e padrão (por exemplo, OAuth, OIDC, SAML, etc.) de conectores "padrão". Espera-se que os usuários do Logto construam várias instâncias em cada conector padrão com base nesse contexto. Por exemplo, suponha que o Logto já tenha fornecido um conector padrão OAuth, os usuários podem construir instâncias "Conector OAuth GitHub", "Conector OAuth Google" e "Conector OAuth Facebook". Todos eles são baseados no conector padrão OAuth do Logto.

Se você estiver 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 de Email ou SMS "padrão" no estágio atual.

readme

readme é um caminho relativo do arquivo README markdown do conector cujos contextos aparecerão no "Admin Console" durante a configuração dos conectores.

configTemplate

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

Armazenamento remoto do conector: Connector DB

id

id, que funciona como a chave primária do DB 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 de DB de conector e módulo de código de conector correspondentes, connectorId sempre é igual a 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, padrão para FALSE.

Se syncProfile for FALSE, as informações básicas do usuário do Logto (incluindo nome e avatar) serão atualizadas apenas quando o usuário se inscrever pela primeira vez no Logto através deste 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 um objeto não vazio arbitrário.

É onde um conector armazena sua configuração. Cada conector tem diferentes propriedades em config e é obrigado a ser válido (conectores têm diferentes padrões para "válido") antes de ser salvo no DB. SOMENTE aqueles config que passaram na verificação de validade podem ser atualizados para o DB, caso contrário, haverá um erro.

Os desenvolvedores são obrigados a implementar uma proteção config ao desenvolver seus próprios conectores, veja desenvolver seu conector para mais detalhes.

Quer dar uma olhada em amostras de config? Vá para conectores ou a página de configurações de cada conector.

nota

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

A regra, conector de Email ou SMS único em funcionamento, não se aplica aos conectores Social.
Em outras palavras, você pode adicionar vários conectores Social.

createdAt

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