This article explains using our OSS lambda-utilities to configure a spring cloud function java lambda to allow method level authorisation using API Gateway and Cognito.

See our OSS repository here.

Architecture Overview

The security setup integrates three key AWS services:

1. AWS Cognito – Identity provider and JWT issuer
2. AWS API Gateway – HTTP API with JWT authorizer
3. AWS Lambda – Function execution environment

Key Components

1. ApiGatewayResponseDecoratorFactory

This is the central factory that creates decorated Spring Cloud Functions with security and error handling:

@Service
public class ApiGatewayResponseDecoratorFactory {
    // Creates decorated functions that handle security, errors, and responses
    public <Input, Output> Function<Input, APIGatewayV2HTTPResponse> create(Function<Input, Output> function)
}

Purpose:

• Wraps your business logic functions
• Automatically handles authentication extraction from API Gateway events
• Converts exceptions to proper HTTP responses
• Manages Spring Security context

2. Security Configuration Setup

The security is configured through : AwsCloudFunctionSpringSecurityConfiguration

@EnableMethodSecurity
@Configuration
@Import({LimeJacksonJsonConfiguration.class, ApiGatewayResponseDecoratorFactory.class})
@ComponentScan(basePackageClasses = ApiGatewayAuthenticationMapper.class)
public class AwsCloudFunctionSpringSecurityConfiguration

This enables:

• Method-level security (@PreAuthorize, @Secured, etc.)
• Automatic authentication mapping
• Exception handling for security violations

3. Authentication Flow

The authentication process works as follows:

1. API Gateway receives request with JWT token in Authorization header
2. JWT Authorizer validates the token against Cognito
3. API Gateway forwards the validated JWT claims in the request context
4. extracts authentication from the event: 
   • Reads JWT claims from request context
   • Creates object ApiGatewayAuthentication
   • Maps Cognito groups to Spring Security authorities
   ApiGatewayAuthenticationMapper
5. Spring Security context is populated for method-level security

AWS Infrastructure Setup

API Gateway Configuration

# Example CDK/CloudFormation for HTTP API with JWT Authorizer
HttpApi:
  Type: AWS::ApiGatewayV2::Api
  Properties:
    Name: MySecureApi
    ProtocolType: HTTP

JwtAuthorizer:
  Type: AWS::ApiGatewayV2::Authorizer
  Properties:
    ApiId: !Ref HttpApi
    AuthorizerType: JWT
    IdentitySource:
      - $request.header.Authorization
    JwtConfiguration:
      Audience:
        - your-cognito-client-id
      Issuer: https://cognito-idp.{region}.amazonaws.com/{user-pool-id}

Route:
  Type: AWS::ApiGatewayV2::Route
  Properties:
    ApiId: !Ref HttpApi
    RouteKey: POST /secure-endpoint
    Target: !Sub integrations/${LambdaIntegration}
    AuthorizerId: !Ref JwtAuthorizer
    AuthorizationType: JWT

Cognito Configuration

UserPool:
  Type: AWS::Cognito::UserPool
  Properties:
    UserPoolName: MyAppUsers
    Schema:
      - Name: email
        AttributeDataType: String
        Required: true
    Policies:
      PasswordPolicy:
        MinimumLength: 8

UserPoolClient:
  Type: AWS::Cognito::UserPoolClient
  Properties:
    UserPoolId: !Ref UserPool
    ClientName: MyAppClient
    GenerateSecret: false
    ExplicitAuthFlows:
      - ADMIN_NO_SRP_AUTH
      - USER_PASSWORD_AUTH

Implementation Example

1. Create Your Business Function

@Component
public class SecureBusinessLogic {
    
    public String processSecureData(MyRequest request) {
        // Your business logic here
        return "Processed: " + request.getData();
    }
}

2. Create the Lambda Handler

@Configuration
@Import(LimeAwsLambdaConfiguration.class)
public class LambdaConfiguration {
    
    @Autowired
    private ApiGatewayResponseDecoratorFactory decoratorFactory;
    
    @Autowired
    private SecureBusinessLogic businessLogic;
    
    @Bean
    public Function<APIGatewayV2HTTPEvent, APIGatewayV2HTTPResponse> secureFunction() {
        return decoratorFactory.create(event -> {
            // Extract request body
            MyRequest request = parseRequest(event.getBody());
            
            // Business logic with automatic security context
            return businessLogic.processSecureData(request);
        });
    }
}

3. Add Method-Level Security

@Component
public class SecureBusinessLogic {
    
