S02L07 - Tutorial sobre Spring Boot JWT utilizando OAuth

html


Integración de Swagger UI y Seguridad en Aplicaciones de Spring: Una Guía Completa
Autor: [Your Name]

Publicado: Octubre 2023

Tabla de Contenidos

Introducción .............................................................. 1
Entendiendo Swagger UI ............................................. 3

¿Qué es Swagger UI? .................................................. 3
Configurando Swagger UI en Spring .................................. 4
Personalizando Swagger UI ................................................. 5


Implementando Seguridad en Aplicaciones de Spring ................. 7

Visión General de Spring Security ......................................... 7
Configurando OAuth2 Resource Server ................................. 8
JWT Authentication and Authorization ........................... 10


Integrando Swagger UI con Spring Security ................. 13

Asegurando Endpoints de Swagger ......................................... 13
Implementación Práctica ................................................ 14


Conclusión ................................................................. 17
Recursos ................................................................. 18


Introducción
En el panorama siempre cambiante del desarrollo web, construir APIs seguras y bien documentadas es fundamental. Spring Boot, un framework muy utilizado, ofrece características robustas para simplificar este proceso. Dos herramientas esenciales en este ecosistema son Swagger UI para la documentación de APIs y Spring Security para proteger su aplicación.
Este eBook profundiza en la integración de Swagger UI con Spring Security, proporcionando una guía completa para principiantes y desarrolladores con conocimientos básicos. Exploraremos la configuración, personalización y las configuraciones de seguridad necesarias para crear un entorno de API fluido y seguro.
¿Por qué Integrar Swagger UI y Spring Security?

Swagger UI ofrece documentación interactiva, permitiendo a los desarrolladores visualizar y probar endpoints de APIs sin esfuerzo.
Spring Security proporciona un marco de autenticación y autorización potente y personalizable, asegurando que las APIs estén protegidas contra accesos no autorizados.

Pros y Contras


Característica
Pros
Contras


Swagger UI
Documentación interactiva de API, pruebas fáciles
Requiere mantenimiento para precisión


Spring Security
Características de seguridad robustas, altamente personalizable
Curva de aprendizaje más pronunciada


Beneficios de la Integración
Seguridad mejorada, experiencia de desarrollador mejorada
Sobre carga de configuración adicional


Cuándo y Dónde Usar Estas Herramientas

Swagger UI es ideal para documentar y probar APIs durante el desarrollo.
Spring Security debe implementarse en cualquier aplicación que requiera mecanismos de autenticación y autorización.


Entendiendo Swagger UI
¿Qué es Swagger UI?
Swagger UI es una herramienta de código abierto que permite a los desarrolladores visualizar e interactuar con endpoints de APIs. Genera una interfaz amigable a partir de la documentación de una API, permitiendo pruebas y exploración en tiempo real.
Configurando Swagger UI en Spring
Para integrar Swagger UI en su aplicación de Spring, siga estos pasos:

Agregar Dependencia de Swagger





		
		
			
			
Java
			
			&lt;!-- pom.xml --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;io.springfox&lt;/groupId&gt;
    &lt;artifactId&gt;springfox-boot-starter&lt;/artifactId&gt;
    &lt;version&gt;3.0.0&lt;/version&gt;
&lt;/dependency&gt;
			
				
					
				
					1
2
3
4
5
6
				
						&lt;!-- pom.xml --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;io.springfox&lt;/groupId&gt;
    &lt;artifactId&gt;springfox-boot-starter&lt;/artifactId&gt;
    &lt;version&gt;3.0.0&lt;/version&gt;
&lt;/dependency&gt;
					
				
			
		



Configurar Swagger en Spring

Cree una clase de configuración para configurar Swagger:




		
		
			
			
Java
			
			// SwaggerConfig.java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
				
						// SwaggerConfig.java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
 
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}
					
				
			
		


Comentarios en el Código:

@Configuration: Indica que la clase tiene métodos de definición de @Bean.
Docket Bean: Configura Swagger para escanear el paquete especificado para endpoints de API.

Personalizando Swagger UI
La personalización le permite adaptar Swagger UI para que coincida con las necesidades de su aplicación.

Modificar Apariencia de Swagger UI

Ajuste el aspecto modificando la configuración:




		
		
			
			
Java
			
			@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info().title("My API")
            .version("1.0")
            .description("Documentación de API con Swagger UI personalizado"));
}
			
				
					
				
					1
2
3
4
5
6
7
				
						@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info().title("My API")
            .version("1.0")
            .description("Documentación de API con Swagger UI personalizado"));
}
					
				
			
		



Agregar Autenticación a Swagger UI

Para asegurar los endpoints de Swagger UI, actualice la configuración para incluir esquemas de autenticación:




		
		
			
			
