Migrar aplicativos OAuth para aplicativos

Os Apps são a maneira recomendada de se integrar ao . Apps oferecem muitas vantagens sobre OAuth apps, incluindo:

• Recursos de segurança aprimorados, como permissões refinadas, escolha sobre o acesso ao repositório e tokens de curta duração
• A capacidade de agir de maneira independente de um usuário ou em nome dele
• Limites de taxa escalonáveis
• Webhooks internos

Para saber mais, confira Sobre a criação de Aplicativos do .

As etapas a seguir fornecem uma visão geral de como migrar de um OAuth app para um App. As etapas específicas dependem do aplicativo.

Familiarize-se novamente com o código do OAuth app. As solicitações de API que o OAuth app faz ajudarão você a decidir as permissões que devem ser selecionadas para o App.

Além disso, há alguns pontos de extremidade da API REST que não estão disponíveis para os OAuth apps. Verifique se todos os pontos de extremidade REST que você usa estão disponíveis para os Apps examinando Pontos de extremidade disponíveis para tokens de acesso de instalação do aplicativo .

Registre um novo App. Para saber mais, confira Registrar um Aplicativo .

Em comparação com um OAuth app, você tem mais controle sobre as configurações do App. Algumas das principais adições são:

• Ao contrário de um OAuth app, que sempre age em nome de um usuário, você pode fazer com que o App execute ações como si mesmo ou em nome de um usuário. Se você não quiser que o novo App execute ações em nome de um usuário, ignore as configurações "Identificação e autorização de usuários". Para saber mais, confira Sobre a autenticação com um App.

• Use webhooks para notificar o App quando ocorrerem eventos específicos. Ao contrário dos webhooks dos OAuth apps, que você precisa configurar por meio da API para cada repositório ou organização, os webhooks são integrados aos Apps. Ao registrar seu App, você pode selecionar os eventos de webhook que deseja receber. Além disso, se atualmente o OAuth app usar a sondagem para determinar se um evento ocorreu, considere a possibilidade de assinar webhooks para ajudar seu App a permanecer dentro do limite de taxa. Para saber mais, confira Usar webhooks com aplicativos .

• Com um OAuth app, você solicita escopos quando um usuário autoriza seu aplicativo. Com um App, você especifica permissões nas configurações do aplicativo. Essas permissões são mais granulares do que os escopos e permitem que você selecione apenas as permissões de que seu aplicativo precisa. Além disso, essas permissões são mapeadas para pontos de extremidade da API REST e eventos de webhook, para que você possa determinar com facilidade as permissões que o App precisa para acessar um ponto de extremidade específico da API REST ou assinar um webhook específico. No momento, as permissões não estão documentadas para solicitações do GraphQL. Para saber mais, confira Escolhendo permissões para um Aplicativo .

Depois de registrar um App, adapte o código do OAuth app antigo para trabalhar com o novo App.

Você precisará atualizar o código do aplicativo para lidar com a autenticação de API para o App. Um App pode ser autenticado de três maneiras:

• Como o próprio aplicativo, para obter ou modificar detalhes sobre o registro do App ou para criar um token de acesso de instalação. Para saber mais, confira Efetuar autenticação como um aplicativo .
• Como uma instalação de aplicativo, para executar ações em nome de si mesmo. Para saber mais, confira Como autenticar como uma instalação de Aplicativo .
• Em nome de um usuário, para atribuir ações a um usuário. Para saber mais, confira Autenticação com um aplicativo em nome de um usuário.

Se você estiver usando a biblioteca oficial do Octokit.js do , use o objeto interno App para autenticar. Para obter exemplos, confira Scripts com a API REST e o JavaScript e Criar um Aplicativo que responde a eventos de webhook.

Confira as diferenças de limites de taxa entre os OAuth apps e os Apps. Os Apps usam regras deslizantes para limites de taxa, que podem aumentar de acordo com o número de repositórios e de usuários na organização. Para saber mais, confira Limites de taxa para aplicativos .

Se possível, considere o uso de solicitações condicionais e a possibilidade de assinar webhooks em vez de sondagem para ajudar você a permanecer dentro dos limites de taxa. Para obter mais informações sobre as solicitações condicionais, confira Práticas recomendadas para usar a API REST. Para obter mais informações sobre como usar webhooks com o App, confira Usar webhooks com aplicativos e Criar um Aplicativo que responde a eventos de webhook.

Teste o novo App para verificar se o código funciona conforme o esperado.

Se você quiser que outras contas possam usar seu novo App, verifique se o aplicativo é público.Para obter mais informações, confira Tornar um aplicativo do público ou privado.

