Procedimientos recomendados para crear una aplicación de GitHub

Selección de los permisos mínimos necesarios

Al registrar una instancia de GitHub App, selecciona los permisos mínimos que necesitará la GitHub App. Si alguna clave o tokens de la aplicación está en peligro, con esto se limitará la cantidad de daños que pueden producirse. Para más información sobre cómo seleccionar los permisos, consulta "Elección de permisos para una aplicación de GitHub".

Cuando la instancia de GitHub App crea un token de acceso de instalación o un token de acceso de usuario, puedes limitar aún más los repositorios a los que la aplicación puede acceder y los permisos que tiene el token. Para obtener más información, vea «Generación de un token de acceso de instalación para una aplicación de GitHub» y «Generación de un token de acceso de usuario para una aplicación de GitHub».

Mantenerse por debajo del límite de frecuencia

Suscríbete a eventos de webhook en lugar de sondear la API para obtener datos. Esto ayudará a que GitHub App permanezca dentro del límite de frecuencia de la API. Para obtener más información, vea «Uso de webhooks con aplicaciones de GitHub» y «Creación de una aplicación de GitHub que responda a eventos de webhook».

Considera la posibilidad de usar solicitudes condicionales para ayudar a mantenerte dentro del límite de frecuencia. Para más información sobre las solicitudes condicionales, consulta "Procedimientos recomendados para usar la API de REST".

Si es posible, considera la posibilidad de usar consultas consolidadas de GraphQL en lugar de solicitudes de API REST como ayuda para mantenerte dentro de los límites de frecuencia. Para obtener más información, vea «Comparación de la API REST de GitHub y la API de GraphQL» y «Documentación de GraphQL API para GitHub».

Si alcanzas un límite de frecuencia y necesitas reintentar una solicitud de API, usa los encabezados de respuesta x-ratelimit-reset o Retry-After. Si estos encabezados no están disponibles, espera una cantidad de tiempo exponencialmente creciente entre reintentos y genera un error después de un número específico de reintentos. Para obtener más información, vea «Procedimientos recomendados para usar la API de REST».

Protección de las credenciales de la aplicación

Puedes generar una clave privada y un secreto de cliente para tu instancia de GitHub App. Con estas credenciales, la aplicación puede generar tokens de acceso de instalación, tokens de acceso de usuario y tokens de actualización. Estos tokens se pueden usar para realizar solicitudes de API en nombre de una instalación o usuario de la aplicación.

Debes almacenar estas credenciales de forma segura. El mecanismo de almacenamiento depende de la arquitectura de las integraciones y de la plataforma en la que se ejecuta. Por lo general, debes usar un mecanismo de almacenamiento pensado para almacenar datos confidenciales en la plataforma que estés usando.

Claves privadas

La clave privada de GitHub App concede acceso a cada cuenta en la que está instalada la aplicación.

Considera la posibilidad de almacenar la clave privada de GitHub App en un almacén de claves, como Azure Key Vault, y convertirlo en solo firma.

Como alternativa, la clave se puede almacenar como una variable de entorno. No obstante, esto no es tan seguro como hacerlo en un almacén de claves. Si un atacante obtiene acceso al entorno, puede leer la clave privada y obtener autenticación persistente como GitHub App.

No deberías codificar la clave privada de forma rígida en la aplicación, incluso si el código se almacena en un repositorio privado. Si la aplicación es un cliente nativo, una aplicación del lado cliente o se ejecuta en un dispositivo de usuario (en lugar de ejecutarse en los servidores), nunca debe enviar la clave privada con la aplicación.

No debes generar más claves privadas de las que necesitas. Debes eliminar las claves privadas que ya no necesites. Para obtener más información, vea «Administración de claves privadas para aplicaciones de GitHub».

Secretos de cliente

Los secretos de cliente se usan para generar tokens de acceso de usuario para la aplicación, a menos que la aplicación use el flujo de dispositivo. Para obtener más información, vea «Generación de un token de acceso de usuario para una aplicación de GitHub».

Si la aplicación es un sitio web o una aplicación web, considera la posibilidad de almacenar el secreto de cliente en un almacén de claves como Azure Key Vault, o como una variable de entorno cifrada o un secreto en el servidor.

Si la aplicación es un cliente nativo, una aplicación del lado cliente o se ejecuta en un dispositivo de usuario (en lugar de ejecutarse en los servidores), no puedes proteger el secreto de cliente. Debes tener cuidado si planeas acceder a tus propios servicios en función de los tokens generados por la aplicación, ya que cualquier usuario puede acceder al secreto de cliente para generar un token.

Tokens de acceso de instalación, tokens de acceso de usuario y tokens de actualización

Los tokens de acceso de instalación se usan para realizar solicitudes de API en nombre de una instalación de la aplicación. Los tokens de acceso de usuario se usan para realizar solicitudes de API en nombre de un usuario. Los tokens de actualización se usan para regenerar los tokens de acceso de usuario. La aplicación puede usar su clave privada para generar un token de acceso de instalación. La aplicación puede usar su secreto de cliente para generar un token de acceso de usuario y un token de actualización.

