La configuración de seguridad estándar de FundeWebJS permite solamente validar los tokens JWT de OAUTH obtenidos desde micampus.
En ocasiones una API necesitará validar otro tipo de tokens OAUTH obtenidos desde otras aplicaciones, scopes u otros flujos OAUTH o, simplemente, querremos ampliar la seguridad de nuestros endpoints.
Por ejemplo: validación del tokens OAUTH del flujo CLIENT CREDENTIALS para la comunicación entre APIs FundeWeb y FundeWebJS.
La autorización por Scope se puede configurar siguiendo la guía Autorización por Scopes .
Esta página trata sobre la configuración de nuestra API FundeWebJS para validar tokens que contengan claims específicos.
Los claims son cada uno de los atributos que forman el payload del token JWT (RFC JWT). Puede verse el contenido de un JWT desde la web https://jwt.io/.
Guía detallada
La librería fundewebjs-security contiene un fichero FundeWebJSSecurityConfig por defecto. Para utilizar otra configuración hay que realizar los siguientes pasos:
- Si no existe en nuestro proyecto, crear una clase SecurityConfig.java nueva a partir del código de FundeWebJSSecurityConfig (ubicada en la librería fundewebjs-security).
En el application.properties (de local y de los entornos en Helm Chart), añadir la siguiente property:
//Deshabilita SecurityFilterChain por defecto fdwjs.starter.security.enable=false
A continuación se detallan las configuraciones específicas para validar claims:
Existen dos formas de configurar esta validación:
- Global: Se configura para toda la aplicación y todos los endpoints realizarán la misma validación.
- Por método: Sólo el endpoint configurado validará el claim
1. Configuración global
Con esta configuración se realizará la validación de claims en TODOS los endpoints de la aplicación.
En la clase SecurityConfig.java (ver pasos 1 y 2 anteriores), añadir el siguiente Bean JwtDecoder:
import org.springframework.security.oauth2.core.DelegatingOAuth2TokenValidator;
import org.springframework.security.oauth2.core.OAuth2TokenValidator;
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtValidators;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;.....@Configuration
public class SecurityConfig {
............
@Bean
JwtDecoder jwtDecoder() {
NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withJwkSetUri( jwkSetUri )
.jwsAlgorithm( SignatureAlgorithm.RS512 ).build();
OAuth2TokenValidator<Jwt> clientIdValidator = new FundeWebJSClaimValidator( "client_id", "tramites" );
OAuth2TokenValidator<Jwt> grantValidator = new FundeWebJSClaimValidator( "grant_type", "CLIENT_CREDENTIALS" );
OAuth2TokenValidator<Jwt> withIssuer = JwtValidators.createDefaultWithIssuer( issuerUri );
OAuth2TokenValidator<Jwt> withAudience = new DelegatingOAuth2TokenValidator<>( withIssuer, clientIdValidator,
grantValidator );
jwtDecoder.setJwtValidator( withAudience );
return jwtDecoder;
}
Este método es un ejemplo para validar que el token se haya obtenido para el flujo Oauth "CLIENT_CREDENTIALS" y para el servicio "tramites".
Para añadir la validación de claim hay que:
- Crear un objeto OAuth2TokenValidator<Jwt> miClaimValidator = new FundeWebJSClaimValidator( MI_CLAIM, MI_CLAIM_A_VALIDAR );
con el nombre del claim y el valor a validar en el constructor.
- Añadir el objeto miClaimValidator como otro parámetro más en new DelegatingOAuth2TokenValidator<>( withIssuer, miClaimValidator,..);
Solo deben realizarse estos dos paso, el resto de código del método debe permanecer tal cuál está en el ejemplo.
-- Respuesta de error --
Cuando llegue una petición con un token que no cumpla las restricciones configuradas con los FundeWebJSClaimValidator, la librería spring-security-oauth2-resource-server toma el control y devuelve la respuesta de la siguiente forma:
- Status Code: 401 Authorized
- Body: VACIO
- Cabecera WWW-Authenticate: Bearer error="invalid_token", error_description="An error occurred while attempting to decode the Jwt: The client_id claim is not valid", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1"
(Siguiendo el ejemplo del bloque de código descrito más arriba).
Repetimos: ESTA CONFIGURACIÓN GLOBAL VALIDARÁ LOS CLAIMS CONFIGURADOS EN TODOS LOS ENDPOINTS DEL API.
2. Configurar endpoints por scope
Con la configuración del punto 1 se configura TODA la aplicación para permitir tokens que contengan cualquiera de los scopes configurados.
Esto significa que un token obtenido desde micampus por cualquier usuario sería válido para acceder a cualquier endpoint.
Si hemos tenido que configurar varios scopes, lo normal es que está situación sea no deseada (no queremos que cualquier token sirva para acceder a endpoints que requieran un nivel diferente de acceso).
En este paso se explica cómo configurar nuestra aplicación para securizar diferentes endpoints con scopes distintos.
Existen dos alternativas :
- Configurar los mvcMatchers en el SecurityConfig.
- Utilizar la anotación PreAuthorize en cada método Java de nuestro RestController.
Configuración con PreAuthorize
La segunda forma para configurar endpoints y securizarlos por scope es utilizando la anotación de spring-security @PreAuthorize.
Para hacerlo hay que:
- Anotar la clase SecurityConfig con @EnableGlobalMethodSecurity( prePostEnabled = true )
- Anotar el método java que publica nuestro endpoint (o directamente todo el RestController en caso de hacer una clase específica para ese scope) con @PreAuthorize( "hasAuthority('SCOPE_miotroscope')" )
-- Respuesta de error --
Cuando llega una petición a el/los endpoints con la anotación PreAuthroize y un token inválido la respuesta por defecto será del mismo tipo que en el caso anterior:
- Status Code: 403 Forbidden
- Body: VACIO
- Cabecera WWW-Authenticate: Bearer error="insufficient_scope", error_description="The request requires higher privileges than provided by the access token.", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1"
La diferencia con MvcMatchers es que con esta configuración la validación se realiza al final, justo antes de entrar al método, y que la aplicación puede tomar el control del manejo de la excepción usando alguno de los mecanismos de Manejo de Errores en FundeWebJS para capturar la excepción AccessDeniedException.
Por ejemplo , podríamos añadir a la respuesta un body y una cabecera propia con este ExceptionHandler:
@ExceptionHandler( AccessDeniedException.class )
public ResponseEntity<ResponseException> accessDeniedException( HttpServletRequest request,
AccessDeniedException e ) throws IOException {
....
MiDTOdeError responseErrorBody = new MiDTOdeError([CON LOS ATRIBUTOS QUE QUIERA SACAR EN EL BODY]) //Puede usarse la clase BearerTokenError y BearerTokenErrors para generarlo.
Map<String, String> parameters = new LinkedHashMap<>();
if ( request.getUserPrincipal() instanceof AbstractOAuth2TokenAuthenticationToken ) {
parameters.put( "error", BearerTokenErrorCodes.INSUFFICIENT_SCOPE );
parameters.put( "error_description",
"The request requires higher privileges than provided by the access token." );
parameters.put( "error_uri", "https://tools.ietf.org/html/rfc6750#section-3.1" );
}
String wwwAuthenticate = computeWWWAuthenticateHeaderValue( parameters );
HttpHeaders headers = new HttpHeaders();
headers.add( HttpHeaders.WWW_AUTHENTICATE, wwwAuthenticate );
headers.add( "UMU-Authenticate", parameters.get( "error" ) );
return new ResponseEntity<>( responseErrorBody, headers, HttpStatus.FORBIDDEN );
}
private static String computeWWWAuthenticateHeaderValue( Map<String, String> parameters ) {
StringBuilder wwwAuthenticate = new StringBuilder();
wwwAuthenticate.append( "Bearer" );
if ( !parameters.isEmpty() ) {
wwwAuthenticate.append( " " );
int i = 0;
for ( Map.Entry<String, String> entry : parameters.entrySet() ) {
wwwAuthenticate.append( entry.getKey() ).append( "=\"" ).append( entry.getValue() ).append( "\"" );
if ( i != ( parameters.size() - 1 ) ) {
wwwAuthenticate.append( ", " );
}
i++;
}
}
return wwwAuthenticate.toString();
}
3. Buenas prácticas
Como se ha mencionado en los apartados de respuesta de error, los mecanismos estándar de manejo de excepciones de spring-security y spring-security-oauth2-resource-server devuelven siempre un 403 Forbidden, con body vacío y con la cabecera WWW-Authenticate informando del error "insufficient_scope".
Esta configuración se puede sobreescribir pero, siguiendo el RFC de Oauth se recomienda mantener el 403 Forbidden y la cabecera con "insufficient_scope" => "The resource server SHOULD respond with the HTTP 403 (Forbidden) status code and MAY include the "scope" attribute with the scope necessary to access the protected resource".
3. Documentar con Springdoc-OPENAPI
Utilizando @PreAuthorize es posible configurar la generación de la documentación para que aparezca el Scope requerido.
Para hacerlo solo sería necesario añadir una clase de configuración como ésta:
@Configuration
public class OpenApiConfiguration { @Bean
public OperationCustomizer operationCustomizer() {
return ( operation, handlerMethod ) -> {
Optional<PreAuthorize> preAuthorizeAnnotation = Optional
.ofNullable( handlerMethod.getMethodAnnotation( PreAuthorize.class ) );
StringBuilder sb = new StringBuilder();
if ( preAuthorizeAnnotation.isPresent() ) {
Pattern patternAuthority = Pattern.compile( "'SCOPE_\\w+'" );
Matcher matcher = patternAuthority.matcher( ( preAuthorizeAnnotation.get() ).value() );
if ( matcher.find() ) {
sb.append( "Este endpoint requiere **SCOPE " ).append( matcher.group().replaceAll( "SCOPE_", "" ) )
.append( "**<br />" );
} Pattern patternClaims = Pattern.compile( "hasClaim\\(authentication,'\\w+','\\w+'\\)" );
matcher = patternClaims.matcher( ( preAuthorizeAnnotation.get() ).value() );
if ( matcher.find() ) {
String[] claims = matcher.group().replaceAll( "hasClaim\\(authentication,|\\)", "" ).split( "," );
sb.append( "Este endpoint requiere **CLAIM " ).append( claims[0] ).append( ": " )
.append( claims[1] ).append( "**<br />" );
}
sb.append( "<br />" );
}
sb.append( operation.getDescription() );
operation.setDescription( sb.toString() );
return operation;
};
}
}
El resultado de esta configuración se puede ver en la siguiente imagen:
Referencias
Artículos Relacionados
No hay ningún contenido con las etiquetas especificadas