Configura el inicio de sesión social con GitHub

Integra la aplicación OAuth de GitHub para habilitar el inicio de sesión con GitHub, vinculación de cuentas y acceso seguro a las API de GitHub.

tip:

Esta guía asume que tienes un entendimiento básico de los Conectores de Logto. Para aquellos que no están familiarizados, por favor consulta la guía de Conectores para comenzar.

Comenzar

El conector de GitHub permite la integración OAuth 2.0 para que tu aplicación pueda:

• Añadir autenticación "Iniciar sesión con GitHub"
• Vincular cuentas de usuario con identidades de GitHub
• Sincronizar la información del perfil de usuario desde GitHub
• Acceder a las API de GitHub mediante el almacenamiento seguro de tokens en Logto Secret Vault para tareas de automatización (por ejemplo, crear incidencias en GitHub, gestionar repositorios desde tu aplicación)

Para configurar estas funciones de autenticación, primero crea un conector de GitHub en Logto:

1. Ve a Consola de Logto > Conector > Conector social.
2. Haz clic en Agregar conector social, selecciona GitHub, haz clic en Siguiente y sigue el tutorial paso a paso para completar la integración.

Paso 1: Crea una aplicación OAuth en GitHub

Antes de poder usar GitHub como proveedor de autenticación, debes crear una aplicación OAuth en GitHub para obtener credenciales de OAuth 2.0.

1. Ve a GitHub e inicia sesión con tu cuenta, o crea una nueva si es necesario.
2. Navega a Settings > Developer settings > OAuth apps.
3. Haz clic en New OAuth App para registrar una nueva aplicación:
   • Application name: Ingresa un nombre descriptivo para tu aplicación.
   • Homepage URL: Ingresa la URL de la página principal de tu aplicación.
   • Authorization callback URL: Copia el Callback URI de tu conector de GitHub en Logto y pégalo aquí. Después de que los usuarios inicien sesión con GitHub, serán redirigidos aquí con un código de autorización que Logto utiliza para completar la autenticación.
   • Application description: (Opcional) Agrega una breve descripción de tu aplicación.
4. Haz clic en Register application para crear la aplicación OAuth.

nota:

Sugerimos no marcar la casilla Enable Device Flow, ya que los usuarios que inicien sesión con GitHub en dispositivos móviles tendrían que confirmar la acción inicial de inicio de sesión en la aplicación móvil de GitHub. Muchos usuarios de GitHub no instalan la aplicación móvil de GitHub en sus teléfonos, lo que podría bloquear el flujo de inicio de sesión. Solo habilita esto si esperas que los usuarios finales confirmen su flujo de inicio de sesión a través de la aplicación móvil de GitHub. Consulta los detalles sobre el device flow.

Para más detalles sobre cómo configurar aplicaciones OAuth en GitHub, consulta Creating an OAuth App.

Paso 2: Configura tu conector de Logto

Después de crear la aplicación OAuth en GitHub, serás redirigido a una página de detalles donde podrás copiar el Client ID y generar un Client secret.

1. Copia el Client ID de tu aplicación OAuth de GitHub y pégalo en el campo clientId en Logto.
2. Haz clic en Generate a new client secret en GitHub para crear un nuevo secreto, luego cópialo y pégalo en el campo clientSecret en Logto.
3. Haz clic en Save and Done en Logto para conectar tu sistema de identidad con GitHub.

aviso:

Mantén tu Client secret seguro y nunca lo expongas en código del lado del cliente. Los client secrets de GitHub no se pueden recuperar si se pierden; tendrás que generar uno nuevo.

Paso 3: Configura los alcances (Scopes) (Opcional)

Los alcances (Scopes) definen los permisos que tu aplicación solicita a los usuarios y controlan a qué datos puede acceder tu aplicación desde sus cuentas de GitHub.

Utiliza el campo Scopes en Logto para solicitar permisos adicionales a GitHub. Elige uno de los siguientes enfoques según tus necesidades:

Opción 1: No se necesitan alcances de API adicionales

• Deja el campo Scopes en tu conector de GitHub en Logto en blanco.
• Se solicitará el alcance predeterminado read:user para asegurar que Logto pueda obtener correctamente la información básica del usuario (por ejemplo, correo electrónico, nombre, avatar).

Opción 2: Solicitar alcances adicionales al iniciar sesión

• Consulta todos los alcances de GitHub para aplicaciones OAuth disponibles y agrega solo los que tu aplicación necesite.
• Ingresa todos los alcances deseados en el campo Scopes, separados por espacios.
• Cualquier alcance que listes aquí sobrescribe los valores predeterminados, así que siempre incluye el alcance de autenticación: read:user.
• Alcances adicionales comunes incluyen:
  • repo: Control total de repositorios privados
  • public_repo: Acceso a repositorios públicos
  • user:email: Acceso a direcciones de correo electrónico del usuario
  • notifications: Acceso a notificaciones
• Asegúrate de que todos los alcances estén escritos correctamente y sean válidos. Un alcance incorrecto o no soportado resultará en un error de "Invalid scope" por parte de GitHub.

Opción 3: Solicitar alcances incrementales más adelante

