La configuración de seguridad estándar de FundeWebJS permite solamente validar los tokens JWT de OAUTH obtenidos desde micampus.

...

Para añadir la validación de claim hay que:
- Crear un objeto OAuth2TokenValidator<Jwt> miClaimValidator = new FundeWebJSClaimValidator( MI_CLAIM, MIVALOR_CLAIM_A_VALIDAR ); 
   con el nombre del claim y el valor a validar en el constructor.

...

-- 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

...

• Unauthorized
• 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).
  

2. Configurar endpoints

...

individualmente

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

con los claims configurados.
Dependiendo de la situación y del diseño de nuestra API, esto puedo ser necesario, pero el caso más habitual será tener diferentes endpoints y querer realizar una validación de claims diferente en cada uno de ellos.

Por ejemplo, en nuestra API que ofrece servicios a miscampus, podremos querer añadir un endpoint que valide tokens del flujo OAUTH CLIENT_CREDENTIALS para el servicio con claim client_id "tramites".

Esta validación específica de un endpoint se realiza de la siguiente manera:

PreAuthorize

Es necesario utilizar La segunda forma para configurar endpoints y securizarlos por scope es utilizando la anotación de spring-security @PreAuthorize .Para hacerlo hay que:
con la clase propia de FundeWebJS creada para tal efecto FundeWebJsJwtClaimPreAuthorizer (@umuJwtAuth):

• Anotar la clase SecurityConfig con @EnableGlobalMethodSecurity( prePostEnabled = true )
  
  

  Bloque de código
  @Configuration @EnableGlobalMethodSecurity( prePostEnabled = true ) public class SecurityConfig {....

  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

  validar ese

  scope

  claim) con @PreAuthorize @umuJwtAuth.hasClaim
  

  
  

  Bloque de código
  @PreAuthorize("

  hasAuthority('SCOPE_miotroscope

  @umuJwtAuth.hasClaim(authentication, 'MI_CLAIM', 'VALOR_A_VALIDAR')")

-- Respuesta de error --

...

• 
  Por ejemplo, a este endpoint sólo se podrá acceder con tokens del flujo Oauth: CLIENT_CREDENTIALS:

  
  

  Expandir
  title Ver ejemplo...
  Bloque de código language java @GetMapping( "/claimsTest" ) @PreAuthorize("@umuJwtAuth.hasClaim(authentication, 'grant_type', 'CLIENT_CREDENTIALS')") public ResponseEntity<String> validateClaimTest( Jwt jwt ) { return ResponseEntity.ok( "Claims validados" ); }

  
  

  Info

  La expresión dentro del PreAuthorize evalúa un booleano. Esto significa que: Pueden añadirse varias validaciones de claims en la misma anotación PreAuthorize añadiendo otro @umuJwtAuth.hasClaim separando cada comprobación por "and" (o por un "or" en caso de querer una u otra validación). Por ejemplo, a este endpoint sólo se podrá acceder con tokens del flujo Oauth: "CLIENT_CREDENTIALS" Y del servicio: "tramites": Bloque de código @GetMapping( "/claimsTest" ) @PreAuthorize("@umuJwtAuth.hasClaim(authentication, 'grant_type', 'CLIENT_CREDENTIALS') and @umuJwtAuth.hasClaim(authentication, 'client_id', 'tramites')") public ResponseEntity<String> validateClaimTest( Jwt jwt ) { return ResponseEntity.ok( "Claims validados" ); }

  
  

  Advertencia
  El primer parámetro del método hasClaim siempre debe ser "authentication". Es la variable de Spring Security con el contexto de seguridad en cada petición.

  
  

-- Respuesta de error --

La clase FundeWebJsJwtClaimPreAuthorizer (@umuJwtAuth) lanza una excepción FundeWebJsJwtClaimsAccessDeniedException cuando llegan tokens con claims inválidos.
El código de la librería Fundewebjs-security incluye por defecto un ExceptionHandler para estas excepciones FundeWebJsJwtClaimsAccessDeniedException. Ver clase FundeWebJsRestControllerAdvice.

Cuando llega una petición a un endpoint anotado con PreAuthorize("@umuJwtAuth.hasClaim..") que incluye un token inválido, la respuesta por defecto será::

• Status Code:  401 Unauthorized

• Body:  JSON con formato org.springframework.security.oauth2.server.resource.BearerTokenError. Por ejemplo:
  

  Bloque de código
  language json
  { "errorCode": "invalid_token", "description": "An error occurred while attempting to decode the Jwt: The grant_type claim is not valid", "uri": "https://tools.ietf.org/html/rfc6750#section-3.1", "httpStatus": "UNAUTHORIZED", "scope": null }

  
  

• Cabecera  WWW-Authenticate: Bearer error="invalid_token", error_description="An error occurred while attempting to decode the Jwt: The grant_type claim is not valid", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1"
• Cabecera UMU-Authenticate= invalid_token
  
  

• 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

...

@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() ) {
				//Documentar auth por scope
                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 />" );
                }  

 				//Documentar auth por claim              
			   Pattern Pattern patternClaims = Pattern.compile( "hasClaim\\(authentication,\\s*'\\w+',,\\s*'\\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:

Image Added

Referencias

https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html#oauth2resourceserver-jwt-validation-custom

...

...