Java
			
			@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .addSecurityItem(new SecurityRequirement().addList("JWT"))
            .components(new Components().addSecuritySchemes("JWT",
                    new SecurityScheme().name("JWT").type(SecurityScheme.Type.HTTP)
                            .scheme("bearer").bearerFormat("JWT")))
            .info(new Info().title("Secure API").version("1.0"));
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
				
						@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .addSecurityItem(new SecurityRequirement().addList("JWT"))
            .components(new Components().addSecuritySchemes("JWT",
                    new SecurityScheme().name("JWT").type(SecurityScheme.Type.HTTP)
                            .scheme("bearer").bearerFormat("JWT")))
            .info(new Info().title("Secure API").version("1.0"));
}
					
				
			
		


Explicación:

SecurityRequirement: Define el requisito de seguridad para la API.
SecurityScheme: Especifica el tipo de seguridad (JWT en este caso).


Implementando Seguridad en Aplicaciones de Spring
Visión General de Spring Security
Spring Security es un marco de autenticación y control de acceso potente y altamente personalizable. Proporciona servicios de seguridad integrales para aplicaciones basadas en Spring, incluyendo:

Autenticación y autorización
Protección contra vulnerabilidades comunes
Integración con diversos mecanismos de autenticación (por ejemplo, JWT, OAuth2)

Configurando OAuth2 Resource Server
Para configurar un OAuth2 Resource Server con Spring Security:

Agregar Dependencia de OAuth2





		
		
			
			
Java
			
			&lt;dependency&gt;
    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
    &lt;artifactId&gt;spring-boot-starter-oauth2-resource-server&lt;/artifactId&gt;
&lt;/dependency&gt;
			
				
					
				
					1
2
3
4
				
						&lt;dependency&gt;
    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
    &lt;artifactId&gt;spring-boot-starter-oauth2-resource-server&lt;/artifactId&gt;
&lt;/dependency&gt;
					
				
			
		



Configurar Ajustes de Seguridad





		
		
			
			
Java
			
			@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer().jwt();
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
				
						@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
 
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer().jwt();
    }
}
					
				
			
		


Comentarios en el Código:

csrf().disable(): Deshabilita la protección CSRF (usar con precaución).
authorizeRequests(): Configura la autorización basada en URLs.
oauth2ResourceServer().jwt(): Habilita la autenticación basada en JWT.

JWT Authentication and Authorization
JSON Web Tokens (JWT) son una forma compacta y autónoma de transmitir información de forma segura entre partes. Implementar JWT en Spring implica:

Generando JWTs





		
		
			
			
Java
			
			public String generateToken(Authentication authentication) {
    UserDetails userDetails = (UserDetails) authentication.getPrincipal();
    return Jwts.builder()
            .setSubject(userDetails.getUsername())
            .setIssuedAt(new Date())
            .setExpiration(new Date(System.currentTimeMillis() + 86400000)) // 1 día
            .signWith(SignatureAlgorithm.HS512, "secretKey")
            .compact();
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
				
						public String generateToken(Authentication authentication) {
    UserDetails userDetails = (UserDetails) authentication.getPrincipal();
    return Jwts.builder()
            .setSubject(userDetails.getUsername())
            .setIssuedAt(new Date())
            .setExpiration(new Date(System.currentTimeMillis() + 86400000)) // 1 día
            .signWith(SignatureAlgorithm.HS512, "secretKey")
            .compact();
}
					
				
			
		


Explicación:

setSubject: Establece el nombre de usuario como el sujeto del token.
setExpiration: Define la duración de la validez del token.
signWith: Firma el token usando el algoritmo y la clave secreta especificados.


Validando JWTs





		
		
			
			
Java
			
			public boolean validateToken(String token) {
    try {
        Jwts.parser().setSigningKey("secretKey").parseClaimsJws(token);
        return true;
    } catch (JwtException | IllegalArgumentException e) {
        // Token inválido
    }
    return false;
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
				
						public boolean validateToken(String token) {
    try {
        Jwts.parser().setSigningKey("secretKey").parseClaimsJws(token);
        return true;
    } catch (JwtException | IllegalArgumentException e) {
        // Token inválido
    }
    return false;
}
					
				
			
		


Explicación:

Analiza y valida el token usando la clave secreta.
Retorna true si es válido; de lo contrario, false.

Código de Programa de Muestra
A continuación se muestra un ejemplo completo que demuestra la autenticación JWT en una aplicación de Spring:




		
		
			
			
Java
			
			// JwtAuthenticationFilter.java
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.util.StringUtils;
import org.springframework.web.filter.OncePerRequestFilter;
import io.jsonwebtoken.*;

import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private String secretKey = "secretKey";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String token = getJwtFromRequest(request);

        if (StringUtils.hasText(token) && validateToken(token)) {
            String username = getUsernameFromJWT(token);

            UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                    username, null, new ArrayList<>());
            authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));

            SecurityContextHolder.getContext().setAuthentication(authentication);
        }

        filterChain.doFilter(request, response);
    }

    private String getJwtFromRequest(HttpServletRequest request) {
        String bearer = request.getHeader("Authorization");
        if (StringUtils.hasText(bearer) && bearer.startsWith("Bearer ")) {
            return bearer.substring(7);
        }
        return null;
    }

    private boolean validateToken(String authToken) {
        try {
            Jwts.parser().setSigningKey(secretKey).parseClaimsJws(authToken);
            return true;
        } catch (JwtException ex) {
            // Token inválido
        }
        return false;
    }

    private String getUsernameFromJWT(String token) {
        Claims claims = Jwts.parser()
                .setSigningKey(secretKey)
                .parseClaimsJws(token)
                .getBody();

        return claims.getSubject();
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
				
						// JwtAuthenticationFilter.java
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.util.StringUtils;
import org.springframework.web.filter.OncePerRequestFilter;
import io.jsonwebtoken.*;
 
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
 
public class JwtAuthenticationFilter extends OncePerRequestFilter {
 
    private String secretKey = "secretKey";
 
    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String token = getJwtFromRequest(request);
 
        if (StringUtils.hasText(token) && validateToken(token)) {
            String username = getUsernameFromJWT(token);
 
            UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                    username, null, new ArrayList<>());
            authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
 
            SecurityContextHolder.getContext().setAuthentication(authentication);
        }
 
        filterChain.doFilter(request, response);
    }
 
    private String getJwtFromRequest(HttpServletRequest request) {
        String bearer = request.getHeader("Authorization");
        if (StringUtils.hasText(bearer) && bearer.startsWith("Bearer ")) {
            return bearer.substring(7);
        }
        return null;
    }
 
    private boolean validateToken(String authToken) {
        try {
            Jwts.parser().setSigningKey(secretKey).parseClaimsJws(authToken);
            return true;
        } catch (JwtException ex) {
            // Token inválido
        }
        return false;
    }
 
    private String getUsernameFromJWT(String token) {
        Claims claims = Jwts.parser()
                .setSigningKey(secretKey)
                .parseClaimsJws(token)
                .getBody();
 
        return claims.getSubject();
    }
}
					
				
			
		


