Pular para o conteúdo principal

Configurar login social com GitHub (Set up social login with GitHub)

Integre o aplicativo GitHub OAuth para habilitar o login com GitHub, vinculação de contas e acesso seguro às APIs do GitHub.

dica:

Este guia assume que você tem um entendimento básico dos Conectores (Connectors) do Logto. Para aqueles que não estão familiarizados, consulte o guia de Conectores para começar.

Primeiros passos​

O conector do GitHub permite a integração OAuth 2.0 para que seu aplicativo possa:

  • Adicionar autenticação "Login com GitHub"
  • Vincular contas de usuário a identidades do GitHub
  • Sincronizar informações do perfil do usuário a partir do GitHub
  • Acessar APIs do GitHub por meio do armazenamento seguro de tokens no Logto Secret Vault para tarefas de automação (por exemplo, criar issues no GitHub, gerenciar repositórios a partir do seu app)

Para configurar esses recursos de autenticação, crie primeiro um conector do GitHub no Logto:

  1. Vá para Logto console > Connector > Social connector.
  2. Clique em Adicionar conector social, selecione GitHub, clique em Próximo e siga o tutorial passo a passo para concluir a integração.

Etapa 1: Crie um aplicativo OAuth no GitHub​

Antes de poder usar o GitHub como um provedor de autenticação, você deve criar um aplicativo OAuth no GitHub para obter credenciais OAuth 2.0.

  1. Acesse o GitHub e faça login com sua conta, ou crie uma nova conta se necessário.
  2. Navegue até Settings > Developer settings > OAuth apps.
  3. Clique em New OAuth App para registrar um novo aplicativo:
    • Application name: Insira um nome descritivo para seu aplicativo.
    • Homepage URL: Insira a URL da página inicial do seu aplicativo.
    • Authorization callback URL: Copie o Callback URI do seu conector GitHub do Logto e cole aqui. Após os usuários fazerem login com o GitHub, eles serão redirecionados para cá com um código de autorização que o Logto usa para concluir a autenticação.
    • Application description: (Opcional) Adicione uma breve descrição do seu aplicativo.
  4. Clique em Register application para criar o aplicativo OAuth.
nota:

Sugerimos não marcar a caixa Enable Device Flow, pois usuários que fizerem login com o GitHub em dispositivos móveis precisariam confirmar a ação inicial de login no aplicativo móvel do GitHub. Muitos usuários do GitHub não instalam o aplicativo móvel do GitHub em seus telefones, o que pode bloquear o fluxo de login. Só habilite isso se você espera que os usuários finais confirmem o fluxo de login pelo aplicativo móvel do GitHub. Veja detalhes sobre o device flow.

Para mais detalhes sobre como configurar aplicativos OAuth do GitHub, veja Creating an OAuth App.

Etapa 2: Configure seu conector Logto​

Após criar o aplicativo OAuth no GitHub, você será redirecionado para uma página de detalhes onde poderá copiar o Client ID e gerar um Client secret.

  1. Copie o Client ID do seu aplicativo OAuth do GitHub e cole no campo clientId no Logto.
  2. Clique em Generate a new client secret no GitHub para criar um novo segredo, depois copie e cole no campo clientSecret no Logto.
  3. Clique em Save and Done no Logto para conectar seu sistema de identidade ao GitHub.
atenção:

Mantenha seu Client secret seguro e nunca o exponha em código do lado do cliente. Os client secrets do GitHub não podem ser recuperados se perdidos — será necessário gerar um novo.

Etapa 3: Configure escopos (Opcional)​

Os escopos definem as permissões que seu aplicativo solicita dos usuários e controlam quais dados seu aplicativo pode acessar das contas GitHub deles.

Use o campo Scopes no Logto para solicitar permissões extras ao GitHub. Escolha uma das abordagens abaixo conforme sua necessidade:

Opção 1: Nenhum escopo extra de API necessário​

  • Deixe o campo Scopes em branco no seu conector GitHub do Logto.
  • O escopo padrão read:user será solicitado para garantir que o Logto possa obter corretamente as informações básicas do usuário (por exemplo, email, nome, avatar).

Opção 2: Solicitar escopos adicionais no login​

  • Veja todos os escopos disponíveis do GitHub para aplicativos OAuth e adicione apenas os escopos que seu aplicativo precisa.
  • Insira todos os escopos desejados no campo Scopes, separados por espaços.
  • Quaisquer escopos listados aqui substituem os padrões, então sempre inclua o escopo de autenticação: read:user.
  • Escopos adicionais comuns incluem:
    • repo: Controle total de repositórios privados
    • public_repo: Acesso a repositórios públicos
    • user:email: Acesso aos endereços de email do usuário
    • notifications: Acesso às notificações
  • Certifique-se de que todos os escopos estejam escritos corretamente e sejam válidos. Um escopo incorreto ou não suportado resultará em um erro "Invalid scope" do GitHub.

