Práticas recomendadas para criar um aplicativo do GitHub

Selecione as permissões mínimas necessárias

Ao registrar o GitHub App, selecione as permissões mínimas necessárias para seu GitHub App. Se alguma chave ou token para seu aplicativo for comprometido, isso limitará a quantidade de danos que pode ocorrer. Para saber mais sobre como escolher permissões, confira Escolhendo permissões para um Aplicativo GitHub.

Quando seu GitHub App cria um token de acesso de instalação ou token de acesso do usuário, você pode limitar ainda mais os repositórios que o aplicativo pode acessar e as permissões que o token tem. Para saber mais, confira Como gerar um token de acesso de instalação para um Aplicativo GitHub e Como gerar um token de acesso do usuário para um GitHub App.

Mantenha-se abaixo do limite de taxa

Assine eventos de webhook em vez de sondar a API para obter dados. Isso ajudará o GitHub App a permanecer dentro do limite de taxa de API. Para saber mais, confira Usar webhooks com aplicativos GitHub e Criar um Aplicativo GitHub que responde a eventos de webhook.

Use solicitações condicionais para ajudar você a permanecer dentro do limite de taxa. Para obter mais informações sobre as solicitações condicionais, confira Práticas recomendadas para usar a API REST.

Se possível, use consultas GraphQL consolidadas em vez de solicitações de API REST para ajudar você a permanecer dentro dos limites de taxa. Para saber mais, confira Comparando a API REST do GitHub e a API GraphQL e Documentação da API do Graph do GitHub.

Se você atingir um limite de taxa e precisar repetir uma solicitação de API, use os cabeçalhos de resposta x-ratelimit-reset ou Retry-After. Se esses cabeçalhos não estiverem disponíveis, aguarde uma quantidade exponencialmente crescente de tempo entre as novas tentativas e gere um erro após um número específico de tentativas. Para saber mais, confira Práticas recomendadas para usar a API REST.

Proteger as credenciais do aplicativo

Você pode gerar uma chave privada e segredo do cliente para seu GitHub App. Com essas credenciais, seu aplicativo pode gerar tokens de acesso de instalação, tokens de acesso do usuário e tokens de atualização. Esses tokens podem ser usados para fazer solicitações de API em nome de uma instalação de aplicativo ou usuário.

Você deve armazenar essas credenciais com segurança. O mecanismo de armazenamento depende da arquitetura de integrações e da plataforma em que ele é executado. Em geral, você deve usar um mecanismo de armazenamento destinado a armazenar dados confidenciais na plataforma que você está usando.

Chaves privadas

A chave privada do GitHub App concede acesso a todas as contas em que o aplicativo está instalado.

Armazene os dados da chave privada do GitHub App em um cofre de chaves, como o Azure Key Vault e torne-o somente para assinatura.

Como alternativa, você pode armazenar a chave como uma variável de ambiente. No entanto, isso não é tão forte quanto armazenar a chave em um cofre. Se um invasor conseguir acesso ao ambiente, ele poderá ler a chave privada e obter autenticação persistente como o GitHub App.

Você nunca deve codificar a chave privada em seu aplicativo, mesmo que o código seja armazenado em um repositório privado. Se o seu aplicativo for um cliente nativo, um aplicativo do lado do cliente ou for executado em um dispositivo de usuário (em vez de ser executado em seus servidores), você nunca deverá enviar sua chave privada com seu aplicativo.

Você não deve gerar mais chaves privadas do que precisa. Você deve excluir chaves privadas de que não precisa mais. Para saber mais, confira Como gerenciar chaves privadas para Aplicativos GitHub.

Segredos do cliente

Os segredos do cliente são usados para gerar tokens de acesso do usuário para seu aplicativo, a menos que seu aplicativo use o fluxo do dispositivo. Para saber mais, confira Como gerar um token de acesso do usuário para um GitHub App.

Se o seu aplicativo for um site ou aplicativo Web, armazene o segredo do cliente em um cofre de chaves, como o Azure Key Vault ou como uma variável de ambiente criptografada ou um segredo em seu servidor.

Se o seu aplicativo for um cliente nativo, um aplicativo do lado do cliente ou for executado em um dispositivo de usuário (em vez de ser executado em seus servidores), você não poderá proteger o segredo do cliente. Você deve ter cuidado se planeja acessar seus serviços com base em tokens gerados pelo aplicativo, pois qualquer pessoa pode acessar o segredo do cliente para gerar um token.

Tokens de acesso de instalação, tokens de acesso do usuário e tokens de atualização

Os tokens de acesso à instalação são usados para fazer solicitações de API em nome de uma instalação de aplicativo. Os tokens de acesso do usuário são usados para fazer solicitações de API em nome de um usuário. Os tokens de atualização são usados para regenerar tokens de acesso do usuário. Seu aplicativo pode usar sua chave privada para gerar um token de acesso de instalação. Seu aplicativo pode usar seu segredo do cliente para gerar um token de acesso do usuário e atualizar o token.