Si la aplicación es un sitio web o una aplicación web, debes cifrar los tokens en el back-end y garantizar que haya seguridad en los sistemas que pueden acceder a los tokens. Considere la posibilidad de almacenar tokens de actualización en un lugar independiente de los tokens de acceso activos.

Si la aplicación es un cliente nativo, aplicación del lado cliente o se ejecuta en un dispositivo de usuario (en lugar de ejecutarse en tus servidores), es posible que no puedas proteger los tokens igual de bien que en una aplicación que se ejecuta en los servidores. No debes generar tokens de acceso de instalación, ya que esto requiere una clave privada. En su lugar, debes generar tokens de acceso de usuario. Debes almacenar tokens a través del mecanismo recomendado para la plataforma de la aplicación y tener en cuenta que es posible que el mecanismo de almacenamiento no sea totalmente seguro.

Uso del tipo de token adecuado

Las GitHub Apps pueden generar tokens de acceso de instalación o tokens de acceso de usuario para realizar solicitudes de API autenticadas.

Los tokens de acceso de instalación atribuirán la actividad a la aplicación. Son útiles para las automatizaciones que actúan independientemente de los usuarios.

Los tokens de acceso de usuario atribuirán la actividad a un usuario y a la aplicación. Estos son útiles para realizar acciones basadas en entradas del usuario o en nombre de un usuario.

Un token de acceso de instalación está restringido en función de los permisos y el acceso de GitHub App. Un token de acceso de usuario está restringido en función de los permisos y el acceso de GitHub App y el permiso y el acceso de usuarios. Por lo tanto, si GitHub App realiza una acción en nombre de un usuario, siempre deberá usar un token de acceso de usuario en lugar de un token de acceso de instalación. De lo contrario, la aplicación podría permitir a un usuario ver o hacer cosas que no debería.

La aplicación nunca debe usar una contraseña de personal access token o GitHub para autenticarse.

Autorización exhaustiva y duradera

Después de iniciar sesión en un usuario, los desarrolladores de aplicaciones deben realizar pasos adicionales para asegurarse de que el usuario está pensado para tener acceso a los datos del sistema. Cada inicio de sesión requiere comprobaciones nuevas en torno a sus pertenencias, acceso y su estado actual de SSO.

Uso del `id` durable y único para almacenar el usuario

Cuando un usuario inicia sesión y realiza acciones en la aplicación, debe recordar qué usuario realizó esa acción para concederles acceso a los mismos recursos la próxima vez que inicien sesión.

Para almacenar los usuarios en la base de datos correctamente, use siempre el id del usuario. Este valor nunca cambiará para el usuario o se usará para que apunte a otro usuario, por lo que garantiza que proporciona acceso al usuario correcto. Puedes encontrar el id de un usuario con el punto de conexión de la API de REST GET /user. Consulte "Puntos de conexión de la API de REST para usuarios".

Si almacena referencias a repositorios, organizaciones y empresas, use también sus id para asegurarse de que los vínculos a ellos sigan siendo precisos.

Nunca use identificadores que puedan cambiar con el tiempo, incluidos los identificadores de usuario, los campos de datos dinámicos de la organización o las direcciones de correo electrónico.

Validación del acceso de la organización para cada nueva autenticación

Cuando uses un token de acceso de usuario, debes realizar un seguimiento de las organizaciones para las que está autorizado el token. Si una organización usa el inicio de sesión único de SAML y un usuario no lo ha realizado, el token de acceso de usuario no tendrá acceso a esa organización. Puedes usar el punto de conexión de la API REST de GET /user/installations para comprobar a qué organizaciones tiene acceso un token de acceso de usuario. Si el usuario no está autorizado a acceder a una organización, debe impedir su acceso a los datos propiedad de la organización dentro de su propia aplicación hasta que realice el SSO de SAML. Para obtener más información, vea «Puntos de conexión de la API de REST para instalaciones de GitHub Apps».

Almacenamiento de datos de usuario con contextos organizativos y empresariales

Además del seguimiento de la identidad de usuario a través del campo id, debe conservar los datos de la organización o de la empresa en la que cada usuario está funcionando. Esto le ayudará a asegurarse de que no filtre información confidencial si un usuario cambia los roles.

Por ejemplo:

Un usuario está en la organización Mona, que requiere el inicio de sesión único de SAML e inicia sesión en la aplicación después de realizar el inicio de sesión único. La aplicación ahora tiene acceso a lo que haga el usuario dentro de Mona.
El usuario extrae un montón de código de un repositorio en Mona y lo guarda en la aplicación para su análisis.
Más adelante, el usuario cambia los trabajos y se quita de la organización Mona.

Cuando el usuario accede a la aplicación, ¿puede ver el código y el análisis de la organización Mona en su cuenta de usuario?

Este es el motivo por el que es fundamental realizar un seguimiento del origen de los datos que guarda la aplicación. De lo contrario, la aplicación es una amenaza de protección de datos para las organizaciones y es probable que prohibieran la aplicación si no pueden confiar en que la aplicación protege correctamente sus datos.

