Docs/Gateway: AWS Sigv4 (#6568)

Author: ardatan

packages/web/docs/src/content/gateway/authorization-authentication.mdx

@@ -24,6 +24,12 @@ gateway, and no other entity can execute requests to the subgraph on behalf of t
 
 </Callout>
 
+<Callout type="warning">
+  If you are looking for an authentication for subgraph requests via [AWS Signature Version 4
+  (Sigv4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html), you
+  can enable `awsSigv4` flag documented [here](/docs/gateway/other-features/security/aws-sigv4).
+</Callout>
+
 <Callout>
   You can refer to [Generic Auth plugin docs](https://www.npmjs.com/package/@envelop/generic-auth),
   if you need a more customized auth setup without JWT.

packages/web/docs/src/content/gateway/other-features/security/_meta.ts

@@ -6,6 +6,7 @@ export default {
   'disable-introspection': 'Introspection',
   https: 'HTTPS',
   'hmac-signature': 'HMAC Signature',
+  'aws-sigv4': 'AWS Signature V4',
   'audit-documents': 'Audit Documents',
   'block-field-suggestions': 'Block Field Suggestions',
   'character-limit': 'Character Limit',

packages/web/docs/src/content/gateway/other-features/security/aws-sigv4.mdx

@@ -0,0 +1,135 @@
+---
+searchable: false
+---
+
+# AWS Signature Version 4 (SigV4)
+
+Hive Gateway allows you to sign subgraph requests with
+[AWS Signature Version 4 (SigV4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)
+for secure communication between the Gateway and the subgraphs.
+
+```mermaid
+flowchart TD
+    A[Consumer] -->|GraphQL Request| B(Hive Gateway)
+    B --> C[Execution Engine]
+    C -->|Subgraph request| D[AWS Sigv4 Plugin]
+    D --> |Get the credentials| E[Assume Role I AM]
+    E --> F[Sign the request]
+    F --> |HTTP Request| G[Products Subgraph]
+    C -->|Subgraph request| H[AWS Sigv4 Plugin]
+    H --> |Get the credentials| I[Hard-coded configuration]
+    I --> J[Sign the request]
+    J --> |HTTP Request| K[Users Subgraph]
+```
+
+## How to use?
+
+You can enable AWS SigV4 signing by setting the `awsSigV4` option to `true` in the Gateway
+configuration.
+
+```ts filename="gateway.config.ts"
+import { defineConfig } from '@graphql-hive/gateway'
+
+export const gatewayConfig = defineConfig({
+  awsSigV4: true
+})
+```
+
+## Credentials
+
+By default, Hive Gateway will use the standard environment variables to get the AWS credentials. But
+you can also provide the credentials directly in the configuration.
+
+```ts filename="gateway.config.ts"
+import { defineConfig } from '@graphql-hive/gateway'
+
+export const gatewayConfig = defineConfig({
+  awsSigV4: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    region: process.env.AWS_REGION
+  }
+})
+```
+
+### Assume Role (IAM)
+
+You can provide the `roleArn` and `roleSessionName` to assume a role using the provided credentials.
+
+```ts filename="gateway.config.ts"
+import { defineConfig } from '@graphql-hive/gateway'
+
+export const gatewayConfig = defineConfig({
+  awsSigV4: {
+    region: process.env.AWS_REGION,
+    // By default it takes the credentials from the environment variables
+    roleArn: 'arn:aws:iam::123456789012:role/role-name', // process.env.AWS_ROLE_ARN
+    roleSessionName: 'session-name' // process.env.AWS_ROLE_SESSION_NAME
+  }
+})
+```
+
+## Service and region configuration
+
+By default, the plugin extracts the service and region from the URL of the subgraph. But you can
+also provide the service and region directly in the configuration.
+
+```ts filename="gateway.config.ts"
+import { defineConfig } from '@graphql-hive/gateway'
+
+export const gatewayConfig = defineConfig({
+  awsSigV4: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    region: process.env.AWS_REGION,
+    serviceName: 'lambda',
+    region: 'us-east-1'
+  }
+})
+```
+
+## Subgraph-specific configuration
+
+You can also configure the SigV4 signing for specific subgraphs by setting the `awsSigV4` option in
+the subgraph configuration.
+
+```ts filename="gateway.config.ts"
+import { defineConfig } from '@graphql-hive/gateway'
+
+export const gatewayConfig = defineConfig({
+  // Allowing SigV4 signing for only the 'products' subgraph
+  awsSigV4: subgraph => subgraph === 'products'
+})
+```
+
+or you can provide the credentials directly per subgraph.
+
+```ts filename="gateway.config.ts"
+import { defineConfig } from '@graphql-hive/gateway'
+
+export const gatewayConfig = defineConfig({
+  // Providing AWS SigV4 credentials for the 'products' and 'users' subgraphs separately
+  // And do not allow SigV4 signing for any other subgraph
+  awsSigV4(subgraph) {
+    // You can use hardcoded credentials for the 'products' subgraph
+    if (subgraph === 'products') {
+      return {
+        accessKeyId: process.env.PRODUCTS_AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.PRODUCTS_AWS_SECRET_ACCESS_KEY,
+        serviceName: 'lambda',
+        region: 'eu-west-1'
+      }
+    }
+    // You can use Assume Role for the 'users' subgraph
+    if (subgraph === 'users') {
+      return {
+        roleArn: 'arn:aws:iam::123456789012:role/role-name',
+        roleSessionName: 'session-name',
+        serviceName: 's3',
+        region: 'us-east-1'
+      }
+    }
+    return false
+  }
+})
+```