Explicación del Código:

Característica	Pros	Contras
Swagger UI	Documentación interactiva de API, pruebas fáciles	Requiere mantenimiento para precisión
Spring Security	Características de seguridad robustas, altamente personalizable	Curva de aprendizaje más pronunciada
Beneficios de la Integración	Seguridad mejorada, experiencia de desarrollador mejorada	Sobre carga de configuración adicional

JwtAuthenticationFilter: Extiende OncePerRequestFilter para asegurar una única ejecución por solicitud.

getJwtFromRequest: Extrae el JWT del encabezado Authorization.


validateToken: Valida el JWT usando la clave secreta.
getUsernameFromJWT: Recupera el nombre de usuario de las claims del JWT.
Configuración de Autenticación: Si el token es válido, establece la autenticación en el contexto de seguridad.


Salida de Muestra:

Cuando se proporciona un JWT válido en el encabezado Authorization, el usuario está autenticado y se concede acceso a los endpoints asegurados. Si el JWT es inválido o falta, se deniega el acceso.



Integrando Swagger UI con Spring Security
Asegurando Endpoints de Swagger
Para proteger los endpoints de Swagger UI mientras se permite el acceso necesario:

Actualizar Configuración de Seguridad

Modifique SecurityConfig para permitir el acceso a los recursos de Swagger:






		
		
			
			
Java
			
			@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .csrf().disable()
        .authorizeRequests()
        .antMatchers(
            "/swagger-resources/**",
            "/swagger-ui/**",
            "/v3/api-docs/**",
            "/public/**"
        ).permitAll()
        .anyRequest().authenticated()
        .and()
        .oauth2ResourceServer().jwt();
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
				
						@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .csrf().disable()
        .authorizeRequests()
        .antMatchers(
            "/swagger-resources/**",
            "/swagger-ui/**",
            "/v3/api-docs/**",
            "/public/**"
        ).permitAll()
        .anyRequest().authenticated()
        .and()
        .oauth2ResourceServer().jwt();
}
					
				
			
		


Explicación:

