Securing REST APIs is paramount for developers and organizations in today’s rapidly evolving digital landscape. One of the most robust ways to secure APIs is by leveraging OAuth2 scopes with AWS Cognito. This blog post will guide you through the process of securing your SpringBoot REST APIs using AWS Cognito OAuth2 scopes, covering key topics such as the use case for OAuth2 scopes, securing APIs with OAuth2 Client Credentials Grant, understanding how JWT works in securing SpringBoot APIs, API authorization and error responses, and critical points to note.

Introduction

OAuth2 is an open standard for access delegation, commonly used to grant websites or applications limited access to a user’s information without exposing passwords. AWS Cognito simplifies adding authentication, authorization, and user management to your web and mobile applications. By combining SpringBoot, AWS Cognito, and OAuth2 scopes, you can create highly secure and scalable APIs.

Use Case for OAuth2 Scopes

OAuth2 scopes are a mechanism in OAuth 2.0 that limits an application’s access to a user’s account. The OAuth2 authorization process involves the client requesting access to specific scopes and defining the access level and permissions granted. This ensures that APIs are protected and only accessible to authorized clients with the correct permissions.

Securing APIs using OAuth2 Client Credentials Grant

The Client Credentials Grant is one of the OAuth2 grant types used when the client requests access to protected resources under its control. It is commonly used for machine-to-machine (M2M) applications without end-users.

  1. Setup AWS Cognito:
    • Create a new Cognito User Pool and configure it with appropriate settings.
    • Create an App Client and generate the client ID and secret.
    • Configure the OAuth2 settings by enabling the Client Credentials grant type.
  2. Configure SpringBoot Project:
    • Add the necessary dependencies for Spring Security and AWS Cognito.
    • Configure the Spring Security settings to use OAuth2 with Cognito.
    • Implement the security configuration class to define the security rules and OAuth2 properties.

@Configuration

@EnableWebSecurity

public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override

    protected void configure(HttpSecurity http) throws Exception {

        http

            .authorizeRequests()

                .antMatchers(“/public/**”).permitAll()

                .anyRequest().authenticated()

                .and()

            .oauth2ResourceServer()

                .jwt();

    }

}

  1. Obtain Access Token:
    • Use the client ID and secret to request an access token from Cognito.
    • The access token will contain the necessary scopes for accessing the APIs.

curl –location –request POST ‘https://your-cognito-domain/oauth2/token’ \

–header ‘Content-Type: application/x-www-form-urlencoded’ \

–data-urlencode ‘grant_type=client_credentials’ \

–data-urlencode ‘client_id=YOUR_CLIENT_ID’ \

–data-urlencode ‘client_secret=YOUR_CLIENT_SECRET’ \

–data-urlencode ‘scope=YOUR_SCOPES’

How JWT Works in Securing SpringBoot APIs

JSON Web Tokens (JWT) are a compact, URL-safe means of representing claims to be transferred between two parties. JWTs are often used to secure APIs by embedding claims that contain information about the user’s identity and the scopes granted.

  • Structure of JWT:
    • Header: Contains metadata about the token.
    • Payload: Contains the claims, statements about an entity (typically, the user), and additional data.
    • Signature: Used to verify the token’s integrity and authenticity.
  • Validation Process:
    • The token is received from the client.
    • The token’s signature is validated using the public key.
    • The claims within the token are checked to ensure they contain the necessary scopes and have not expired.

API Authorization and Error Responses

When securing APIs, handling authorization and providing appropriate error responses is crucial.

  1. Authorization:
    • Use annotations or configuration to specify which roles or scopes are required for each endpoint.
    • Implement fine-grained access control to ensure only authorized clients can access specific resources.

@RestController

@RequestMapping(“/api”)

public class ApiController {

    @PreAuthorize(“hasAuthority(‘SCOPE_read’)”)

    @GetMapping(“/data”)

    public ResponseEntity<String> getData() {

        return ResponseEntity.ok(“Secure Data”);

    }

}

  1. Error Responses:
    • Provide meaningful error messages for unauthorized access attempts.
    • Ensure error responses do not leak sensitive information about the application’s security configuration.

@ControllerAdvice

public class CustomExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(AccessDeniedException.class)

    public ResponseEntity<Object> handleAccessDeniedException(AccessDeniedException ex) {

        return new ResponseEntity<>(“Access denied: ” + ex.getMessage(), HttpStatus.FORBIDDEN);

    }

}

Key Points to Note

  • Ensure that your AWS Cognito User Pool and App Client are configured correctly with the necessary OAuth2 settings.
  • Use the Client Credentials Grant for machine-to-machine communication where no end-user is involved.
  • Always validate JWTs to ensure their integrity and authenticity.
  • Implement fine-grained access control using OAuth2 scopes to restrict access to your APIs.
  • Provide meaningful and secure error responses to unauthorized access attempts.

References

Scopes, M2M, and API authorization with resource servers

Access token security for microservice APIs on Amazon EKS