diff --git a/packages/web/docs/src/content/gateway/authorization-authentication.mdx b/packages/web/docs/src/content/gateway/authorization-authentication.mdx index 6a3c83283..d995f19a9 100644 --- a/packages/web/docs/src/content/gateway/authorization-authentication.mdx +++ b/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 + + 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). + + 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. diff --git a/packages/web/docs/src/content/gateway/other-features/security/_meta.ts b/packages/web/docs/src/content/gateway/other-features/security/_meta.ts index 06183d82b..e2ac92379 100644 --- a/packages/web/docs/src/content/gateway/other-features/security/_meta.ts +++ b/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', diff --git a/packages/web/docs/src/content/gateway/other-features/security/aws-sigv4.mdx b/packages/web/docs/src/content/gateway/other-features/security/aws-sigv4.mdx new file mode 100644 index 000000000..8558b753b --- /dev/null +++ b/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 + } +}) +```