Tutorial SpringBoot: Autenticación OAuth con GitHub

Crear una GitHub OAuth App

Para implementar autenticación OAuth con GitHub en nuestra aplicación Spring Boot, el primer paso es registrar nuestra aplicación en GitHub como una OAuth App. Este proceso nos proporcionará las credenciales necesarias que GitHub utilizará para identificar y autorizar nuestra aplicación.

Acceso al panel de configuración

Inicia sesión en tu cuenta de GitHub y navega hasta la configuración de desarrollador. Puedes acceder directamente desde tu perfil haciendo clic en Settings > Developer settings > OAuth Apps, o visitando directamente la URL https://github.com/settings/developers.

Una vez en la sección de OAuth Apps, encontrarás un botón "New OAuth App" que te permitirá crear una nueva aplicación.

Configuración de la OAuth App

Al crear una nueva OAuth App, GitHub te solicitará varios campos obligatorios que definen cómo interactuará tu aplicación con el servicio de autenticación:

Application name: Introduce un nombre descriptivo para tu aplicación, como "Mi App Spring Boot" o "Sistema de Gestión OAuth". Este nombre será visible para los usuarios durante el proceso de autorización.

Homepage URL: Especifica la URL principal de tu aplicación. Para desarrollo local, utiliza http://localhost:8080. En producción, será la URL real de tu aplicación desplegada.

Application description: Aunque es opcional, es recomendable incluir una breve descripción de tu aplicación para que los usuarios entiendan qué servicio están autorizando.

Authorization callback URL: Este es el campo más crítico de la configuración. Aquí debes especificar la URL a la que GitHub redirigirá al usuario después de completar la autenticación. Para Spring Boot con OAuth2, la URL sigue un patrón específico:

http://localhost:8080/login/oauth2/code/github

Esta URL está compuesta por:

• http://localhost:8080: La base de tu aplicación
• /login/oauth2/code/: El endpoint estándar de Spring Security OAuth2
• github: El identificador del proveedor OAuth que configuraremos en Spring Boot

Obtención de credenciales

Una vez completado el formulario y creada la aplicación, GitHub te proporcionará dos elementos fundamentales:

Client ID: Un identificador público único para tu aplicación. Este valor no es secreto y puede ser visible en el código del cliente.

Client Secret: Una clave privada que debe mantenerse segura y nunca exponerse públicamente. GitHub te mostrará este valor solo una vez, así que asegúrate de copiarlo y guardarlo de forma segura.

Estas credenciales son las que utilizarás en la configuración de Spring Boot para establecer la comunicación segura entre tu aplicación y GitHub.

Consideraciones de seguridad

Es importante tratar el Client Secret como información sensible. Nunca lo incluyas directamente en tu código fuente ni lo subas a repositorios públicos. En su lugar, utiliza variables de entorno o archivos de configuración externos que no se incluyan en el control de versiones.

Para desarrollo local, puedes crear un archivo application-local.properties que contenga estas credenciales y añadirlo a tu .gitignore. En entornos de producción, utiliza las herramientas de gestión de secretos de tu plataforma de despliegue.

Configuración para diferentes entornos

Durante el desarrollo, es común trabajar con múltiples entornos. Puedes crear diferentes OAuth Apps para cada entorno (desarrollo, testing, producción) o configurar múltiples callback URLs en la misma aplicación separándolas por comas:

http://localhost:8080/login/oauth2/code/github,
https://miapp.com/login/oauth2/code/github

Esta flexibilidad te permite mantener la misma configuración de GitHub mientras trabajas en diferentes etapas del desarrollo de tu aplicación.

Configuración oauth2-client en Spring Boot

Una vez que tenemos nuestra GitHub OAuth App configurada, el siguiente paso es integrar las credenciales en nuestra aplicación Spring Boot y configurar el cliente OAuth2. Spring Boot 3 incluye soporte nativo para OAuth2 a través de Spring Security, lo que simplifica considerablemente la implementación.

Dependencias necesarias

Para habilitar la funcionalidad OAuth2 en Spring Boot, necesitamos añadir la dependencia correspondiente en nuestro archivo pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Esta dependencia incluye automáticamente Spring Security y todas las librerías necesarias para manejar el flujo OAuth2. No necesitas añadir dependencias adicionales de Spring Security ya que están incluidas.

Configuración básica en application.properties

