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

Integre o GitHub App para habilitar o login com GitHub, vinculação de contas e acesso seguro às APIs do GitHub com permissões granulares e tokens de atualização.

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.

GitHub App vs OAuth App

O GitHub oferece dois tipos de aplicativos para autenticação e acesso à API: GitHub Apps e OAuth Apps. Veja uma comparação para ajudar na escolha:

Recurso	GitHub App	OAuth App
Permissões	Permissões granulares — solicita acesso apenas a recursos específicos	Escopos amplos — geralmente concede mais acesso do que o necessário
Gerenciamento de permissões	Configurado apenas no painel do GitHub; o campo Scope do Logto pode ficar vazio	Configurado via escopos no conector do Logto
Tokens de atualização (Refresh tokens)	Sempre emitidos durante o fluxo OAuth	Não suportado — tokens nunca expiram a menos que revogados
Expiração do token	Tokens de acesso expiram após 8 horas; tokens de atualização válidos por 6 meses	Tokens de acesso nunca expiram
Controle do usuário	Usuários podem escolher quais repositórios o app pode acessar	Acesso a todos os repositórios que o usuário pode acessar
Limites de taxa	Limites de taxa mais altos que escalam com instalações	Limites de taxa mais baixos (5.000 requisições/hora por usuário)
Instalação	Instalado em contas/organizações com acesso granular a repositórios	Autorizado por usuários com acesso amplo
Webhooks	Suporte centralizado a webhook integrado	Deve ser configurado separadamente para cada repositório
Atuação independente	Pode agir em seu próprio nome (servidor para servidor)	Sempre age em nome de um usuário

Quando usar GitHub App:

• Você precisa de controle granular sobre permissões e acesso a repositórios
• Você deseja tokens de atualização para acesso prolongado à API com segurança aprimorada
• Você precisa de limites de taxa de API mais altos
• Você deseja realizar tarefas automatizadas independentemente das sessões de usuário

Quando usar OAuth App:

• Integração simples de login com acesso mínimo à API
• Você precisa de tokens que não expiram (para integrações legadas)
• Você precisa acessar recursos em nível empresarial (GitHub Apps ainda não suportam permissões em nível empresarial)

dica:

O GitHub recomenda GitHub Apps em vez de OAuth Apps para a maioria dos casos de uso devido aos seus recursos de segurança aprimorados e permissões granulares. Saiba mais sobre as diferenças entre GitHub Apps e OAuth Apps.

Primeiros passos

O conector GitHub App permite 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 do GitHub
• Acessar APIs do GitHub por meio do armazenamento seguro de tokens no Logto Secret Vault para tarefas automatizadas (por exemplo, criar issues no GitHub, gerenciar repositórios a partir do seu app)
• Usar tokens de atualização (refresh tokens) (sempre emitidos por GitHub Apps) para manter acesso prolongado à API sem exigir que os usuários se autentiquem novamente

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

1. Acesse Logto console > Conector > Conector social.
2. Clique em Adicionar conector social, selecione GitHub App, clique em Próximo e siga o tutorial passo a passo para concluir a integração.

Etapa 1: Crie um GitHub App

Antes de usar o GitHub como um provedor de autenticação, você deve criar um GitHub App 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 > GitHub Apps.
3. Clique em New GitHub App para registrar um novo aplicativo:
   • GitHub App name: Insira um nome exclusivo para seu aplicativo. O nome não pode ter mais de 34 caracteres e deve ser único em todo o GitHub.
   • Homepage URL: Insira a URL da página inicial do seu aplicativo.
   • Callback URL: Copie o Callback URI do seu conector GitHub do Logto e cole aqui. Você pode adicionar várias URLs de callback se necessário. 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.
   • Expire user authorization tokens: Mantenha esta opção marcada (recomendado). Isso habilita a expiração de tokens e tokens de atualização para maior segurança.
   • Request user authorization (OAuth) during installation: Opcionalmente marque esta opção para solicitar que os usuários autorizem seu aplicativo durante a instalação.
   • Webhook: Desmarque Active se você não precisar de eventos de webhook. Para casos de uso apenas de autenticação, webhooks normalmente não são necessários.
4. Em Permissions, configure as permissões que seu aplicativo precisa (veja a Etapa 2 abaixo para detalhes).
5. Em Where can this GitHub App be installed?, selecione Any account se quiser que usuários de qualquer conta do GitHub possam usar seu aplicativo para autenticação.
6. Clique em Create GitHub App para criar o GitHub App.

nota:

Diferente dos OAuth Apps, os GitHub Apps usam permissões granulares em vez de escopos amplos. Você configura as permissões no painel do GitHub durante a criação do aplicativo, e os usuários concedem acesso a repositórios específicos durante a autorização.

Para mais detalhes sobre como configurar GitHub Apps, veja Registering a GitHub App.

Etapa 2: Configure as permissões no GitHub

Os GitHub Apps usam permissões granulares em vez de escopos OAuth. Você deve configurar as permissões no painel do GitHub ao criar ou editar seu GitHub App. Essas permissões determinam quais dados seu aplicativo pode acessar.

Entendendo as permissões do GitHub App

As permissões são categorizadas em três tipos:

• Permissões de repositório: Acesso a recursos no nível do repositório (código, issues, pull requests, etc.)
• Permissões de organização: Acesso a recursos no nível da organização (membros, equipes, projetos, etc.)
• Permissões de conta: Acesso a dados da conta do usuário (email, perfil, seguidores, etc.)

Para cada permissão, você pode selecionar:

• No access: O aplicativo não pode acessar este recurso
• Read-only: O aplicativo pode ler, mas não modificar este recurso
• Read & write: O aplicativo pode ler e modificar este recurso