• Después de que el usuario inicie sesión, puedes solicitar alcances adicionales bajo demanda reiniciando un flujo de autorización social federado y actualizando el conjunto de tokens almacenados del usuario.
• Estos alcances adicionales no necesitan ser rellenados en el campo Scopes de tu conector de GitHub en Logto, y pueden lograrse a través de la Social Verification API de Logto.

Siguiendo estos pasos, tu conector de GitHub en Logto solicitará exactamente los permisos que tu aplicación necesita, ni más ni menos.

tip:

Si tu aplicación solicita estos alcances para acceder a la API de GitHub y realizar acciones, asegúrate de habilitar Store tokens for persistent API access en el conector de GitHub de Logto. Consulta la siguiente sección para más detalles.

Paso 4: Configuración general

Aquí tienes algunas configuraciones generales que no bloquearán la conexión con GitHub pero pueden afectar la experiencia de autenticación del usuario final.

Sincronizar información de perfil

En el conector de GitHub, puedes establecer la política para sincronizar la información de perfil, como nombres de usuario y avatares. Elige entre:

• Solo sincronizar al registrarse: La información del perfil se obtiene una vez cuando el usuario inicia sesión por primera vez.
• Siempre sincronizar al iniciar sesión: La información del perfil se actualiza cada vez que el usuario inicia sesión.

Almacenar tokens para acceder a las APIs de GitHub (Opcional)

Si deseas acceder a las APIs de GitHub y realizar acciones con autorización del usuario (ya sea mediante inicio de sesión social o vinculación de cuentas), Logto necesita obtener alcances de API específicos y almacenar los tokens.

1. Agrega los alcances requeridos siguiendo las instrucciones anteriores.
2. Habilita Store tokens for persistent API access en el conector de GitHub de Logto. Logto almacenará de forma segura los tokens de acceso de GitHub en el Secret Vault.

nota:

Cuando usas una OAuth App de GitHub como se describe en este tutorial, no puedes obtener un refresh token de GitHub porque su access token no expira a menos que el usuario lo revoque manualmente. Por lo tanto, no necesitas agregar offline_access en el campo Scopes; hacerlo puede causar un error.

Si deseas que el access token expire o usar refresh tokens, considera integrar con una GitHub App en su lugar. Aprende sobre las diferencias entre GitHub Apps y OAuth Apps.

Paso 5: Prueba tu integración (Opcional)

Antes de lanzar, prueba tu integración con GitHub:

1. Usa el conector en un tenant de desarrollo de Logto.
2. Verifica que los usuarios puedan iniciar sesión con GitHub.
3. Comprueba que se estén solicitando los alcances correctos.
4. Prueba las llamadas a la API si estás almacenando tokens.

Las aplicaciones OAuth de GitHub funcionan con cualquier cuenta de usuario de GitHub de inmediato; no es necesario crear usuarios de prueba ni aprobar la aplicación como en otras plataformas.

Utiliza el conector de GitHub

Una vez que hayas creado un conector de GitHub y lo hayas conectado a GitHub, puedes incorporarlo en tus flujos de usuario final. Elige las opciones que se adapten a tus necesidades:

Habilitar "Iniciar sesión con GitHub"

1. En la Consola de Logto, ve a Experiencia de inicio de sesión > Registro e inicio de sesión.
2. Agrega el conector de GitHub en la sección Inicio de sesión social para permitir que los usuarios se autentiquen con GitHub.

Aprende más sobre la experiencia de inicio de sesión social.

Vincular o desvincular una cuenta de GitHub

Utiliza la Account API para construir un Centro de Cuenta personalizado en tu aplicación que permita a los usuarios autenticados vincular o desvincular su cuenta de GitHub. Sigue el tutorial de Account API

tip:

Se permite habilitar el conector de GitHub solo para vinculación de cuentas y acceso a API, sin habilitarlo para el inicio de sesión social.

Acceder a las API de GitHub y realizar acciones

Tu aplicación puede recuperar los tokens de acceso de GitHub almacenados en el Secret Vault para llamar a las API de GitHub y automatizar tareas de backend (por ejemplo, crear incidencias, gestionar repositorios o automatizar flujos de trabajo). Consulta la guía sobre cómo recuperar tokens almacenados para el acceso a API.

Gestionar la identidad de GitHub del usuario

Después de que un usuario vincule su cuenta de GitHub, los administradores pueden gestionar esa conexión en la Consola de Logto:

1. Navega a Consola de Logto > Gestión de usuarios y abre el perfil del usuario.
2. En Conexiones sociales, localiza el elemento de GitHub y haz clic en Gestionar.
3. En esta página, los administradores pueden gestionar la conexión de GitHub del usuario, ver toda la información de perfil otorgada y sincronizada desde su cuenta de GitHub, y comprobar el estado del token de acceso.

nota:

La respuesta del token de acceso de GitHub no incluye la información específica de los alcances (scope), por lo que Logto no puede mostrar directamente la lista de permisos otorgados por el usuario. Sin embargo, siempre que el usuario haya consentido los alcances solicitados durante la autorización, tu aplicación tendrá los permisos correspondientes al acceder a la API de GitHub.

Referencia

Documentación para desarrolladores de GitHub - Acerca de las aplicaciones

Documentación para desarrolladores de GitHub - Crear una aplicación OAuth

Documentación de alcances para aplicaciones OAuth de GitHub