feat: add AWS SigV4 proxy integration #5041

nickvelloff · 2025-11-19T20:07:38Z

Summary

introduce the AWS SigV4 provider (docs, spec entry, logo, generated templates, and connect UI copy) so customers can create proxy integrations against AWS services
add the SigV4 auth flow on the backend (new /auth/aws-sigv4 controller, session/reconnect handling, validation, and reconnect defaults) plus expose the new auth type through the shared types & SDKs
add the signing/proxy helpers (shared proxy service + unit tests) and hook them into the connection service so signed calls pick up the correct base URL and ARN context

Testing

npm run test packages/shared/lib/services/proxy/aws-sigv4.unit.test.ts
npm run test packages/server/test/integration/connect/postReconnect.integration.test.ts
npm run test packages/server/test/integration/providerConfigKey/patchIntegration.integration.test.ts

Feature: AWS SigV4 Proxy Integration

This pull request introduces a new first-class 'AWS SigV4' provider, enabling proxy integrations with any AWS service through automatically signed requests. This is a comprehensive, full-stack feature that adds a new authentication flow to the backend, including a dedicated controller for handling sessions and fetching temporary credentials from customer-hosted STS endpoints. It also includes a shared service for SigV4 request signing, propagates the new AWS_SIGV4 authentication type across all SDKs and shared packages, and implements new UI components for both configuring the integration in the Nango dashboard and for the end-user connection flow in Connect UI.

The change is designed to be backward-compatible but introduces a new AuthType enum value. This allows Nango to securely proxy requests to AWS services without ever storing long-lived customer credentials, significantly enhancing security for AWS integrations.

Key Changes

• Introduced a new aws-sigv4 provider in providers.yaml and the OpenAPI specification.
• Added a new backend controller at /auth/aws-sigv4 in packages/server/lib/controllers/auth/postAwsSigV4.ts to manage the authentication flow, including session creation, validation, and fetching temporary credentials.
• Implemented a shared proxy service in packages/shared/lib/services/proxy/aws-sigv4.ts for building canonical requests and injecting SigV4 Authorization headers.
• Extended the AuthType enum with AWS_SIGV4 and propagated this change across @nangohq/types, the backend, and various SDKs.
• Developed a new UI section in packages/webapp/.../General.tsx for configuring AWS SigV4 integrations, including settings for the STS endpoint, AWS service, default region, and dynamic management of CloudFormation templates.
• Updated the Connect UI in packages/connect-ui/src/views/Go.tsx to handle the AWS_SIGV4 auth flow, providing inputs for IAM Role ARN and region, and displaying one-click CloudFormation deployment options.
• Added comprehensive documentation for the new AWS SigV4 provider in docs/integrations/all/aws-sigv4.mdx.
• Included new unit tests for the SigV4 signing logic and integration tests for the new backend endpoints.

Affected Areas

• Backend Authentication (packages/server/lib/controllers/auth/)
• Shared Services (packages/shared/lib/services/proxy/, packages/shared/lib/auth/)
• Type Definitions (packages/types/)
• Webapp UI (packages/webapp/src/pages/Integrations/)
• Connect UI (packages/connect-ui/src/views/)
• Node SDK (packages/node-client/)
• Runner SDK (packages/runner-sdk/)
• API Specification (docs/spec.yaml)
• Documentation (docs/)

This summary was automatically generated by @propel-code-bot

propel-code-bot · 2025-11-19T20:13:54Z

docs/integrations/all/aws-sigv4.mdx

+
+## Access requirements
+
+| Pre-Requisites | Status | Comment|


[Documentation]

Fix spelling: change "Pre-Requisites" to "Prerequisites".

Context for Agents

[**Documentation**] Fix spelling: change "Pre-Requisites" to "Prerequisites". File: docs/integrations/all/aws-sigv4.mdx Line: 18

propel-code-bot · 2025-11-19T20:13:55Z

docs/snippets/generated/aws-sigv4/PreBuiltTooling.mdx

+| Tools | Status |
+| - | - |
+| HTTP request logging | ✅ |
+| End-to-type type safety | ✅ |


[Documentation]

Fix typo: "End-to-type type safety" should be "End-to-end type safety".

Context for Agents