Opção 3: Solicitar escopos incrementais posteriormente​

  • Após o usuário fazer login, você pode solicitar escopos adicionais sob demanda reiniciando um fluxo de autorização social federada e atualizando o conjunto de tokens armazenados do usuário.
  • Esses escopos adicionais não precisam ser preenchidos no campo Scopes do seu conector GitHub do Logto, e podem ser obtidos através da Social Verification API do Logto.

Seguindo essas etapas, seu conector GitHub do Logto solicitará exatamente as permissões que seu aplicativo precisa — nem mais, nem menos.

dica:

Se seu aplicativo solicitar esses escopos para acessar a API do GitHub e realizar ações, certifique-se de habilitar Store tokens for persistent API access no conector GitHub do Logto. Veja a próxima seção para detalhes.

Etapa 4: Configurações gerais​

Aqui estão algumas configurações gerais que não bloqueiam a conexão com o GitHub, mas podem afetar a experiência de autenticação do usuário final.

Sincronizar informações do perfil​

No conector GitHub, você pode definir a política para sincronização das informações do perfil, como nomes de usuário e avatares. Escolha entre:

  • Only sync at sign-up: As informações do perfil são buscadas apenas uma vez, quando o usuário faz login pela primeira vez.
  • Always sync at sign-in: As informações do perfil são atualizadas toda vez que o usuário faz login.

Armazenar tokens para acessar APIs do GitHub (Opcional)​

Se você deseja acessar APIs do GitHub e realizar ações com autorização do usuário (seja via login social ou vinculação de conta), o Logto precisa obter escopos específicos de API e armazenar tokens.

  1. Adicione os escopos necessários seguindo as instruções acima.
  2. Habilite Store tokens for persistent API access no conector GitHub do Logto. O Logto armazenará com segurança os tokens de acesso do GitHub no Secret Vault.
nota:

Ao usar um OAuth App do GitHub conforme descrito neste tutorial, você não pode obter um refresh token do GitHub porque o token de acesso não expira, a menos que o usuário o revogue manualmente. Portanto, não é necessário adicionar offline_access no campo Scopes — fazer isso pode causar um erro.

Se você deseja que o token de acesso expire ou usar refresh tokens, considere integrar com um GitHub App em vez disso. Saiba mais sobre as diferenças entre GitHub Apps e OAuth Apps.

Etapa 5: Teste sua integração (Opcional)​

Antes de ir para produção, teste sua integração com o GitHub:

  1. Use o conector em um tenant de desenvolvimento do Logto.
  2. Verifique se os usuários conseguem fazer login com o GitHub.
  3. Confira se os escopos corretos estão sendo solicitados.
  4. Teste chamadas de API se você estiver armazenando tokens.

Os aplicativos OAuth do GitHub funcionam com qualquer conta de usuário do GitHub imediatamente — não é necessário criar usuários de teste ou aprovar o aplicativo como em outras plataformas.

Utilizar o conector do GitHub​

Depois de criar um conector do GitHub e conectá-lo ao GitHub, você pode incorporá-lo aos fluxos de usuários finais. Escolha as opções que atendem às suas necessidades:

Habilitar "Login com GitHub"​

  1. No Logto Console, vá para Sign-in experience > Sign-up and sign-in.
  2. Adicione o conector do GitHub na seção Login social para permitir que os usuários se autentiquem com o GitHub.

Saiba mais sobre a experiência de login social.

Use a Account API para construir um Centro de Conta personalizado em seu aplicativo, permitindo que usuários autenticados vinculem ou desvinculem sua conta do GitHub. Siga o tutorial da Account API

dica:

É permitido habilitar o conector do GitHub apenas para vinculação de contas e acesso à API, sem habilitá-lo para login social.

Acessar APIs do GitHub e realizar ações​

Seu aplicativo pode recuperar tokens de acesso do GitHub armazenados no Secret Vault para chamar APIs do GitHub e automatizar tarefas de backend (por exemplo, criar issues, gerenciar repositórios ou automatizar fluxos de trabalho). Consulte o guia sobre como recuperar tokens armazenados para acesso à API.

Gerenciar a identidade do usuário no GitHub​

Após um usuário vincular sua conta do GitHub, administradores podem gerenciar essa conexão no Logto Console:

  1. Navegue até Logto console > User management e abra o perfil do usuário.
  2. Em Conexões sociais, localize o item do GitHub e clique em Gerenciar.
  3. Nesta página, os administradores podem gerenciar a conexão do usuário com o GitHub, ver todas as informações de perfil concedidas e sincronizadas da conta do GitHub e verificar o status do token de acesso.
nota:

A resposta do token de acesso do GitHub não inclui informações específicas de escopo, portanto, o Logto não pode exibir diretamente a lista de permissões concedidas pelo usuário. No entanto, desde que o usuário tenha consentido com os escopos solicitados durante a autorização, seu aplicativo terá as permissões correspondentes ao acessar a API do GitHub.

Referência​

Documentação do GitHub Developer - Sobre Apps

Documentação do GitHub Developer - Criando um OAuth App

Documentação de Escopos do GitHub OAuth App