Se o seu aplicativo for um site ou aplicativo Web, você deverá criptografar os tokens no back-end e garantir que haja segurança em torno dos sistemas que podem acessar os tokens. Armazene os tokens de atualização em um local separado dos tokens de acesso ativos.

Se o seu aplicativo for um cliente nativo, um aplicativo do lado do cliente ou executado em um dispositivo de usuário (em vez de ser executado em seus servidores), talvez você não consiga proteger tokens, bem como um aplicativo executado em seus servidores. Você não deve gerar tokens de acesso de instalação, pois isso requer uma chave privada. Em vez disso, você deve gerar tokens de acesso do usuário. Você deve armazenar tokens por meio do mecanismo recomendado para a plataforma do aplicativo e ter em mente que o mecanismo de armazenamento pode não ser totalmente seguro.

Use o tipo de token apropriado

GitHub Appss podem gerar tokens de acesso de instalação ou tokens de acesso do usuário para fazer solicitações de API autenticadas.

Os tokens de acesso à instalação atribuirão a atividade ao seu aplicativo. Elas são úteis para automações que atuam independentemente dos usuários.

Os tokens de acesso ao usuário atribuirão a atividade a um usuário e ao seu aplicativo. Elas são úteis para executar ações com base na entrada do usuário ou em nome de um usuário.

Um token de acesso de instalação é restrito com base nas permissões e no acesso do GitHub App. Um token de acesso do usuário é restrito com base na permissão e no acesso do GitHub App e na permissão e no acesso do usuário. Portanto, se o GitHub App executar uma ação em nome de um usuário, ele sempre deverá usar um token de acesso do usuário em vez de um token de acesso de instalação. Caso contrário, seu aplicativo pode permitir que um usuário veja ou faça coisas que não deve ser capaz de ver ou fazer.

O aplicativo nunca deve usar uma senha de personal access token ou GitHub para autenticação.

Autorizar de forma completa e duradoura

Depois de conectar um usuário, os desenvolvedores de aplicativos devem executar etapas adicionais para garantir que o usuário tenha acesso aos dados em seu sistema. Cada login requer novas verificações sobre suas associações, acesso e seu status de SSO atual.

Use o `id` durável e exclusivo para armazenar o usuário

Quando um usuário inicia uma sessão e faz ações em seu aplicativo, você precisa lembrar qual foi o usuário fez a ação para conceder a ele acesso aos mesmos recursos a próxima vez que ele iniciar uma sessão.

Para armazenar usuários em seu banco de dados corretamente, sempre use a id do usuário. Esse valor nunca é alterado para o usuário nem é usado para apontar para um usuário diferente, assim, garante que você esteja fornecendo acesso ao usuário pretendido. Você pode encontrar a id do usuário com o ponto de extremidade de API REST GET /user. Confira "Pontos de extremidade de API REST para usuários".

Se você armazenar referências a repositórios, organizações e empresas, também use a id deles para garantir que seus links para eles permaneçam exatos.

Nunca use identificadores que possam mudar ao longo do tempo, incluindo identificadores de usuário, slugs de organização ou endereços de email.

Validar o acesso da organização para cada nova autenticação

Ao usar um token de acesso do usuário, você deve acompanhar para quais organizações o token está autorizado. Se uma organização usar SSO SAML e um usuário não tiver feito SSO SAML, o token de acesso do usuário não terá acesso a essa organização. Você pode usar o ponto de extremidade da API REST GET /user/installations para verificar a quais organizações um token de acesso de usuário tem acesso. Se o usuário não estiver autorizado a acessar uma organização, você deverá impedir seu acesso aos dados pertencentes à organização dentro do seu aplicativo até que ele faça SSO SAML. Para obter mais informações, confira "Pontos de extremidade da API REST para instalações do GitHub App".

Armazenar dados do usuário com contextos organizacionais e corporativos

Além de rastrear a identidade do usuário por meio do campo id, você deve reter dados para a organização ou empresa em que cada usuário está operando. Isso ajudará a garantir que você não vaze informações confidenciais se um usuário mudar de função.

Por exemplo:

Um usuário está na organização Mona, que exige SSO SAML, e inicia uma sessão do seu aplicativo depois de executar o SSO. Seu aplicativo agora tem acesso a tudo o que o usuário faz dentro do Mona.
O usuário extrai um monte de código de um repositório em Mona e salva em seu aplicativo para análise.
Posteriormente, o usuário muda de cargo e é removido da organização Mona.

Quando o usuário acessar seu aplicativo, ele ainda poderá ver o código e a análise da organização Mona em sua conta de usuário?