Expiración de los tokens

GitHub recomienda encarecidamente que uses tokens de acceso de usuario que expiren. Si anteriormente has optado por no participar en el uso de tokens de acceso de usuario que expiran, pero quieres volver a habilitar esta característica, consulta "Activación de características opcionales para Aplicaciones de GitHub".

Los tokens de acceso de instalación expiran después de una hora, los tokens de acceso de usuario después de ocho horas y los de actualización después de seis meses. Sin embargo, también puedes revocar los tokens tan pronto como ya no los necesites. Para más información, consulta "DELETE /installation/token" para revocar un token de acceso de instalación y "DELETE /applications/{client_id}/token" para revocar uno de acceso de usuario.

Almacenamiento de tokens en caché

Los tokens de acceso de usuario y los tokens de acceso de instalación están diseñados para usarse hasta que expiren. Debes almacenar en caché los tokens que crees. Antes de crear un nuevo token, comprueba la memoria caché para ver si ya tiene un token válido. La reutilización de tokens hará que la aplicación sea más rápida, ya que realizará menos solicitudes para generar tokens.

Creación de un plan para controlar infracciones de seguridad

Debes tener un plan implementado para poder controlar las infracciones de seguridad de forma oportuna.

En caso de que la clave privada o el secreto de la aplicación estén en peligro, deberás generar una nueva clave o secreto, actualizar la aplicación para que use la nueva clave o secreto y eliminar la clave o el secreto antiguos.

En caso de que los tokens de acceso de instalación, de acceso de usuario o de actualización estén en peligro, debes revocar inmediatamente estos tokens. Para más información, consulta "DELETE /installation/token" para revocar un token de acceso de instalación y "DELETE /applications/{client_id}/token" para revocar uno de acceso de usuario.

Realización de exámenes de vulnerabilidades normales

Debes realizar exámenes de vulnerabilidades regulares para la aplicación. Por ejemplo, puedes configurar el examen de código y el examen de secretos para el repositorio que hospeda el código de la aplicación. Para obtener más información, vea «Acerca del examen de código» y «Acerca del examen de secretos».

Elección de un entorno adecuado

Si la aplicación se ejecuta en un servidor, comprueba que el entorno del servidor es seguro y que puedes controlar el volumen de tráfico esperado de la aplicación.

Suscríbete solo a los eventos de webhook que necesita la aplicación. Esto ayudará a reducir la latencia, ya que la aplicación no recibirá cargas que no necesite.

Uso de un secreto de webhook

Debes establecer un secreto de webhook para la GitHub App y comprobar que la firma de los eventos de webhook entrantes coincide con el secreto. Esto ayuda a garantizar que el evento de webhook entrante es un evento de GitHub válido.

Para obtener más información, vea «Uso de webhooks con aplicaciones de GitHub». Para obtener un ejemplo, consulta "Creación de una aplicación de GitHub que responda a eventos de webhook".

Permitir un tiempo para que los usuarios acepten nuevos permisos

Cuando agregues permisos de repositorio u organización a GitHub App, los usuarios que tengan la aplicación instalada en su cuenta personal u organización recibirán un correo electrónico en el que se les pedirá que revisen los nuevos permisos. Hasta que el usuario apruebe los nuevos permisos, la instalación de la aplicación solo recibirá los permisos antiguos.

Cuando actualices los permisos, debes considerar la posibilidad de que la aplicación sea compatible con versiones anteriores para conceder a los usuarios tiempo para aceptar los nuevos permisos. Puedes usar el webhook de instalación con la propiedad de acción new_permissions_accepted para conocer cuándo aceptan los usuarios los nuevos permisos de la aplicación.

Uso de servicios de forma segura

Si la aplicación usa servicios de terceros, se deben usar de forma segura:

Los servicios usados por la aplicación deben tener un inicio de sesión y una contraseña únicos.
Las apps no deben compartir cuentas de servicio tales como servicios de correo electrónico o de bases de datos para administrar tu servicio SaaS.
Solo los empleados con tareas administrativas deben tener acceso de administrador a la infraestructura que hospeda la aplicación.

Adición del registro y supervisión

Considere la posibilidad de agregar funcionalidades de registro y supervisión para la aplicación. Un registro de seguridad debería incluir:

Eventos de autenticación y autorización
Cambios a la configuración del servicio
Escritura y lectura de objetos
Los cambios de permisos de usuarios y grupos
Elevación de rol a aquel de administrador

Los registros deben usar marcas de tiempo coherentes para cada evento y registrar los usuarios, las direcciones IP o los nombres de host de todos los eventos registrados.

Habilitación para la eliminación de datos

Si la GitHub App está disponible para otros usuarios u organizaciones, debes proporcionar a los usuarios y a los propietarios de la organización una manera de eliminar sus datos. Los usuarios no deben tener que enviar un correo electrónico ni llamar a una persona de soporte técnico para eliminar sus datos.