AWS Lambda HTTP Security Integration

sam local docs

convert lambda security to auth mechanism

default providers

add mechanism if empty credential types

use QuarkusPrincipal

fix test

don't fire mech if request not set

revert idp

docs/src/main/asciidoc/amazon-lambda-http.adoc

@@ -258,6 +258,7 @@ For the AWS REST API you can inject the AWS variables `com.amazonaws.services.la
 ----
 import javax.ws.rs.core.Context;
 import io.quarkus.amazon.lambda.http.model.AwsProxyRequestContext;
+import io.quarkus.amazon.lambda.http.model.AwsProxyRequest;
 
 
 @Path("/myresource")
@@ -266,7 +267,10 @@ public class MyResource {
     public String ctx(@Context com.amazonaws.services.lambda.runtime.Context ctx) { }
 
     @GET
-    public String req(@Context AwsProxyRequestContext req) { }
+    public String reqContext(@Context AwsProxyRequestContext req) { }
+
+    @GET
+    public String req(@Context AwsProxyRequest req) { }
 
 }
 ----
@@ -276,3 +280,203 @@ public class MyResource {
 If you are building native images, and want to use https://aws.amazon.com/xray[AWS X-Ray Tracing] with your lambda
 you will need to include `quarkus-amazon-lambda-xray` as a dependency in your pom.  The AWS X-Ray
 library is not fully compatible with GraalVM so we had to do some integration work to make this work.
+
+== Security Integration
+
+When you invoke an HTTP request on the API Gateway, the Gateway turns that HTTP request into a JSON event document that is
+forwarded to a Quarkus Lambda.  The Quarkus Lambda parses this json and converts in into an internal representation of an HTTP
+request that can be consumed by any HTTP framework Quarkus supports (JAX-RS, servlet, Vert.x Web).
+
+API Gateway supports many different ways to securely invoke on your HTTP endpoints that are backed by Lambda and Quarkus.
+If you enable it, Quarkus will automatically parse relevant parts of the https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html[event json document]
+and look for security based metadata and register a `java.security.Principal` internally that can be looked up in JAX-RS
+by injecting a `javax.ws.rs.core.SecurityContext`, via `HttpServletRequest.getUserPrincipal()` in servlet, and `RouteContext.user()` in Vert.x Web.
+If you want more security information, the `Principal` object can be typecast to
+a class that will give you more information.
+
+To enable this security feature, add this to your `application.properties` file:
+----
+quarkus.lambda-http.enable-security=true
+----
+
+
+Here's how its mapped:
+
+.HTTP `quarkus-amazon-lambda-http`
+[options="header"]
+|=======================
+|Auth Type       |Principal Class                                 |Json path of Principal Name
+|Cognito JWT     |`io.quarkus.amazon.lambda.http.CognitoPrincipal`|`requestContext.authorizer.jwt.claims.cognito:username`
+|IAM             |`io.quarkus.amazon.lambda.http.IAMPrincipal`    |`requestContext.authorizer.iam.userId`
+|Custom Lambda   |`io.quarkus.amazon.lambda.http.CustomPrincipal` |`requestContext.authorizer.lambda.principalId`
+
+|=======================
+
+.REST `quarkus-amazon-lambda-rest`
+[options="header"]
+|=======================
+|Auth Type       |Principal Class                                 |Json path of Principal Name
+|Cognito         |`io.quarkus.amazon.lambda.http.CognitoPrincipal`|`requestContext.authorizer.claims.cognito:username`
+|IAM             |`io.quarkus.amazon.lambda.http.IAMPrincipal`    |`requestContext.identity.user`
+|Custom Lambda   |`io.quarkus.amazon.lambda.http.CustomPrincipal` |`requestContext.authorizer.principalId`
+
+|=======================
+
+== Custom Security Integration
+
+The default support for AWS security only maps the principal name to Quarkus security
+APIs and does nothing to map claims or roles or permissions.  You have can full control
+how security metadata in the lambda HTTP event is mapped to Quarkus security APIs using
+implementations of the `io.quarkus.amazon.lambda.http.LambdaIdentityProvider`
+interface.  By implementing this interface, you can do things like define role mappings for your principal
+or publish additional attributes provided by IAM or Cognito or your Custom Lambda security integration.
+
+.HTTP `quarkus-amazon-lambda-http`
+[source, java]
+----
+package io.quarkus.amazon.lambda.http;
+
+/**
+ * Helper interface that removes some boilerplate for creating
+ * an IdentityProvider that processes APIGatewayV2HTTPEvent
+ */
+public interface LambdaIdentityProvider extends IdentityProvider<LambdaAuthenticationRequest> {
+    @Override
+    default public Class<LambdaAuthenticationRequest> getRequestType() {
+        return LambdaAuthenticationRequest.class;
+    }
+
+    @Override
+    default Uni<SecurityIdentity> authenticate(LambdaAuthenticationRequest request, AuthenticationRequestContext context) {
+        APIGatewayV2HTTPEvent event = request.getEvent();
+        SecurityIdentity identity = authenticate(event);
+        if (identity == null) {
+            return Uni.createFrom().optional(Optional.empty());
+        }
+        return Uni.createFrom().item(identity);
+    }
+
+    /**
+     * You must override this method unless you directly override
+     * IdentityProvider.authenticate
+     *
+     * @param event
+     * @return
+     */
+    default SecurityIdentity authenticate(APIGatewayV2HTTPEvent event) {
+        throw new IllegalStateException("You must override this method or IdentityProvider.authenticate");
+    }
+}
+----
+
+For HTTP, the important method to override is `LambdaIdentityProvider.authenticate(APIGatewayV2HTTPEvent event)`.  From this
+you will allocate a SecurityIdentity based on how you want to map security data from `APIGatewayV2HTTPEvent`
+
+.REST `quarkus-amazon-lambda-rest`
+[source, java]
+----
+package io.quarkus.amazon.lambda.http;
+
+import java.util.Optional;
+
+import com.amazonaws.services.lambda.runtime.events.APIGatewayV2HTTPEvent;
+
+import io.quarkus.amazon.lambda.http.model.AwsProxyRequest;
+import io.quarkus.security.identity.AuthenticationRequestContext;
+import io.quarkus.security.identity.IdentityProvider;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.smallrye.mutiny.Uni;
+
+/**
+ * Helper interface that removes some boilerplate for creating
+ * an IdentityProvider that processes APIGatewayV2HTTPEvent
+ */
+public interface LambdaIdentityProvider extends IdentityProvider<LambdaAuthenticationRequest> {
+...
+
+    /**
+     * You must override this method unless you directly override
+     * IdentityProvider.authenticate
+     *
+     * @param event
+     * @return
+     */
+    default SecurityIdentity authenticate(AwsProxyRequest event) {
+        throw new IllegalStateException("You must override this method or IdentityProvider.authenticate");
+    }
+}
+----
+
+For REST, the important method to override is `LambdaIdentityProvider.authenticate(AwsProxyRequest event)`.  From this
+you will allocate a SecurityIdentity based on how you want to map security data from `AwsProxyRequest`.
+
+Your implemented provider must be a CDI bean.  Here's an example:
+
+[source,java]
+----
+package org.acme;
+
+import java.security.Principal;
+
+import javax.enterprise.context.ApplicationScoped;
+
+import com.amazonaws.services.lambda.runtime.events.APIGatewayV2HTTPEvent;
+
+import io.quarkus.amazon.lambda.http.LambdaIdentityProvider;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.quarkus.security.runtime.QuarkusPrincipal;
+import io.quarkus.security.runtime.QuarkusSecurityIdentity;
+
+@ApplicationScoped
+public class CustomSecurityProvider implements LambdaIdentityProvider {
+    @Override
+    public SecurityIdentity authenticate(APIGatewayV2HTTPEvent event) {
+        if (event.getHeaders() == null || !event.getHeaders().containsKey("x-user"))
+            return null;
+        Principal principal = new QuarkusPrincipal(event.getHeaders().get("x-user"));
+        QuarkusSecurityIdentity.Builder builder = QuarkusSecurityIdentity.builder();
+        builder.setPrincipal(principal);
+        return builder.build();
+    }
+}
+----
+
+Here's the same example, but with the AWS Gateway REST API:
+
+[source,java]
+----
+package org.acme;
+
+import java.security.Principal;
+
+import javax.enterprise.context.ApplicationScoped;
+
+import io.quarkus.amazon.lambda.http.model.AwsProxyRequest;
+
+import io.quarkus.amazon.lambda.http.LambdaIdentityProvider;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.quarkus.security.runtime.QuarkusPrincipal;
+import io.quarkus.security.runtime.QuarkusSecurityIdentity;
+
+@ApplicationScoped
+public class CustomSecurityProvider implements LambdaIdentityProvider {
+    @Override
+    public SecurityIdentity authenticate(AwsProxyRequest event) {
+        if (event.getMultiValueHeaders() == null || !event.getMultiValueHeaders().containsKey("x-user"))
+            return null;
+        Principal principal = new QuarkusPrincipal(event.getMultiValueHeaders().getFirst("x-user"));
+        QuarkusSecurityIdentity.Builder builder = QuarkusSecurityIdentity.builder();
+        builder.setPrincipal(principal);
+        return builder.build();
+    }
+}
+----
+
+Quarkus should automatically discover this implementation and use it instead of the default implementation
+discussed earlier.
+
+== Simple SAM Local Principal
+
+If you are testing your application with `sam local` you can
+hardcode a principal name to use when your application runs by setting
+the `QUARKUS_AWS_LAMBDA_FORCE_USER_NAME` environment variable

extensions/amazon-lambda-http/deployment/pom.xml

@@ -19,6 +19,10 @@
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-core-deployment</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-security-deployment</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-vertx-http-deployment</artifactId>

extensions/amazon-lambda-http/deployment/src/main/java/io/quarkus/amazon/lambda/http/deployment/AmazonLambdaHttpProcessor.java

@@ -7,9 +7,12 @@
 
 import io.quarkus.amazon.lambda.deployment.LambdaUtil;
 import io.quarkus.amazon.lambda.deployment.ProvidedAmazonLambdaHandlerBuildItem;
+import io.quarkus.amazon.lambda.http.DefaultLambdaIdentityProvider;
+import io.quarkus.amazon.lambda.http.LambdaHttpAuthenticationMechanism;
 import io.quarkus.amazon.lambda.http.LambdaHttpHandler;
 import io.quarkus.amazon.lambda.http.model.Headers;
 import io.quarkus.amazon.lambda.http.model.MultiValuedTreeMap;
+import io.quarkus.arc.deployment.AdditionalBeanBuildItem;
 import io.quarkus.deployment.annotations.BuildProducer;
 import io.quarkus.deployment.annotations.BuildStep;
 import io.quarkus.deployment.builditem.LaunchModeBuildItem;
@@ -24,6 +27,19 @@
 public class AmazonLambdaHttpProcessor {
     private static final Logger log = Logger.getLogger(AmazonLambdaHttpProcessor.class);
 
+    @BuildStep
+    public void setupSecurity(BuildProducer<AdditionalBeanBuildItem> additionalBeans,
+            LambdaHttpBuildTimeConfig config) {
+        if (!config.enableSecurity)
+            return;
+
+        AdditionalBeanBuildItem.Builder builder = AdditionalBeanBuildItem.builder().setUnremovable();
+
+        builder.addBeanClass(LambdaHttpAuthenticationMechanism.class)
+                .addBeanClass(DefaultLambdaIdentityProvider.class);
+        additionalBeans.produce(builder.build());
+    }
+
     @BuildStep
     public RequireVirtualHttpBuildItem requestVirtualHttp(LaunchModeBuildItem launchMode) {
         return launchMode.getLaunchMode() == LaunchMode.NORMAL ? RequireVirtualHttpBuildItem.MARKER : null;

extensions/amazon-lambda-http/deployment/src/main/java/io/quarkus/amazon/lambda/http/deployment/LambdaHttpBuildTimeConfig.java

@@ -0,0 +1,14 @@
+package io.quarkus.amazon.lambda.http.deployment;
+
+import io.quarkus.runtime.annotations.ConfigItem;
+import io.quarkus.runtime.annotations.ConfigRoot;
+
+@ConfigRoot
+public class LambdaHttpBuildTimeConfig {
+    /**
+     * Enable security mechanisms to process lambda and AWS based security (i.e. Cognito, IAM) from
+     * the http event sent from API Gateway
+     */
+    @ConfigItem(defaultValue = "false")
+    public boolean enableSecurity;
+}

extensions/amazon-lambda-http/runtime/pom.xml

@@ -20,6 +20,10 @@
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-vertx-http</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-security</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-amazon-lambda</artifactId>

extensions/amazon-lambda-http/runtime/src/main/java/io/quarkus/amazon/lambda/http/CognitoPrincipal.java

@@ -0,0 +1,30 @@
+package io.quarkus.amazon.lambda.http;
+
+import java.security.Principal;
+
+import com.amazonaws.services.lambda.runtime.events.APIGatewayV2HTTPEvent;
+
+/**
+ * Represents a Cognito JWT used to authenticate request
+ *
+ * Will only be allocated if requestContext.authorizer.jwt.claims.cognito:username is set
+ * in the http event sent by API Gateway
+ */
+public class CognitoPrincipal implements Principal {
+    private APIGatewayV2HTTPEvent.RequestContext.Authorizer.JWT jwt;
+    private String name;
+
+    public CognitoPrincipal(APIGatewayV2HTTPEvent.RequestContext.Authorizer.JWT jwt) {
+        this.jwt = jwt;
+        this.name = jwt.getClaims().get("cognito:username");
+    }
+
+    @Override
+    public String getName() {
+        return name;
+    }
+
+    public APIGatewayV2HTTPEvent.RequestContext.Authorizer.JWT getClaims() {
+        return jwt;
+    }
+}

extensions/amazon-lambda-http/runtime/src/main/java/io/quarkus/amazon/lambda/http/CustomPrincipal.java

@@ -0,0 +1,30 @@
+package io.quarkus.amazon.lambda.http;
+
+import java.security.Principal;
+import java.util.Map;
+
+/**
+ * Represents a custom principal sent by API Gateway i.e. a Lambda authorizer
+ *
+ * Will only be allocated if requestContext.authorizer.lambda.principalId is set
+ * in the http event sent by API Gateway
+ *
+ */
+public class CustomPrincipal implements Principal {
+    private String name;
+    private Map<String, Object> claims;
+
+    public CustomPrincipal(String name, Map<String, Object> claims) {
+        this.claims = claims;
+        this.name = name;
+    }
+
+    @Override
+    public String getName() {
+        return name;
+    }
+
+    public Map<String, Object> getClaims() {
+        return claims;
+    }
+}

extensions/amazon-lambda-http/runtime/src/main/java/io/quarkus/amazon/lambda/http/DefaultLambdaAuthenticationRequest.java

@@ -0,0 +1,20 @@
+package io.quarkus.amazon.lambda.http;
+
+import com.amazonaws.services.lambda.runtime.events.APIGatewayV2HTTPEvent;
+
+import io.quarkus.security.identity.request.BaseAuthenticationRequest;
+
+/**
+ * This will execute if and only if there is no identity after invoking a LambdaAuthenticationRequest
+ */
+final public class DefaultLambdaAuthenticationRequest extends BaseAuthenticationRequest {
+    private APIGatewayV2HTTPEvent event;
+
+    public DefaultLambdaAuthenticationRequest(APIGatewayV2HTTPEvent event) {
+        this.event = event;
+    }
+
+    public APIGatewayV2HTTPEvent getEvent() {
+        return event;
+    }
+}