feat(apigatewayv2): http api - IAM authorizer support

packages/@aws-cdk/aws-apigatewayv2/README.md

@@ -284,6 +284,26 @@ API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-acces
 
 These authorizers can be found in the [APIGatewayV2-Authorizers](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-apigatewayv2-authorizers-readme.html) constructs library.
 
+In addition to these authorizers, API Gateway supports IAM via the included `HttpIamAuthorizer` and grant syntax:
+
+```ts
+declare const principal: iam.IGrantee;
+
+const authorizer = new apigwv2.HttpIamAuthorizer();
+
+const httpApi = new apigwv2.HttpApi(stack, 'HttpApi', {
+  httpApi,
+  defaultAuthorizer: authorizer,
+});
+
+const routes = httpApi.addRoute({
+  integration,
+  path: '/books/{book}',
+});
+
+routes[0].grantInvoke(principal);
+```
+
 ### Metrics
 
 The API Gateway v2 service sends metrics around the performance of HTTP APIs to Amazon CloudWatch.

packages/@aws-cdk/aws-apigatewayv2/lib/http/iam.ts

@@ -0,0 +1,12 @@
+import { IHttpRouteAuthorizer, HttpRouteAuthorizerBindOptions, HttpRouteAuthorizerConfig } from './authorizer';
+
+/**
+ * Authorize HTTP API Routes with IAM
+ */
+export class HttpIamAuthorizer implements IHttpRouteAuthorizer {
+  public bind(_options: HttpRouteAuthorizerBindOptions): HttpRouteAuthorizerConfig {
+    return {
+      authorizationType: 'AWS_IAM',
+    };
+  }
+}

packages/@aws-cdk/aws-apigatewayv2/lib/http/index.ts

@@ -4,3 +4,4 @@ export * from './integration';
 export * from './stage';
 export * from './vpc-link';
 export * from './authorizer';
+export * from './iam';

packages/@aws-cdk/aws-apigatewayv2/lib/http/route.ts

@@ -1,9 +1,11 @@
-import { Resource } from '@aws-cdk/core';
+import * as iam from '@aws-cdk/aws-iam';
+import { Resource, Lazy } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { CfnRoute, CfnRouteProps } from '../apigatewayv2.generated';
 import { IRoute } from '../common';
 import { IHttpApi } from './api';
-import { IHttpRouteAuthorizer } from './authorizer';
+import { HttpRouteAuthorizerConfig, IHttpRouteAuthorizer } from './authorizer';
+import { HttpIamAuthorizer } from './iam';
 import { HttpRouteIntegration } from './integration';
 
 /**
@@ -19,6 +21,28 @@ export interface IHttpRoute extends IRoute {
    * Returns the path component of this HTTP route, `undefined` if the path is the catch-all route.
    */
   readonly path?: string;
+
+  /**
+   * Returns the arn of the route.
+   * @attribute
+   */
+  readonly routeArn: string;
+
+  /**
+   * Grant access to invoke the route.
+   */
+  grantInvoke(grantee: iam.IGrantable, options?: GrantInvokeOptions): iam.Grant;
+}
+
+/**
+ * Options for granting invoke access.
+ */
+export interface GrantInvokeOptions {
+  /**
+   * The HTTP methods to allow.
+   * @default - the HttpMethod of the route
+   */
+  readonly httpMethods?: HttpMethod[];
 }
 
 /**
@@ -51,7 +75,7 @@ export class HttpRouteKey {
   /**
    * The catch-all route of the API, i.e., when no other routes match
    */
-  public static readonly DEFAULT = new HttpRouteKey('$default');
+  public static readonly DEFAULT = new HttpRouteKey(HttpMethod.ANY, '$default');
 
   /**
    * Create a route key with the combination of the path and the method.
@@ -61,9 +85,14 @@ export class HttpRouteKey {
     if (path !== '/' && (!path.startsWith('/') || path.endsWith('/'))) {
       throw new Error('A route path must always start with a "/" and not end with a "/"');
     }
-    return new HttpRouteKey(`${method ?? HttpMethod.ANY} ${path}`, path);
+    const keyMethod = method ?? HttpMethod.ANY;
+    return new HttpRouteKey(keyMethod, `${keyMethod} ${path}`, path);
   }
 
+  /**
+   * The method of the route
+   */
+  public readonly method: HttpMethod;
   /**
    * The key to the RouteKey as recognized by APIGateway
    */