Permissões recomendadas para autenticação

Para a funcionalidade básica de "Entrar com o GitHub", configure estas permissões mínimas de conta:

Permissão	Nível de acesso	Finalidade
Email addresses	Read-only	Obter o endereço de email do usuário para criação de conta

dica:

Os GitHub Apps têm acesso implícito para ler informações públicas do perfil ao agir em nome de um usuário. Não é necessário solicitar permissão explicitamente para dados básicos do perfil como nome de usuário, avatar e URL do perfil público.

Permissões adicionais para acesso à API

Se seu aplicativo precisar acessar APIs do GitHub além da autenticação, adicione as permissões correspondentes no painel do GitHub. Aqui estão alguns exemplos comuns:

Tipo de permissão	Permissão	Nível de acesso	Caso de uso
Repository	Contents	Read-only / Read & write	Acessar arquivos e código do repositório
Repository	Issues	Read & write	Criar e gerenciar issues
Repository	Pull requests	Read & write	Criar e gerenciar pull requests
Repository	Metadata	Read-only	Acessar metadados do repositório (necessário para várias operações)
Organization	Members	Read-only	Listar membros da organização
Account	Followers	Read-only	Acessar seguidores e seguidos do usuário

Esta não é uma lista exaustiva — os GitHub Apps suportam muitas outras permissões granulares. Veja Permissions required for GitHub Apps para a lista completa.

Diferencial chave em relação aos OAuth Apps:

Diferente dos OAuth Apps, onde você configura escopos no conector do Logto, as permissões do GitHub App são gerenciadas inteiramente no painel do GitHub. Você pode deixar o campo Scope vazio no seu conector GitHub do Logto — não é necessário porque os GitHub Apps não usam escopos OAuth tradicionais.

Basta configurar as permissões necessárias no GitHub, e os usuários serão solicitados a conceder acesso durante a autorização.

Etapa 3: Configure seu conector Logto

Após criar o GitHub App, você será redirecionado para a página de configurações dele, onde poderá obter as credenciais.

1. Na página de configurações do seu GitHub App, copie o Client ID e cole no campo clientId no Logto.
2. Em Client secrets, clique em Generate a new client secret. Copie o segredo gerado 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.

nota:

O Client ID de um GitHub App é diferente do App ID. Certifique-se de usar o Client ID (exibido como "Client ID" na página de configurações), não o App ID.

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 do GitHub, você pode configurar como as informações do perfil são sincronizadas do user info do GitHub para o perfil do usuário no Logto, incluindo name, avatar e email. Escolha entre as seguintes opções:

• Sincronizar apenas no cadastro: As informações do perfil são buscadas uma vez quando o usuário faz login pela primeira vez.
• Sempre sincronizar no login: 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), ative o armazenamento de tokens no Logto:

1. Configure as permissões necessárias nas configurações do seu GitHub App (Etapa 2).
2. Ative Store tokens for persistent API access no conector GitHub do Logto. O Logto armazenará com segurança tanto o token de acesso quanto o token de atualização no Secret Vault.

nota:

Como os GitHub Apps sempre emitem tokens de atualização, o Logto armazena ambos os tokens automaticamente. O token de acesso expira após 8 horas, mas o Logto pode usar o token de atualização para obter novos tokens de acesso, garantindo acesso contínuo à API por até 6 meses.

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

Antes de ir para produção, teste a integração do seu GitHub App:

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 usuários são solicitados para as permissões corretas durante a autorização.
4. Se você ativou o armazenamento de tokens, verifique se os tokens de acesso (e tokens de atualização) estão sendo armazenados corretamente.
5. Teste chamadas à API usando os tokens armazenados para garantir que as permissões estão funcionando conforme esperado.

Os GitHub Apps funcionam com qualquer conta de usuário do GitHub imediatamente — não é necessário criar usuários de teste ou aprovação do aplicativo como em outras plataformas. No entanto, se seu aplicativo for instalado em uma organização, os proprietários da organização podem precisar aprovar a instalação.

Utilizar o conector GitHub

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

Habilitar "Login com GitHub"

1. No Logto Console, acesse Experiência de login > Cadastro e login.
2. Adicione o conector 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.

Vincular ou desvincular uma conta GitHub

Use a Account API para construir um Centro de Conta personalizado em seu app que permita aos usuários autenticados vincular ou desvincular sua conta GitHub. Siga o tutorial da Account API

dica:

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

Acessar APIs do GitHub e executar ações

Seu aplicativo pode recuperar tokens 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.

Como os GitHub Apps sempre emitem tokens de atualização durante o fluxo OAuth, o Logto armazena tanto tokens de acesso quanto tokens de atualização. Os tokens de acesso expiram após 8 horas, mas o Logto usa automaticamente o token de atualização (válido por 6 meses) para obter novos tokens de acesso, garantindo acesso contínuo à API.

Gerenciar a identidade GitHub do usuário

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

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

nota:

Diferente dos OAuth Apps que usam escopos, os GitHub Apps usam permissões granulares configuradas no painel do GitHub. O token de acesso do usuário é limitado às permissões que tanto seu app quanto o usuário possuem. O Logto não pode exibir diretamente a lista de permissões, mas seu aplicativo terá acesso conforme as permissões configuradas nas definições do seu GitHub App.

Referência

Documentação do desenvolvedor GitHub - Sobre GitHub Apps

Documentação do desenvolvedor GitHub - Registrando um GitHub App

Documentação do desenvolvedor GitHub - Gerando tokens de acesso de usuário

Documentação do desenvolvedor GitHub - Atualizando tokens de acesso de usuário

GitHub Apps vs OAuth Apps