[**Documentation**] Fix typo: "End-to-type type safety" should be "End-to-end type safety". File: docs/snippets/generated/aws-sigv4/PreBuiltTooling.mdx Line: 26

propel-code-bot · 2025-11-19T20:13:55Z

docs/snippets/generated/aws-sigv4/PreBuiltTooling.mdx

+| Pre-configured rate-limit handling | 🚫 (time to contribute: &lt;48h) |
+| Per-customer configurations | ✅ |
+</Accordion>
+</AccordionGroup>


[Documentation]

Add a newline at the end of the file to avoid the “No newline at end of file” marker.

Context for Agents

[**Documentation**] Add a newline at the end of the file to avoid the “No newline at end of file” marker. File: docs/snippets/generated/aws-sigv4/PreBuiltTooling.mdx Line: 40

TBonnin · 2025-11-19T23:38:29Z

A few questions:

who is running/providing the STS helper service?
can you share the cloudformation template?

khaliqgant · 2025-11-20T12:03:24Z

who is running/providing the STS helper service?

Our users would have to run the STS helper service

TBonnin · 2025-11-20T19:24:13Z

who is running/providing the STS helper service?

Our users would have to run the STS helper service

With some cross-account sts assume role policy I imagine. I guess that what the cloudformation template is setting up. I would like to see the intended template.

nickvelloff · 2025-11-20T20:35:35Z

The intent is that the Nango customer runs their own STS helper container in their AWS account; it assumes roles on behalf of their end customers. That keeps Nango out of operating that lifecycle and cleanly separates responsibilities.