@@ -74,7 +103,8 @@ export class HttpRouteKey {
    */
   public readonly path?: string;
 
-  private constructor(key: string, path?: string) {
+  private constructor(method: HttpMethod, key: string, path?: string) {
+    this.method = method;
     this.key = key;
     this.path = path;
   }
@@ -124,6 +154,9 @@ export interface HttpRouteProps extends BatchHttpRouteOptions {
  * Supported Route Authorizer types
  */
 enum HttpRouteAuthorizationType {
+  /** AWS IAM */
+  AWS_IAM = 'AWS_IAM',
+
   /** JSON Web Tokens */
   JWT = 'JWT',
 
@@ -142,50 +175,117 @@ export class HttpRoute extends Resource implements IHttpRoute {
   public readonly routeId: string;
   public readonly httpApi: IHttpApi;
   public readonly path?: string;
+  public readonly routeArn: string;
+
+  private readonly method: HttpMethod;
+  private authorizer?: IHttpRouteAuthorizer;
+  private authBindResult?: HttpRouteAuthorizerConfig;
 
   constructor(scope: Construct, id: string, props: HttpRouteProps) {
     super(scope, id);
 
     this.httpApi = props.httpApi;
     this.path = props.routeKey.path;
+    this.method = props.routeKey.method;
+    this.routeArn = this.produceRouteArn(props.routeKey.method);
+    this.authorizer = props.authorizer;
 
     const config = props.integration._bindToRoute({
       route: this,
       scope: this,
     });
 
-    const authBindResult = props.authorizer ? props.authorizer.bind({
-      route: this,
-      scope: this.httpApi instanceof Construct ? this.httpApi : this, // scope under the API if it's not imported
-    }) : undefined;
-
-    if (authBindResult && !(authBindResult.authorizationType in HttpRouteAuthorizationType)) {
-      throw new Error('authorizationType should either be JWT, CUSTOM, or NONE');
-    }
-
-    let authorizationScopes = authBindResult?.authorizationScopes;
-
-    if (authBindResult && props.authorizationScopes) {
-      authorizationScopes = Array.from(new Set([
-        ...authorizationScopes ?? [],
-        ...props.authorizationScopes,
-      ]));
-    }
-
-    if (authorizationScopes?.length === 0) {
-      authorizationScopes = undefined;
-    }
+    // Bind early to emit any exceptions as early as possible.
+    this.tryAuthorizerBinding();
 
     const routeProps: CfnRouteProps = {
       apiId: props.httpApi.apiId,
       routeKey: props.routeKey.key,
       target: `integrations/${config.integrationId}`,
-      authorizerId: authBindResult?.authorizerId,
-      authorizationType: authBindResult?.authorizationType ?? 'NONE', // must be explicitly NONE (not undefined) for stack updates to work correctly
-      authorizationScopes,
+      authorizerId: Lazy.string({ produce: () => this.authBindResult?.authorizerId }),
+      authorizationType: Lazy.string({
+        produce: () => {
+          // Provide the authorization type or explicitly 'NONE'. We must use
+          // 'NONE' and not undefined or CloudFormation doesn't remove an
+          // authorizer. @see https://github.com/aws/aws-cdk/pull/14424
+          return this.authBindResult?.authorizationType ?? 'NONE';
+        },
+      }),
+      authorizationScopes: Lazy.list({
+        produce: () => {
+          let authorizationScopes = this.authBindResult?.authorizationScopes;
+
+          if (this.authBindResult && props.authorizationScopes) {
+            authorizationScopes = Array.from(new Set([
+              ...authorizationScopes ?? [],
+              ...props.authorizationScopes,
+            ]));
+          }
+
+          if (authorizationScopes?.length === 0) {
+            authorizationScopes = undefined;
+          }
+
+          return authorizationScopes;
+        },
+      }),
     };
 
     const route = new CfnRoute(this, 'Resource', routeProps);
     this.routeId = route.ref;
   }
+
+  protected onPrepare() {
+    super.onPrepare();
+    this.tryAuthorizerBinding();
+  }
+
+  private tryAuthorizerBinding() {
+    if (this.authorizer && !this.authBindResult) {
+      this.authBindResult = this.authorizer.bind({
+        route: this,
+        scope: this.httpApi instanceof Construct ? this.httpApi : this, // scope under the API if it's not imported
+      });
+
+      if (!(this.authBindResult.authorizationType in HttpRouteAuthorizationType)) {
+        throw new Error('authorizationType should either be AWS_IAM, JWT, CUSTOM, or NONE');
+      }
+    }
+  }
+
+  private produceRouteArn(httpMethod: HttpMethod): string {
+    const stage = '*';
+    const iamHttpMethod = httpMethod === HttpMethod.ANY ? '*' : httpMethod;
+    const path = this.path ?? '/';
+    // When the user has provided a path with path variables, we replace the
+    // path variable and all that follows with a wildcard.
+    const iamPath = path.replace(/\{.*?\}.*/, '*');
+
+    return `arn:aws:execute-api:${this.stack.region}:${this.stack.account}:${this.httpApi.apiId}/${stage}/${iamHttpMethod}${iamPath}`;
+  }
+
+  public grantInvoke(grantee: iam.IGrantable, options: GrantInvokeOptions = {}): iam.Grant {
+    if (this.authorizer && !(this.authorizer instanceof HttpIamAuthorizer)) {
+      throw new Error('The authorizer has been set, so we cannot enable IAM authorization');
+    }
+
+    if (!this.authorizer) {
+      this.authorizer = new HttpIamAuthorizer();
+    }
+
+    const httpMethods = Array.from(new Set(options.httpMethods ?? [this.method]));
+    if (this.method !== HttpMethod.ANY && httpMethods.some(method => method !== this.method)) {
+      throw new Error('This route does not support granting invoke for all requested http methods');
+    }
+
+    const resourceArns = httpMethods.map(httpMethod => {
+      return this.produceRouteArn(httpMethod);
+    });
+
+    return iam.Grant.addToPrincipal({
+      grantee,
+      actions: ['execute-api:Invoke'],
+      resourceArns: resourceArns,
+    });
+  }
 }

packages/@aws-cdk/aws-apigatewayv2/rosetta/default.ts-fixture

@@ -3,6 +3,7 @@ import { Construct } from 'constructs';
 import { Duration, Stack } from '@aws-cdk/core';
 import * as apigwv2 from '@aws-cdk/aws-apigatewayv2';
 import * as lambda from '@aws-cdk/aws-lambda';
+import * as iam from '@aws-cdk/aws-iam';
 
 class Fixture extends Stack {
   constructor(scope: Construct, id: string) {