feat(storage): support S3 IAM role credentials

Author: nitin-bhadauria

apps/nestjs-backend/src/configs/storage.ts

@@ -46,6 +46,7 @@ export const storageConfig = registerAs('storage', () => ({
     internalForcePathStyle: process.env.BACKEND_STORAGE_S3_INTERNAL_FORCE_PATH_STYLE
       ? process.env.BACKEND_STORAGE_S3_INTERNAL_FORCE_PATH_STYLE === 'true'
       : undefined,
+    useIAMRole: process.env.BACKEND_STORAGE_S3_USE_IAM_ROLE === 'true',
   },
   uploadMethod: process.env.BACKEND_STORAGE_UPLOAD_METHOD ?? 'put',
   encryption: {

apps/nestjs-backend/src/features/attachments/plugins/s3-iam-role.spec.ts

@@ -0,0 +1,78 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { S3Client } from '@aws-sdk/client-s3';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { IStorageConfig } from '../../../configs/storage';
+import { S3Storage } from './s3';
+
+vi.mock('@aws-sdk/client-s3', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...(actual as object),
+    S3Client: vi.fn(function s3Client(this: unknown) {
+      return this;
+    }),
+  };
+});
+
+type StorageConfigOverrides = Partial<Omit<IStorageConfig, 's3'>> & {
+  s3?: Partial<IStorageConfig['s3']>;
+};
+
+const createConfig = (overrides: StorageConfigOverrides = {}): IStorageConfig => {
+  const { s3: s3Overrides, ...configOverrides } = overrides;
+  return {
+    provider: 's3',
+    publicBucket: 'public',
+    privateBucket: 'private',
+    s3: {
+      region: 'us-east-1',
+      endpoint: 'https://s3.us-east-1.amazonaws.com',
+      accessKey: 'access-key',
+      secretKey: 'secret-key',
+      maxSockets: 100,
+      forcePathStyle: false,
+      ...s3Overrides,
+    },
+    uploadMethod: 'put',
+    tokenExpireIn: '6d',
+    urlExpireIn: '6d',
+    ...configOverrides,
+  } as IStorageConfig;
+};
+
+describe('S3Storage IAM role credentials', () => {
+  beforeEach(() => {
+    vi.mocked(S3Client).mockClear();
+  });
+
+  it('uses configured static credentials by default', () => {
+    new S3Storage(createConfig());
+
+    expect(S3Client).toHaveBeenCalledWith(
+      expect.objectContaining({
+        credentials: {
+          accessKeyId: 'access-key',
+          secretAccessKey: 'secret-key',
+        },
+      })
+    );
+  });
+
+  it('omits credentials when S3 IAM role support is enabled', () => {
+    new S3Storage(
+      createConfig({
+        privateBucketEndpoint: 'https://private.example.com',
+        s3: {
+          useIAMRole: true,
+          internalEndpoint: 'https://s3.internal.example.com',
+          accessKey: undefined as any,
+          secretKey: undefined as any,
+        },
+      })
+    );
+
+    for (const [clientConfig] of vi.mocked(S3Client).mock.calls) {
+      expect(clientConfig).not.toHaveProperty('credentials');
+    }
+  });
+});

apps/nestjs-backend/src/features/attachments/plugins/s3.ts

@@ -56,6 +56,7 @@ export class S3Storage implements StorageAdapter {
       forcePathStyle,
       internalForcePathStyle,
     } = this.config.s3;
+    const useIAMRole = this.config.provider === 's3' && this.config.s3.useIAMRole;
     this.checkConfig();
     this.httpAgent = new http.Agent({
       maxSockets,
@@ -74,15 +75,20 @@ export class S3Storage implements StorageAdapter {
           httpsAgent: this.httpsAgent,
         })
       : undefined;
+    const s3Credentials = useIAMRole
+      ? {}
+      : {
+          credentials: {
+            accessKeyId: accessKey,
+            secretAccessKey: secretKey,
+          },
+        };
     this.s3Client = new S3Client({
       region,
       endpoint,
       forcePathStyle,
       requestHandler,
-      credentials: {
-        accessKeyId: accessKey,
-        secretAccessKey: secretKey,
-      },
+      ...s3Credentials,
     });
     // Reuse the same requestHandler (shared http/https agents) so the
     // maxSockets limit governs both public and internal endpoint traffic.
@@ -99,10 +105,7 @@ export class S3Storage implements StorageAdapter {
             endpoint: internalEndpoint ?? endpoint,
             forcePathStyle: internalPathStyle,
             requestHandler,
-            credentials: {
-              accessKeyId: accessKey,
-              secretAccessKey: secretKey,
-            },
+            ...s3Credentials,
           })
         : this.s3Client;
     fse.ensureDirSync(StorageAdapter.TEMPORARY_DIR);
@@ -113,10 +116,7 @@ export class S3Storage implements StorageAdapter {
           endpoint,
           bucketEndpoint: true,
           requestHandler,
-          credentials: {
-            accessKeyId: accessKey,
-            secretAccessKey: secretKey,
-          },
+          ...s3Credentials,
         })
       : this.s3Client;
 
@@ -199,14 +199,15 @@ export class S3Storage implements StorageAdapter {
         },
       });
     }
-    if (!this.config.s3.accessKey) {
+    const useIAMRole = this.config.provider === 's3' && this.config.s3.useIAMRole;
+    if (!useIAMRole && !this.config.s3.accessKey) {
       throw new CustomHttpException('S3 access key is required', HttpErrorCode.VALIDATION_ERROR, {
         localization: {
           i18nKey: 'httpErrors.attachment.s3AccessKeyRequired',
         },
       });
     }
-    if (!this.config.s3.secretKey) {
+    if (!useIAMRole && !this.config.s3.secretKey) {
       throw new CustomHttpException('S3 secret key is required', HttpErrorCode.VALIDATION_ERROR, {
         localization: {
           i18nKey: 'httpErrors.attachment.s3SecretKeyRequired',

apps/nextjs-app/.env.example

@@ -16,6 +16,8 @@ BACKEND_STORAGE_S3_ENDPOINT=https://s3.us-east-2.amazonaws.com
 BACKEND_STORAGE_PRIVATE_BUCKET_ENDPOINT=https://custom.domain
 # s3 internal endpoint, optional
 BACKEND_STORAGE_S3_INTERNAL_ENDPOINT=https://s3.us-east-2.amazonaws-internal.com
+# Set to true to use the AWS SDK default credential provider chain, such as an EC2/ECS IAM role
+BACKEND_STORAGE_S3_USE_IAM_ROLE=false
 BACKEND_STORAGE_S3_ACCESS_KEY=your_access_key
 BACKEND_STORAGE_S3_SECRET_KEY=your_secret_key