diff --git a/packages/credential-provider-ini/src/fromIni.spec.ts b/packages/credential-provider-ini/src/fromIni.spec.ts index ee86f5ff548a..1fcf9eb07263 100644 --- a/packages/credential-provider-ini/src/fromIni.spec.ts +++ b/packages/credential-provider-ini/src/fromIni.spec.ts @@ -72,4 +72,55 @@ describe(fromIni.name, () => { mockInitWithParentClientConfig ); }); + + describe("ignoreCache option", () => { + it("passes ignoreCache option to parseKnownFiles when true", async () => { + const initWithIgnoreCache = { ...mockInit, ignoreCache: true }; + const expectedInitWithParentClientConfig = { + ...mockInitWithParentClientConfig, + ignoreCache: true, + }; + + await fromIni(initWithIgnoreCache)(); + + expect(parseKnownFiles).toHaveBeenCalledWith(expectedInitWithParentClientConfig); + }); + + it("passes ignoreCache option to parseKnownFiles when false", async () => { + const initWithIgnoreCache = { ...mockInit, ignoreCache: false }; + const expectedInitWithParentClientConfig = { + ...mockInitWithParentClientConfig, + ignoreCache: false, + }; + + await fromIni(initWithIgnoreCache)(); + + expect(parseKnownFiles).toHaveBeenCalledWith(expectedInitWithParentClientConfig); + }); + + it("does not pass ignoreCache when option is undefined", async () => { + await fromIni(mockInit)(); + + expect(parseKnownFiles).toHaveBeenCalledWith(mockInitWithParentClientConfig); + expect(mockInitWithParentClientConfig).not.toHaveProperty("ignoreCache"); + }); + + it("preserves ignoreCache when merging with callerClientConfig", async () => { + const initWithIgnoreCache = { ...mockInit, ignoreCache: true }; + const callerConfig = { + profile: "otherProfile", + region: async () => "us-east-1", + }; + + await fromIni(initWithIgnoreCache)({ callerClientConfig: callerConfig }); + + expect(parseKnownFiles).toHaveBeenCalledWith( + expect.objectContaining({ + ignoreCache: true, + profile: mockProfileName, + parentClientConfig: expect.objectContaining(callerConfig), + }) + ); + }); + }); }); diff --git a/packages/credential-provider-ini/src/fromIni.ts b/packages/credential-provider-ini/src/fromIni.ts index 31c245c9e890..46e8cd0c5236 100644 --- a/packages/credential-provider-ini/src/fromIni.ts +++ b/packages/credential-provider-ini/src/fromIni.ts @@ -47,6 +47,12 @@ export interface FromIniInit extends SourceProfileInit, CredentialProviderOption clientConfig?: any; clientPlugins?: Pluggable[]; + + /** + * When true, always reload credentials from the file system instead of using cached values. + * This is useful when you need to detect changes to the credentials file. + */ + ignoreCache?: boolean; } /** diff --git a/supplemental-docs/CLIENTS.md b/supplemental-docs/CLIENTS.md index af573fc20bc0..66ab91f51a1b 100644 --- a/supplemental-docs/CLIENTS.md +++ b/supplemental-docs/CLIENTS.md @@ -151,6 +151,43 @@ const client = new S3Client({ }); ``` +#### Enabling uncached/refreshed credentials in `fromIni` credential provider + +`fromIni` credential provider accepts a boolean `ignoreCache` option which when true, always reloads credentials from the file system instead of using cached values. This is useful when you need to detect changes to the credentials file. + +Note: For temporary credentials that need regular refreshing, consider using `fromTemporaryCredentials` instead. + +Using ignoreCache with an S3 client: + +```typescript +import { S3Client } from "@aws-sdk/client-s3"; +import { fromIni } from "@aws-sdk/credential-providers"; + +// Create client with credentials that will reload from file +const client = new S3Client({ + credentials: fromIni({ ignoreCache: true }), +}); +``` + +For temporary credentials: + +You can use the `fromTemporaryCredentials` provider that creates a credential provider function that retrieves temporary credentials from STS AssumeRole API. Depending on your use-case, this might be the preferred way to use temporary credentials, as compared to having a `.ini` file with `ignoreCache` (that will utilize filesystem operations) set to true. + +```typescript +import { fromTemporaryCredentials } from "@aws-sdk/credential-providers"; + +// Better approach for temporary credentials that need regular refreshing +const client = new S3Client({ + credentials: fromTemporaryCredentials({ + // your temporary credentials config + }), +}); +``` + +- When using with AWS clients, the credential provider function is handled automatically. +- For temporary credentials that need regular refreshing, `fromTemporaryCredentials` is recommended over manual refresh with `ignoreCache`. +- Creating a new client instance ensures fresh credentials. + ### AWS Profile `profile` Available since [v3.714.0](https://github.com/aws/aws-sdk-js-v3/releases/tag/v3.714.0).