Depois que o novo App estiver pronto, instrua os usuários do OAuth app antigo a migrar para o novo App. Não há uma forma de migrar automaticamente os usuários. Cada usuário precisa instalar e/ou autorizar seu App por conta própria.

Como proprietário do aplicativo, você deve incluir chamadas à ação para incentivar os usuários a instalar/autorizar o novo App e revogar a autorização para o OAuth app antigo. Você também deve atualizar qualquer documentação ou elementos de interface do usuário.

Se você desejar que o App faça solicitações de API em nome próprio ou acesse recursos da organização ou do repositório, o usuário precisará instalar o App. Quando um usuário instala um App na respectiva conta ou organização, ele escolhe quais repositórios o aplicativo pode acessar e concede ao aplicativo as permissões de organização e repositório solicitadas.

Para ajudar os usuários a instalar o App, adicione um link à página da Web do aplicativo em que os usuários podem clicar para instalar o App. O formato da URL de instalação é http(s)://HOSTNAME/-apps/YOUR_APP_NAME/installations/new. Substitua YOUR_APP_NAME pelo nome do slug do seu App, que você pode encontrar no campo "Link público" na página de configurações do App.

Para selecionar previamente todos os repositórios aos quais seu OAuth app teve acesso, acrescente /permissions e consulte parâmetros à URL de instalação. Isso ajuda os usuários a permitir acesso ao App nos repositórios aos quais o OAuth app já têm acesso. Os parâmetros de consulta são:

• suggested_target_id: a ID do usuário ou da organização que está instalando seu App. Este parâmetro é necessário.
• repository_ids[]: as IDs do repositório a serem selecionadas para a instalação. Se isso for omitido, todos os repositórios serão selecionados. O número máximo de repositórios que pode ser pré-selecionado é 100. Para ver a lista de repositórios aos quais o OAuth app tem acesso, use os pontos de extremidade Listar os repositórios do usuário autenticado e Listar os repositórios da organização.

Por exemplo: http(s)://HOSTNAME/-apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.

Para obter mais informações sobre como instalar os Apps, confira Instalando um Aplicativo de terceiros e Instalando seu próprio Aplicativo .

Se você quiser que o App faça solicitações de API em nome de um usuário, o usuário precisará autorizar o aplicativo. Quando um usuário autoriza um aplicativo, ele concede ao aplicativo permissão para agir no nome dele e concede as permissões de conta solicitadas pelo aplicativo. Se o aplicativo estiver instalado em uma conta da organização, cada usuário dessa organização precisará autorizar o aplicativo para que o aplicativo aja no respectivo nome.

Para solicitar aos usuários que autorizem seu aplicativo, você os conduzirá pelo fluxo do aplicativo Web ou pelo fluxo do dispositivo. Para saber mais, confira Como gerar um token de acesso do usuário para um App.

Para obter mais informações sobre como autorizar Apps, confira Autorizando aplicativos .

Você também deve incentivar os usuários a revogar o acesso ao OAuth app antigo. Isso ajudará você a descontinuar o uso por completo do OAuth app e ajudará a manter os dados dos usuários em segurança. Para saber mais, confira Revisar aplicativos OAuth autorizados.

Você deve atualizar qualquer interface do usuário ou documentação relacionada ao seu aplicativo para refletir a mudança de um OAuth app para um App.

Quando um usuário instala seu App e permite acesso a um repositório, você deve remover todos os webhooks do OAuth app antigo. Se o novo App e o OAuth app antigo responderem a webhooks para o mesmo evento, o usuário poderá observar um comportamento duplicado.

Para remover webhooks do repositório, escute o webhook installation_repositories com a ação added. Quando o App receber esse evento, você poderá usar a API REST para excluir o webhook nesses repositórios do OAuth app. Para saber mais, confira Eventos e cargas de webhook e Pontos de extremidade da API REST para webhooks de repositório.

Da mesma forma, para remover webhooks da organização, escute o webhook installation com a ação created. Quando o App recebe esse evento para uma organização, você pode usar a API REST para excluir o webhook nessa organização e os repositórios correspondentes do OAuth app. Para saber mais, confira Eventos e cargas de webhook, Pontos de extremidade de API REST para webhooks da organização e Pontos de extremidade da API REST para webhooks de repositório.

Depois que os usuários migrarem para o novo App, você deverá excluir o OAuth app antigo. Isso ajudará a evitar o abuso das credenciais do OAuth app. Essa ação também revogará todas as autorizações restantes do OAuth app. Para saber mais, confira Excluir um aplicativo OAuth. Caso o OAuth app esteja listado no Marketplace, talvez seja necessário entrar em contato com o Suporte do para remover seu aplicativo do marketplace primeiro.