Por isso é fundamental rastrear a origem dos dados que seu aplicativo está salvando. Se não, seu aplicativo é uma ameaça à proteção de dados das organizações, e há grande possibilidade de que seja banido se elas não puderem confiar que o aplicativo proteja corretamente os dados.

Expirar tokens

O GitHub incentiva fortemente você a usar tokens de acesso do usuário que expiram. Se você já recusou o uso de tokens de acesso do usuário que expiram, mas deseja habilitar esse recurso novamente, confira Ativando recursos opcionais para aplicativos do GitHub.

Os tokens de acesso à instalação expiram após uma hora, os tokens de acesso do usuário expiram após oito horas e os tokens de atualização expiram após seis meses. No entanto, você também pode revogar tokens assim que não precisar mais deles. Para obter mais informações, confira DELETE /installation/token para revogar um token de acesso de instalação e DELETE /applications/{client_id}/token para revogar um token de acesso de usuário.

Tokens de cache

Os tokens de acesso do usuário e de instalação devem ser usados até expirarem. Armazene em cache os tokens criados. Antes de criar um novo token, marque seu cache para ver se você já tem um token válido. A reutilização de tokens tornará o aplicativo mais rápido, porque ele fará menos solicitações para gerar tokens.

Criar um plano para lidar com violações de segurança

Você deve ter um plano em vigor para que possa lidar com quaisquer violações de segurança em tempo hábil.

Caso a chave privada ou o segredo do aplicativo seja comprometido, você precisará gerar uma nova chave ou segredo, atualizar seu aplicativo para usar a nova chave ou segredo e excluir sua chave ou segredo antigo.

Caso os tokens de acesso de instalação, tokens de acesso do usuário ou tokens de atualização sejam comprometidos, você deverá revogar imediatamente esses tokens. Para obter mais informações, confira DELETE /installation/token para revogar um token de acesso de instalação e DELETE /applications/{client_id}/token para revogar um token de acesso de usuário.

Realizar verificações de vulnerabilidade regulares

Você deve realizar verificações regulares de vulnerabilidade do aplicativo. Por exemplo, você pode configurar a verificação de código e a verificação de segredo no repositório que hospeda o código do aplicativo. Para obter mais informações, confira "Sobre a varredura de código" e "Sobre a verificação de segredo."

Escolher um ambiente apropriado

Se o aplicativo for executado em um servidor, verifique se o ambiente do servidor é seguro e se ele pode lidar com o volume de tráfego esperado para seu aplicativo.

Assine apenas os eventos de webhook de que seu aplicativo precisa. Isso ajudará a reduzir a latência, pois seu aplicativo não receberá conteúdos de que não precisa.

Usar um segredo de webhook

Você deve definir um segredo de webhook para seus dados do GitHub App e verificar se a assinatura de eventos de webhook de entrada correspondem ao segredo. Isso ajuda a garantir que o evento de webhook de entrada seja um evento válido de GitHub.

Para saber mais, confira Usar webhooks com aplicativos GitHub. Para ver um exemplo, confira Criar um Aplicativo GitHub que responde a eventos de webhook.

Permitir tempo para os usuários aceitarem novas permissões

Quando você adiciona permissões de repositório ou organização aos seus dados do GitHub App, os usuários que têm o aplicativo instalado na sua conta pessoal ou da organização receberão um email solicitando que revisem as novas permissões. Até que o usuário aprove as novas permissões, a instalação do aplicativo receberá apenas as permissões antigas.

Ao atualizar as permissões, torne seu aplicativo compatível com versões anteriores para dar aos usuários tempo para aceitar as novas permissões. Você pode usar o webhook de instalação com a new_permissions_accepted propriedade de ação para saber quando os usuários aceitam novas permissões para seu aplicativo.

Usar serviços de maneira segura

Se o aplicativo usar serviços de terceiros, isso deverá ocorrer de maneira segura:

todos os serviços usados pelo aplicativo devem ter um logon exclusivo e uma senha.
Os aplicativos não devem compartilhar contas de serviço como, por exemplo, e-mail ou serviços de banco de dados para gerenciar seu serviço de SaaS.
Somente os funcionários com funções administrativas devem ter acesso de administrador à infraestrutura que hospeda o aplicativo.

Adicionar log e monitoramento

Considere adicionar funcionalidades de log e monitoramento no aplicativo. Um log de segurança pode incluir:

Eventos de autenticação e autorização
Alterações na configuração do serviço
Leitura e gravação de objetos
Alterações de permissão de usuário e grupo
Elevação do papel para administrador

Os logs devem usar carimbos de data/hora consistentes para cada evento e registrar usuários, endereços IP ou nomes de host de todos os eventos registrados.

Habilitar a exclusão de dados

Se o GitHub App estiver disponível para outros usuários ou organizações, você deverá fornecer aos usuários e proprietários da organização uma maneira de excluir os dados deles. Os usuários não devem precisar enviar um email ou chamar uma pessoa de suporte para excluir os dados.