Nango could optionally “provide” a boilerplate service, but only as a contract/example (see https://github.com/nickvelloff/nango-sts-boilerplate). It’s deliberately simple.

CloudFormation templates are owned/hosted by the customer because they reflect their specific role needs. The only requirement is that the template URL is publicly readable (CORS-friendly) so the UI can hydrate parameters. Nango could host a few generic templates as defaults, but that’s just a nice-to-have. We assume anyone needing this enterprise-style integration already has the CloudFormation/DevOps maturity to host their own templates.

Cloudformation template example (https://raw.githubusercontent.com/nickvelloff/nango-sts-boilerplate/refs/heads/main/infra/cloudformation/s3-readonly.json) - simply hosted publicly.

Importantly: This file explains the usage and validation flows a customer would want to leverage when setting this up - https://github.com/nickvelloff/nango-sts-boilerplate/blob/main/docs/aws-sigv4-e2e-validation.md

fix: add missing AWS SigV4 error types and type fixes

propel-code-bot · 2025-12-04T19:33:53Z

docs/integrations/all/aws-sigv4.mdx

+
+## Access requirements
+
+| Pre-Requisites | Status | Comment|


[Documentation]

Fix table header formatting so the third column reads Comment without the trailing pipe character.

Context for Agents

[**Documentation**] Fix table header formatting so the third column reads `Comment` without the trailing pipe character. File: docs/integrations/all/aws-sigv4.mdx Line: 18

github-actions · 2026-01-04T16:02:36Z

This PR is stale because it has been open for 30 days with no activity.

propel-code-bot · 2026-01-04T16:06:31Z

docs/integrations/all/aws-sigv4/connect.mdx

+
+To finish connecting an AWS SigV4 integration, you (the end customer) need:
+
+1. **Access to your AWS account** – enough permission to deploy the CloudFormation template (or equivalent) your vendor provides.


[Documentation] Grammar: change "enough permission" to "enough permissions."

Context for Agents

[**Documentation**] Grammar: change "enough permission" to "enough permissions." File: docs/integrations/all/aws-sigv4/connect.mdx Line: 10

propel-code-bot · 2026-01-04T16:06:32Z

docs/snippets/generated/aws-sigv4/PreBuiltUseCases.mdx

@@ -0,0 +1,5 @@
+## Pre-built integrations
+
+_No pre-built integration yet (time to contribute: &lt;48h)_


[Documentation] Match the heading by pluralizing: change "No pre-built integration yet" to "No pre-built integrations yet."

Context for Agents

[**Documentation**] Match the heading by pluralizing: change "No pre-built integration yet" to "No pre-built integrations yet." File: docs/snippets/generated/aws-sigv4/PreBuiltUseCases.mdx Line: 3

propel-code-bot · 2026-01-04T16:06:33Z

docs/spec.yaml


        post:
+            operationId: postAuthAwsSigV4
            summary: Create an integration


[Documentation] The operationId postAuthAwsSigV4 does not match this generic "Create an integration" endpoint and makes the spec misleading. Please restore a generic name (e.g., the previous value) and reserve the SigV4-specific operationId for the new /auth/aws-sigv4/{providerConfigKey} route.

Context for Agents

[**Documentation**] The `operationId` `postAuthAwsSigV4` does not match this generic "Create an integration" endpoint and makes the spec misleading. Please restore a generic name (e.g., the previous value) and reserve the SigV4-specific operationId for the new `/auth/aws-sigv4/{providerConfigKey}` route. File: docs/spec.yaml Line: 95

propel-code-bot · 2026-01-04T16:06:33Z

docs/integrations/all/aws-sigv4.mdx

+  <Step title="Collect Role ARN & optional region during Connect">
+    1. Create a Connect session as usual. You can optionally pre-fill credential fields via `integrations_config_defaults` (see <a href="#pre-populating-credential-values">Pre-populating credential values</a>).  
+    2. The Connect UI shows your instructions, a one-click button for each template, **and a generated External ID**. Ask the customer to copy that External ID into their IAM trust policy before finishing the flow.  
+    3. When the end customer submits the form, Nango generates a unique ExternalId, calls your STS endpoint, tests the credentials via `GetCallerIdentity`, and stores a refreshable SigV4 credential.


[Documentation] Use consistent casing for the external ID. This line says "ExternalId" but the rest of the guide uses "External ID"/external_id. Update it to "External ID" (or external_id) for consistency.

Context for Agents

[**Documentation**] Use consistent casing for the external ID. This line says "ExternalId" but the rest of the guide uses "External ID"/`external_id`. Update it to "External ID" (or `external_id`) for consistency. File: docs/integrations/all/aws-sigv4.mdx Line: 48

nick-braintrust and others added 4 commits November 17, 2025 22:40

feat: add aws sigv4 integration

893b995

Validate AWS SigV4 custom config and pass reconnect defaults

2f13f41

Fix AWS SigV4 base URL derivation

234e694

Merge branch 'NangoHQ:master' into feat/aws-sig4

0310239

propel-code-bot bot reviewed Nov 19, 2025

View reviewed changes

arsalazarjr and others added 2 commits December 4, 2025 11:21

fix: add missing AWS SigV4 error types and type fixes

a4c054a

Merge pull request #1 from nickvelloff/aws-sigv4-fix-build

f12aa2e

fix: add missing AWS SigV4 error types and type fixes

propel-code-bot bot reviewed Dec 4, 2025

View reviewed changes

github-actions bot added the Stale label Jan 4, 2026

propel-code-bot bot reviewed Jan 4, 2026

View reviewed changes

github-actions bot removed the Stale label Jan 5, 2026


		To finish connecting an AWS SigV4 integration, you (the end customer) need:

		1. Access to your AWS account – enough permission to deploy the CloudFormation template (or equivalent) your vendor provides.

		@@ -0,0 +1,5 @@
		## Pre-built integrations

		_No pre-built integration yet (time to contribute: <48h)_

feat: add AWS SigV4 proxy integration #5041

Are you sure you want to change the base?

feat: add AWS SigV4 proxy integration #5041

Uh oh!

Conversation

nickvelloff commented Nov 19, 2025 • edited by propel-code-bot bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Uh oh!

propel-code-bot bot Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

propel-code-bot bot Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

propel-code-bot bot Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

TBonnin commented Nov 19, 2025

Uh oh!

khaliqgant commented Nov 20, 2025

Uh oh!

TBonnin commented Nov 20, 2025

Uh oh!

nickvelloff commented Nov 20, 2025

Uh oh!

propel-code-bot bot Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 4, 2026

Uh oh!

propel-code-bot bot Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

propel-code-bot bot Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

propel-code-bot bot Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

propel-code-bot bot Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nickvelloff commented Nov 19, 2025 •

edited by propel-code-bot bot

Loading