La configuración OAuth2 en Spring Boot se realiza principalmente a través del archivo application.properties. Aquí definimos los parámetros de conexión con GitHub utilizando las credenciales obtenidas anteriormente:

# Configuración OAuth2 para GitHub
spring.security.oauth2.client.registration.github.client-id=tu_client_id_aqui
spring.security.oauth2.client.registration.github.client-secret=tu_client_secret_aqui
spring.security.oauth2.client.registration.github.scope=read:user,user:email

El parámetro scope define qué información del usuario solicitaremos a GitHub. Los scopes más comunes son:

• read:user: Acceso básico al perfil del usuario
• user:email: Acceso a las direcciones de email del usuario

Configuración de seguridad

Para que OAuth2 funcione correctamente con nuestros controladores MVC, necesitamos crear una clase de configuración de seguridad. Esta clase define qué rutas requieren autenticación y cómo manejar el proceso de login:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/", "/login", "/error").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .loginPage("/login")
                .defaultSuccessUrl("/dashboard", true)
            );
        
        return http.build();
    }
}

Esta configuración establece que:

• Las rutas /, /login y /error son públicas
• Cualquier otra ruta requiere autenticación
• El login se maneja a través de OAuth2 con una página personalizada
• Después del login exitoso, el usuario es redirigido a /dashboard

Controlador de login personalizado

Para proporcionar una experiencia de usuario coherente con nuestro diseño Bootstrap, creamos un controlador que maneje la página de login:

@Controller
public class AuthController {

    @GetMapping("/login")
    public String login() {
        return "login";
    }
    
    @GetMapping("/dashboard")
    public String dashboard(Authentication authentication, Model model) {
        OAuth2AuthenticationToken oauth2Token = (OAuth2AuthenticationToken) authentication;
        String username = oauth2Token.getPrincipal().getAttribute("login");
        String email = oauth2Token.getPrincipal().getAttribute("email");
        
        model.addAttribute("username", username);
        model.addAttribute("email", email);
        
        return "dashboard";
    }
}

El método dashboard muestra cómo extraer información del usuario autenticado. GitHub proporciona los datos del usuario a través del objeto OAuth2AuthenticationToken.

Plantilla Thymeleaf para login

Creamos una plantilla login.html en src/main/resources/templates/ que integre con Bootstrap 5.3:

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Iniciar Sesión</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body class="bg-light">
    <div class="container mt-5">
        <div class="row justify-content-center">
            <div class="col-md-6">
                <div class="card">
                    <div class="card-body text-center">
                        <h2 class="card-title mb-4">Iniciar Sesión</h2>
                        <p class="text-muted mb-4">Accede con tu cuenta de GitHub</p>
                        <a href="/oauth2/authorization/github" class="btn btn-dark btn-lg">
                            <i class="fab fa-github me-2"></i>
                            Continuar con GitHub
                        </a>
                    </div>
                </div>
            </div>
        </div>
    </div>
</body>
</html>

El enlace /oauth2/authorization/github es la URL estándar que Spring Security OAuth2 utiliza para iniciar el flujo de autenticación con GitHub.

Gestión de variables de entorno

Para mantener las credenciales seguras, es recomendable utilizar variables de entorno en lugar de valores hardcodeados. Modifica tu application.properties:

spring.security.oauth2.client.registration.github.client-id=${GITHUB_CLIENT_ID}
spring.security.oauth2.client.registration.github.client-secret=${GITHUB_CLIENT_SECRET}
spring.security.oauth2.client.registration.github.scope=read:user,user:email

En tu entorno de desarrollo, puedes definir estas variables en tu IDE o crear un archivo application-local.properties:

GITHUB_CLIENT_ID=tu_client_id_real
GITHUB_CLIENT_SECRET=tu_client_secret_real

Prueba de la configuración

Una vez completada la configuración, inicia tu aplicación Spring Boot y navega a http://localhost:8080/dashboard. Como esta ruta requiere autenticación, serás redirigido automáticamente a la página de login.

Al hacer clic en "Continuar con GitHub", el navegador te llevará a GitHub donde podrás autorizar tu aplicación. Después de la autorización exitosa, GitHub te redirigirá de vuelta a tu aplicación con el usuario autenticado.

El flujo completo funciona de la siguiente manera: usuario accede a ruta protegida → redirección a /login → clic en botón GitHub → autorización en GitHub → callback a tu aplicación → acceso concedido a la ruta original.