Pular para o conteúdo principal

Guia passo a passo para desenvolver um conector social

A maneira mais rápida de começar é copiar o código de um conector oficial existente e modificá-lo para atender às suas necessidades. Vamos usar o conector do GitHub como exemplo.

Passo 1: Clone um pacote de conector existente​

Em uma pasta de origem do conector, você encontrará os seguintes arquivos:

  • index.ts: O arquivo principal de entrada do conector.
  • constant.ts: As constantes usadas no conector.
  • types.ts: Os tipos TypeScript usados no conector.
  • index.test.ts: Os casos de teste para o conector.
  • mock.ts: Os dados simulados usados nos casos de teste do conector.

Além desses arquivos, você também precisará fornecer um arquivo README.md para descrever o conector, um logo.svg (opcionalmente um logo-dark.svg para uma melhor experiência no modo escuro) e um arquivo package.json para definir as informações do pacote npm.

Passo 2: Modifique o arquivo principal de entrada (index.ts)​

No arquivo index.ts, você encontrará a maior parte da lógica do conector. Normalmente, há 4 funções que você precisa implementar:

  • getAuthorizationUri: Gera o URI de autorização para a plataforma social de terceiros. Para o GitHub, seria: https://github.com/login/oauth/authorize?client_id={clientId}&redirect_uri={redirectUri}&state={state}. Consulte a documentação do desenvolvedor da sua plataforma social alvo para obter o URI correto.
  • authorizationCallbackHandler: Protege os valores dos parâmetros retornados no URI de callback de autorização, extrai o code de autorização e trata possíveis erros.
  • getAccessToken: Troca o code de autorização por um token de acesso.
  • getUserInfo: Busca informações do usuário na plataforma social de terceiros com o token de acesso.

A maioria das outras lógicas comuns já foi tratada no kit de conectores do Logto, o que deve facilitar seu trabalho.

Por fim, ao final do arquivo, você só precisará exportar o objeto do conector, seguindo a mesma estrutura de código do conector do GitHub.

const createGithubConnector: CreateConnector<SocialConnector> = async ({ getConfig }) => {
  return {
    metadata: defaultMetadata,
    type: ConnectorType.Social,
    configGuard: githubConfigGuard,
    getAuthorizationUri: getAuthorizationUri(getConfig),
    getUserInfo: getUserInfo(getConfig),
  };
};

Passo 3: Teste o conector​

Teste unitário​

Primeiro, escreva alguns casos de teste unitário e certifique-se de que as funcionalidades básicas funcionam conforme o esperado.

Teste local​

  • Configure o Logto em seu ambiente local: O Logto oferece várias maneiras de rodar localmente, você pode usar o CLI, docker ou até mesmo compilar a partir do código-fonte. Confira a documentação para mais detalhes.
  • Vincule seu conector personalizado à sua instância Logto: Use o CLI para criar um link simbólico do seu conector para a instância Logto. Mais detalhes. 
    cd logto
    npx @logto/cli connector link -p .
  • Após vincular o conector, você deverá vê-lo na pasta <logto-root-path>/packages/core/connectors.
  • Reinicie sua instância Logto, acesse o Logto Admin Console e você deverá vê-lo na lista de conectores sociais.
  • Configure seu conector em Console > Login & conta > Cadastro e login > Login social. E teste em nosso aplicativo de demonstração com o recurso "Visualização ao vivo".