GitHub Apps vs. OAuth Apps: Escolhe a ligação certa ao GitHub

Ao integrares a autenticação do GitHub na tua aplicação Logto, tens duas opções: GitHub Apps e GitHub OAuth Apps. Embora ambas permitam a funcionalidade "Iniciar sessão com GitHub", oferecem experiências fundamentalmente diferentes em termos de segurança, gestão de tokens e acesso à API. Este guia vai ajudar-te a perceber as diferenças-chave e escolher a abordagem certa para o teu caso de uso.

Contexto: Dois caminhos para integrar o GitHub#

A documentação atual do Logto guia-te na configuração de uma GitHub OAuth App para iniciares sessão socialmente. Esta é a opção mais simples e direta, ótima para necessidades básicas de autenticação. No entanto, os GitHub Apps representam a abordagem moderna e recomendada pelo próprio GitHub, oferecendo funcionalidades de segurança avançadas e controlo mais granular.

Pensa assim: As OAuth Apps são como dar a alguém uma chave mestra da tua casa — depois de autorizadas, têm acesso amplo. As GitHub Apps, por outro lado, assemelham-se a um sistema de fechadura inteligente, com códigos de acesso específicos para cada divisão — os utilizadores podem conceder permissões exatas apenas para aquilo que a tua app necessita.

Principais diferenças num relance#

Permissões: Abrangentes vs. granulares#

• OAuth Apps usam scopes amplos — solicitar repo concede controlo total do repositório.
• GitHub Apps usam permissões granulares — podes pedir apenas "Issues: Leitura" sem aceder ao código. Os utilizadores também podem selecionar repositórios específicos na instalação, sem conceder acesso ao todo.

Segurança do token: Permanente vs. temporário#

• OAuth Apps emitem tokens que nunca expiram (até serem revogados manualmente), sem mecanismo de renovação.
• GitHub Apps usam tokens de curta duração (expiram em 1 hora) com suporte automático à renovação — significativamente mais seguro para aplicações de longa duração.

Identidade: Utilizador vs. bot#

• OAuth Apps atuam sempre como o utilizador que autoriza (ex: @octocat) e partilham o limite de taxa desse utilizador (5.000 pedidos/hora).
• GitHub Apps podem atuar de forma independente com a própria identidade de bot (ex: @my-app[bot]) e usufruir de limites de taxa escaláveis com o uso — perfeito para automação.

Controlo de acesso: Tudo-ou-nada vs. seletivo#

• OAuth Apps requerem autorização única para todos os recursos acessíveis.
• GitHub Apps permitem que os utilizadores instalem a app, escolham repositórios específicos e recebam notificações webhook sobre alterações de permissões — proporcionando transparência e controlo superiores.

Persistência: Dependente do utilizador vs. independente#

• OAuth Apps estão ligadas ao utilizador autorizador — se esse programador perder acesso ou abandonar uma organização, a app deixa de funcionar.
• GitHub Apps continuam a funcionar mesmo que o programador que fez a instalação saia da tua organização — garantindo serviço ininterrupto para automação e integrações.

Qual escolher?#

Tanto GitHub Apps como OAuth Apps funcionam perfeitamente com o conector social do Logto. O Cofre de Segredos do Logto armazena de forma segura tokens de qualquer uma das integrações, mas cada opção proporciona uma experiência diferente:

Início de sessão social básico com OAuth Apps#

Se só precisas de autenticar utilizadores (Iniciar sessão com GitHub) e não vais chamar APIs do GitHub após o login, o caminho do OAuth App é o mais rápido:

• Configuração simples: os utilizadores autorizam a tua OAuth App e iniciam sessão via GitHub.
• Tokens de longa duração (sem renovação): o Logto pode guardar o access token no Secret Vault, mas não existe fluxo de renovação — os tokens mantêm-se válidos até serem revogados.
• Ideal quando só precisas da identidade do utilizador (email, nome, avatar) e não realizas operações automáticas via API.

Razão para escolher: implementação mais rápida para protótipos ou apps que apenas requerem login e sincronização ocasional de perfil.

Integração avançada com GitHub Apps#

Opta por uma GitHub App se a tua aplicação precisa de acesso contínuo às APIs do GitHub, automação em background ou maior segurança:

