Merge pull request #2782 from aws/api-key-passthrough

feat(gateway): allow API_KEY on passthrough targets

Author: mquang-amazon

src/projectSchemas/gateway.test.ts

@@ -14,6 +14,17 @@ const lambdaCompute = {
   implementation: { language: "Python" as const, path: "tools", handler: "handler.main" },
   pythonVersion: "PYTHON_3_12" as const,
 };
+const githubPassthrough = {
+  name: "github",
+  targetType: "passthrough",
+  passthrough: { endpoint: "https://api.github.com", protocolType: "CUSTOM" },
+};
+const apiKeyAuth = { type: "API_KEY", credentialName: "githubToken" };
+const targetIssues = (target: object) =>
+  AgentCoreGatewayTargetSchema.safeParse(target).error?.issues.map(({ path, message }) => ({
+    path,
+    message,
+  }));
 describe("gateway custom validation", () => {
   it("binds compute runtime versions to implementation languages", () => {
     expect(
@@ -236,6 +247,121 @@ describe("gateway custom validation", () => {
       }).success,
     ).toBe(true);
   });
+  it.each([
+    ["passthrough with no API key placement", githubPassthrough, {}],
+    [
+      "passthrough with an Authorization Bearer header",
+      githubPassthrough,
+      { location: "HEADER", parameterName: "Authorization", prefix: "Bearer" },
+    ],
+    [
+      "openApiSchema with an API key query parameter",
+      {
+        name: "weather",
+        targetType: "openApiSchema",
+        schemaSource: { inline: { path: "openapi.json" } },
+      },
+      { location: "QUERY_PARAMETER", parameterName: "api_key" },
+    ],
+    [
+      "apiGateway with a custom API key header",
+      {
+        name: "pets",
+        targetType: "apiGateway",
+        apiGateway: {
+          restApiId: "api",
+          stage: "prod",
+          apiGatewayToolConfiguration: { toolFilters: [{ filterPath: "/*", methods: ["GET"] }] },
+        },
+      },
+      { parameterName: "X-Pets-Key" },
+    ],
+    [
+      "a query parameter name with a colon",
+      githubPassthrough,
+      { location: "QUERY_PARAMETER", parameterName: "api:key" },
+    ],
+    [
+      "a query parameter name with brackets",
+      githubPassthrough,
+      { location: "QUERY_PARAMETER", parameterName: "auth[token]" },
+    ],
+  ])("accepts %s", (_case, target, placement) => {
+    expect(
+      targetIssues({ ...target, outboundAuth: { ...apiKeyAuth, ...placement } }),
+    ).toBeUndefined();
+  });
+  it.each([
+    [
+      "an unknown API key location",
+      { location: "BODY" },
+      ["outboundAuth", "location"],
+      'Invalid option: expected one of "HEADER"|"QUERY_PARAMETER"',
+    ],
+    [
+      "a parameterName over 64 characters",
+      { parameterName: "x".repeat(65) },
+      ["outboundAuth", "parameterName"],
+      "Too big: expected string to have <=64 characters",
+    ],
+    [
+      "a query parameter name over 64 characters",
+      { location: "QUERY_PARAMETER", parameterName: "x".repeat(65) },
+      ["outboundAuth", "parameterName"],
+      "Too big: expected string to have <=64 characters",
+    ],
+    [
+      "a HEADER parameterName with a colon",
+      { location: "HEADER", parameterName: "Authorization: " },
+      ["outboundAuth", "parameterName"],
+      "A HEADER API key's parameterName must be an HTTP header name, with no spaces or colons.",
+    ],
+    [
+      "a parameterName with spaces when location defaults to HEADER",
+      { parameterName: "x api key" },
+      ["outboundAuth", "parameterName"],
+      "A HEADER API key's parameterName must be an HTTP header name, with no spaces or colons.",
+    ],
+    [
+      "an empty API key prefix",
+      { prefix: "" },
+      ["outboundAuth", "prefix"],
+      "Too small: expected string to have >=1 characters",
+    ],
+    [
+      "an API key prefix over 64 characters",
+      { prefix: "x".repeat(65) },
+      ["outboundAuth", "prefix"],
+      "Too big: expected string to have <=64 characters",
+    ],
+    [
+      "QUERY_PARAMETER without a parameterName",
+      { location: "QUERY_PARAMETER" },
+      ["outboundAuth", "parameterName"],
+      "An API key with location QUERY_PARAMETER requires a parameterName.",
+    ],
+  ])("rejects %s", (_case, placement, path, message) => {
+    expect(
+      targetIssues({ ...githubPassthrough, outboundAuth: { ...apiKeyAuth, ...placement } }),
+    ).toEqual([{ path, message }]);
+  });
+  it("rejects API key placement fields with non-API_KEY outbound auth", () => {
+    expect(
+      targetIssues({
+        ...githubPassthrough,
+        outboundAuth: {
+          type: "OAUTH",
+          credentialName: "githubOauth",
+          parameterName: "Authorization",
+        },
+      }),
+    ).toEqual([
+      {
+        path: ["outboundAuth"],
+        message: "location, parameterName and prefix are only valid with API_KEY outbound auth.",
+      },
+    ]);
+  });
   it("requires JWT configuration when a gateway selects CUSTOM_JWT", () => {
     const gateway = { name: "gateway", targets: [] };
     expect(

src/projectSchemas/gateway.ts

@@ -48,13 +48,20 @@ export const OutboundAuthTypeSchema = z.enum([
   "JWT_PASSTHROUGH",
 ]);
 export type OutboundAuthType = z.infer<typeof OutboundAuthTypeSchema>;
+// An HTTP header name (RFC 9110 token). Rejects spaces and colons, so "Authorization: " fails
+// validation instead of the CloudFormation deploy. Query parameter names have no such rule: any
+// character can be percent-encoded (RFC 3986), so they're only length-checked.
+const HTTP_HEADER_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
 export const OutboundAuthSchema = z
   .object({
     type: OutboundAuthTypeSchema.default("NONE"),
     credentialName: z.string().min(1).optional(),
     scopes: z.array(z.string()).optional(),
     service: z.string().min(1).max(64).optional(),
     region: z.string().min(1).max(32).optional(),
+    location: z.enum(["HEADER", "QUERY_PARAMETER"]).optional(),
+    parameterName: z.string().min(1).max(64).optional(),
+    prefix: z.string().min(1).max(64).optional(),
   })
   .strict();
 export type OutboundAuth = z.infer<typeof OutboundAuthSchema>;
@@ -88,7 +95,7 @@ export const TARGET_TYPE_AUTH_CONFIG: Record<
   connector: { authRequired: false, validAuthTypes: [], iamRoleFallback: true },
   passthrough: {
     authRequired: true,
-    validAuthTypes: ["GATEWAY_IAM_ROLE", "OAUTH", "JWT_PASSTHROUGH"],
+    validAuthTypes: ["GATEWAY_IAM_ROLE", "OAUTH", "JWT_PASSTHROUGH", "API_KEY"],
     iamRoleFallback: false,
   },
 };
@@ -429,6 +436,43 @@ export const AgentCoreGatewayTargetSchema = z
           path: ["outboundAuth"],
         });
       }
+      if (
+        data.outboundAuth?.type !== "API_KEY" &&
+        (data.outboundAuth?.location !== undefined ||
+          data.outboundAuth?.parameterName !== undefined ||
+          data.outboundAuth?.prefix !== undefined)
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          message: "location, parameterName and prefix are only valid with API_KEY outbound auth.",
+          path: ["outboundAuth"],
+        });
+      }
+      if (
+        data.outboundAuth?.location === "QUERY_PARAMETER" &&
+        data.outboundAuth.parameterName === undefined
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          message: "An API key with location QUERY_PARAMETER requires a parameterName.",
+          path: ["outboundAuth", "parameterName"],
+        });
+      }
+      // location defaults to HEADER, so an unset location is checked as a header name.
+      const parameterName = data.outboundAuth?.parameterName;
+      if (
+        data.outboundAuth?.type === "API_KEY" &&
+        data.outboundAuth.location !== "QUERY_PARAMETER" &&
+        parameterName !== undefined &&
+        !HTTP_HEADER_NAME_PATTERN.test(parameterName)
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            "A HEADER API key's parameterName must be an HTTP header name, with no spaces or colons.",
+          path: ["outboundAuth", "parameterName"],
+        });
+      }
     }
   });
 export type AgentCoreGatewayTarget = z.infer<typeof AgentCoreGatewayTargetSchema>;