    @PreAuthorize("hasAuthority('ADMIN')")
    public String processAdminData(MyRequest request) {
        return "Admin processed: " + request.getData();
    }
    
    @PreAuthorize("hasAuthority('USER') or hasAuthority('ADMIN')")
    public String processUserData(MyRequest request) {
        return "User processed: " + request.getData();
    }
}

4. Access Current User Context

@Bean
public Function<APIGatewayV2HTTPEvent, APIGatewayV2HTTPResponse> contextAwareFunction() {
    return decoratorFactory.create(event -> {
        // Access current authentication
        ApiGatewayContext context = decoratorFactory.getCurrentApiGatewayContext();
        ApiGatewayAuthentication auth = context.getAuthentication();
        
        if (auth.isAuthenticated()) {
            String username = auth.getPrincipal().getName();
            Set<String> groups = auth.getAuthorities()
                                    .stream()
                                    .map(GrantedAuthority::getAuthority)
                                    .collect(Collectors.toSet());
            
            return new UserResponse(username, groups, "Success");
        } else {
            return new UserResponse("anonymous", Set.of("ANONYMOUS"), "Limited access");
        }
    });
}

Configuration Properties

The authentication mapper supports several configuration properties:

com:
  limemojito:
    aws:
      lambda:
        security:
          claimsKey: "cognito:groups"  # Cognito groups claim
          anonymous:
            sub: "ANONYMOUS"
            userName: "anonymous"
            authority: "ANONYMOUS"

Security Benefits

1. Automatic JWT Validation: API Gateway validates tokens before reaching Lambda
2. Claims Extraction: Automatic mapping of Cognito user groups to Spring authorities
3. Method Security: Use standard Spring Security annotations
4. Exception Handling: Automatic conversion of security exceptions to HTTP responses
5. Context Access: Easy access to user information and claims
6. Anonymous Support: Graceful handling of unauthenticated requests

Error Handling

The decorator automatically handles:

• Authentication failures → 401 Unauthorized
• Authorization failures → 403 Forbidden
• Validation errors → 400 Bad Request
• General exceptions → 500 Internal Server Error

This architecture provides a robust, scalable security solution that leverages AWS managed services while maintaining clean separation of concerns in your Spring Cloud Function implementation.

This article looks at optimising a Java Spring Boot application (Cloud Function style) with AWS SnapStart, and covered advanced optimisation with lifecycle management of pre snapshots and post restore of the application image by AWS SnapStart. We cover optimising a lambda for persistent network connection style conversational resources, such as an RDBMS, SQL, legacy messaging framework, etc.

How Snap Start Works

To import start up times for a cold start, SnapStart snapshots a virtual machine and uses the restore of the snapshot rather than the whole JVM + library startup time. For Java applications built on frameworks such as Spring Boot, this provides order of magnitude time reductions on cold start time. For a comparison with raw, SnapStart and Graal Native performance see our article here.

What frameworks do we use with Spring Boot?

For our Java Lambdas we use Spring Cloud Function with the AWS Lambda Adaptor. For an example for how we set this up, and links to our development frameworks and code, see our article AWS SnapStart for Faster Java Lambdas

Default SnapStart: Simple Optimisation of the Lambda INIT phase

When the lambda version is published SnapStart will run up the Java application to the point that the lambda is initialised. For a spring cloud function application, this will complete the Spring Boot lifecycle to the Container Started phase. In short, all your beans will be constructed, injected and started from a Spring Container perspective.

SnapStart will then snapshot the virtual machine with all the loaded information. When the image is restored, the exact memory layout of all classes and data in the JVM is restored. Thus any data loaded in this phase as part of a Spring Bean Constructor, @PostCreate annotated methods and ContextRefresh event handlers will have been reloaded as part of the restore.

Issues with persistent network connections

Where this breaks down is if you wish to use a “persistent” network connection style resource, such as a RDBMS connection. In this example, usually in a Spring Boot application a Data Source is configured and the network connections initialised pre container start. This can cause significant slow downs when restoring an image, perhaps weeks after its creation, as all the network connections will be broken.

For a self healing data source, when a connection is requested the connection will check, timeout and have to reconnect the connection and potentially start a new transaction for the number of configured connections in the pool. Even if you smartly set the pool size to one, given the single threaded lambda execution model, that connection timeout and reconnect may take significant time depending on network and database settings.

Advanced Java SnapStart: CRaC Lifecycle Management