• Permissões granulares e seleção de repositórios por instalação mantêm o acesso mínimo e auditável.
• Tokens de curta duração (normalmente 1 hora) e GitHub Apps podem fornecer tokens de renovação; quando ativado, o Logto guarda ambos os tokens de acesso e renovação no Secret Vault e gere a rotação para que o teu backend continue a funcionar sem necessidade de novo login do utilizador.
• Identidade como app (bot) melhora a atribuição e limites de taxa escaláveis tornam a solução mais fiável para automação intensiva.

Melhor para:

• Plataformas SaaS que gerem repositórios GitHub em nome dos utilizadores
• Agentes de IA que interagem com código, issues ou pull requests
• Aplicações que requerem acesso sustentado à API
• Ferramentas que realizam tarefas de automação em background

Configurar uma GitHub App com o Logto#

A configuração de uma GitHub App segue um padrão semelhante ao das OAuth Apps, com algumas diferenças essenciais. A migração de OAuth App para GitHub App exige pouco esforço.

Criar uma GitHub App#

1. Vai a "GitHub Settings > Developer settings > GitHub Apps"

2. Clica em "New GitHub App"

3. Configura:

   • Nome da GitHub App: Identificador único da tua aplicação
   • Homepage URL: O site da tua aplicação
   • Callback URL: URI de callback do conector Logto (igual ao OAuth App)
   • Solicitar autorização de utilizador (OAuth) durante a instalação: Ativa esta opção
   • Webhook: Opcional, conforme as tuas necessidades
   • Permissões: Seleciona permissões granulares (ex: "Issues: Leitura")
   • Permissões de utilizador: Adiciona permissões de conta se atuas em nome dos utilizadores

4. Gera um client secret (tal como numa OAuth App)

Configurar no Logto#

A configuração do conector Logto é quase idêntica:

1. Introduz o Client ID da tua GitHub App
2. Adiciona o Client secret
3. Ativa "Armazenar tokens para acesso persistente à API" se precisares de chamar APIs do GitHub
4. Diferença crucial - Scopes:
   • Ao contrário das OAuth Apps (que exigem adicionar scopes no campo scope do Logto), as permissões das GitHub Apps são definidas diretamente nas definições da GitHub App.
   • Simplesmente deixa o campo scope vazio no Logto
5. Solicitar token de renovação (opcional)
   • Adiciona offline_access ao campo scope no Logto para ativar tokens de renovação
   • O GitHub emite automaticamente um token de renovação e o Logto gere a rotação e armazena ambos os tokens no Secret Vault
   • Nota: As OAuth Apps não suportam tokens de renovação — os seus access tokens nunca expiram, por isso offline_access não se aplica. Isto é diferente ao usar GitHub Apps para integrar.

Conclusão#

Apesar das OAuth Apps continuarem a ser uma opção válida para autenticação básica, as GitHub Apps representam o futuro das integrações com GitHub. Oferecem uma segurança superior devido à expiração dos tokens, modelos de permissões mais precisos e melhor controlo do acesso pelo utilizador.

Para os utilizadores do Logto, ambas as opções funcionam com o conector social. A escolha depende das tuas necessidades específicas:

• Começa simples com OAuth Apps se só precisas de autenticação
• Evolui para GitHub Apps se precisares de acesso à API, automação ou segurança avançada

E não te esqueças — o Secret Vault do Logto e a renovação automática de tokens tornam a gestão dos tokens das GitHub Apps tão simples quanto nas OAuth Apps, sem sacrificar segurança. Estejas a construir um assistente de programação com IA, uma plataforma de gestão de projetos ou uma ferramenta de produtividade para developers, agora já tens o conhecimento para escolher a integração GitHub certa para a tua aplicação Logto.

Pronto para começar? Consulta o conector GitHub do Logto para começares hoje a integrar a autenticação GitHub.

Recursos adicionais#

• GitHub: Diferenças entre GitHub Apps e OAuth Apps
• GitHub: Migrar OAuth Apps para GitHub Apps
• Logto: Configurar login social com GitHub
• Logto: Armazenamento de tokens de terceiros & acesso à API
• GitHub: Criar um GitHub App
• GitHub: Scopes para OAuth Apps