antMatchers: Especifica las URLs a permitir sin autenticación.
/swagger-resources/**, /swagger-ui/**, /v3/api-docs/**: Endpoints esenciales de Swagger.

Implementación Práctica
Implementemos la integración paso a paso:

Agregar Dependencias





		
		
			
			
Java
			
			&lt;!-- Spring Security y OAuth2 --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
    &lt;artifactId&gt;spring-boot-starter-security&lt;/artifactId&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
    &lt;artifactId&gt;spring-boot-starter-oauth2-resource-server&lt;/artifactId&gt;
&lt;/dependency&gt;

&lt;!-- Swagger --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;io.springfox&lt;/groupId&gt;
    &lt;artifactId&gt;springfox-boot-starter&lt;/artifactId&gt;
    &lt;version&gt;3.0.0&lt;/version&gt;
&lt;/dependency&gt;
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
				
						&lt;!-- Spring Security y OAuth2 --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
    &lt;artifactId&gt;spring-boot-starter-security&lt;/artifactId&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
    &lt;artifactId&gt;spring-boot-starter-oauth2-resource-server&lt;/artifactId&gt;
&lt;/dependency&gt;
 
&lt;!-- Swagger --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;io.springfox&lt;/groupId&gt;
    &lt;artifactId&gt;springfox-boot-starter&lt;/artifactId&gt;
    &lt;version&gt;3.0.0&lt;/version&gt;
&lt;/dependency&gt;
					
				
			
		



Configurar Swagger con Seguridad





		
		
			
			
Java
			
			@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .addSecurityItem(new SecurityRequirement().addList("JWT"))
            .components(new Components().addSecuritySchemes("JWT",
                    new SecurityScheme().name("JWT").type(SecurityScheme.Type.HTTP)
                            .scheme("bearer").bearerFormat("JWT")))
            .info(new Info().title("Secure API").version("1.0"));
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
				
						@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .addSecurityItem(new SecurityRequirement().addList("JWT"))
            .components(new Components().addSecuritySchemes("JWT",
                    new SecurityScheme().name("JWT").type(SecurityScheme.Type.HTTP)
                            .scheme("bearer").bearerFormat("JWT")))
            .info(new Info().title("Secure API").version("1.0"));
}
					
				
			
		



Implementar Filtro de Autenticación JWT

Como se mostró en la sección anterior, implemente JwtAuthenticationFilter y regístrelo en la configuración de seguridad.



Probar la Configuración


Acceder a Endpoint Público: Debería ser accesible sin autenticación.
Acceder a Endpoint Asegurado: Requiere un JWT válido.
Acceder a Swagger UI: Accesible sin autenticación si está configurado en consecuencia.

Interacción de Ejemplo:

Llamada a API Pública





		
		
			
			
Java
			
			GET /public/hello
			
				
					
				
					1
				
						GET /public/hello
					
				
			
		


Respuesta:




		
		
			
			
Java
			
			{
    "message": "Hello, World!"
}
			
				
					
				
					1
2
3
				
						{
    "message": "Hello, World!"
}
					
				
			
		



Llamada a API Asegurada sin JWT





		
		
			
			
Java
			
			GET /api/secure-data
			
				
					
				
					1
				
						GET /api/secure-data
					
				
			
		


Respuesta:




		
		
			
			
Java
			
			{
    "error": "Unauthorized"
}
			
				
					
				
					1
2
3
				
						{
    "error": "Unauthorized"
}
					
				
			
		



Llamada a API Asegurada con JWT Válido





		
		
			
			
Java
			
			GET /api/secure-data
Authorization: Bearer &lt;valid_jwt&gt;
			
				
					
				
					1
2
				
						GET /api/secure-data
Authorization: Bearer &lt;valid_jwt&gt;
					
				
			
		


Respuesta:




		
		
			
			
Java
			
			{
    "data": "Secure Information"
}
			
				
					
				
					1
2
3
				
						{
    "data": "Secure Information"
}
					
				
			
		



Conclusión
Integrar Swagger UI con Spring Security en aplicaciones de Spring mejora tanto la documentación como la seguridad de sus APIs. Al seguir los pasos descritos en esta guía, los desarrolladores pueden crear APIs bien documentadas y seguras que son amigables para el usuario y robustas contra accesos no autorizados.
Conclusiones Clave

Swagger UI simplifica la documentación y las pruebas de APIs, mejorando la experiencia del desarrollador.
Spring Security ofrece herramientas completas para asegurar aplicaciones, con soporte para JWT y OAuth2.
La integración adecuada asegura que los endpoints de Swagger estén asegurados mientras permanecen accesibles para usuarios autorizados.

Implementar estas herramientas de manera efectiva puede agilizar significativamente su proceso de desarrollo de APIs, asegurando que sus aplicaciones sean tanto transparentes como seguras.
SEO Keywords: Spring Boot, Swagger UI, Spring Security, JWT Authentication, OAuth2, API Documentation, Secure APIs, Spring Boot Security Configuration, JSON Web Token, API Development

Recursos

Documentación de Spring Boot
Sitio Oficial de Swagger UI
Referencia de Spring Security
Visión General de OAuth2
Introducción a JSON Web Tokens (JWT)
Repositorio de Springfox en GitHub


Nota: Este artículo ha sido generado por IA.