Project CRaC, Co-ordinated Restore at Checkpoint, is a JVM project that allows responses to the host operating system having a checkpoint pre a snapshot operation, and the signal that a operating system restore has occurred. The AWS Java Runtime supports integration with CRaC so that you can optimise your cold starts even under SnapStart.

At the time of our integration, we used the CRaC library to create a base class that could be used to create a support class that can handle “manual” tailoring of preSnapshot and postRestore events. Newer versions of boot are integrating CRaC support – see here for details.

We have created a base class, SnapStartOptimizer, that can be used to create a spring bean that can respond to preSnapshot and postRestore events. This gives us two hooks into the lifecycle:

1. Load more data into memory before the snapshot occurs.
2. Restore data and connections after we are running again.

Optimising pre snapshot

In this example we have a simple Spring Component that we use to exercise some functionality (http based) to load and lazy classes, data, etc. We also exercise the lookup of our spring cloud function definition bean.

@Component
@RequiredArgsConstructor
public class SnapStartOptimisation extends SnapStartOptimizer {

    private final UserManager userManager;
    private final TradingAccountManager accountManager;
    private final TransactionManager transactionManager;

    @Override
    protected void performBeforeCheckpoint() {
        swallowError(() -> userManager.fetchUser("thisisnotatoken"));
        swallowError(() -> accountManager.accountsFor(new TradingUser("bob", "sub")));
        final int previous = 30;
        final int pageSize = 10;
        swallowError(() -> transactionManager.query("435345345",
                                                    Instant.now().minusSeconds(previous),
                                                    Instant.now(),
                                                    PaginatedRequest.of(pageSize)));
        checkSpringCloudFunctionDefinitionBean();
    }
}

Optimising post restore – LambdaSqlConnection class.

In this example we highlight our LambdaSqlConnection class, which is already optimised for SnapStart. This class exercises a delegated java.sql.Connection instance preSnapshot to confirm connectivity, but replaces the connection on postRestore. This class is used to implement a bean of type java.sql.Connection, allowing you to write raw JDBC in lambdas using a single RDBMS connection for the lambda instance.

Note: Do not use default Spring Boot JDBC templates, JPA, Hibernate, etc in lambdas. The overhead of the default multi connection pools, etc is inappropriate for lambda use. For heavy batch processing a “Run Task” ECS image is more appropriate, and does not have 15 minute timeout constraints.

So how does it work?

1. The LambdaSqlConnection class manages the Connection bean instance.
2. When preSnapshot occurs, LambdaSqlConnection closes the Connection instance.
3. When postRestore occurs, LambdaSqlConnection reconnects the Connection instance.

Because LambdaSqlConnection creating a dynamic proxy as the Connection instance, it can manage the delegated connection “behind” the proxy without your injected Connection instance changing.

Using Our SQL Connection replacement in Spring Boot

See the code at https://github.com/LimeMojito/oss-maven-standards/tree/master/utilities/aws-utilities/lambda-sql.

Maven dependency:

<dependency>
   <groupId>com.limemojito.oss.standards.aws</groupId>
   <artifactId>lambda-sql</artifactId>
   <version>15.0.2</version>
</dependency>

Importing our java.sql.Connection interceptor

@Import(LambdaSqlConnection.class)
@SpringBootApplication
public class MySpringBootApplication {

You can now remove any code that is creating a java.sql.Connection and simply use a standard java.sql.Connection instance injected as a dependency in your code. This configuration creates a java.sql.Connection compatible bean that is optimised with SnapStart and delegates to a real SQL connection.

Configuring your (real) DB connection

Example with Postgres driver.

lime:
  jdbc:
    driver:
      classname: org.postgresql.Driver
    url: 'jdbc:postgresql://localhost:5432/postgres'
    username: postgres
    password: postgres

Example spring bean using SQL

@Service
@RequiredArgsConstructor
public class MyService {
    private final Connection connection;

    @SneakyThrows
    public int fetchCount() {
      try(Statement statement = connection.createStatement()){
         try(ResultSet results = statement.executeQuery("count(1) from some_table")) {
             results.next();
             results.getInt(1);
         }
      }
    }
}

References

• AWS SnapStart: https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html
• Cold Start Timings: http://52.35.51.142/native-java-aws-lambda-with-graal-vm/
• Using AWS Snapstart for Faster Java Lambdas: http://52.35.51.142/aws-snap-start-for-faster-java-lambda/
• Project CRaC: https://github.com/CRaC/docs
• Spring Framework CRaC integration: https://docs.spring.io/spring-framework/reference/integration/checkpoint-restore.html