@aws-sdk/credential-providers 3.918.0 → 3.920.0

package/README.md

@@ -7,26 +7,29 @@ A collection of all credential providers.
 
 # Table of Contents
 
-1. [Terminology](#terminology)
-1. [From Cognito Identity](#fromcognitoidentity)
-1. [From Cognito Identity Pool](#fromcognitoidentitypool)
-1. [From Temporary Credentials](#fromtemporarycredentials)
-1. [From Web Token](#fromwebtoken)
-   1. [Examples](#examples)
-1. [From Token File](#fromtokenfile)
-1. [From Instance and Container Metadata Service](#fromcontainermetadata-and-frominstancemetadata)
-1. [From HTTP(S)](#fromhttp)
-1. [From Shared INI files](#fromini)
-   1. [Sample Files](#sample-files)
-1. [From Environmental Variables](#fromenv)
-1. [From Credential Process](#fromprocess)
-   1. [Sample files](#sample-files-1)
-1. [From Single Sign-On Service](#fromsso)
-   1. [Supported Configuration](#supported-configuration)
-   1. [SSO login with AWS CLI](#sso-login-with-the-aws-cli)
-   1. [Sample Files](#sample-files-2)
-1. [From Node.js default credentials provider chain](#fromnodeproviderchain)
-1. [Creating a custom credentials chain](#createcredentialchain)
+- [Terminology](#terminology)
+  - [Credentials Provider](#credentials-provider)
+  - [Outer and inner clients](#outer-and-inner-clients)
+- [Resolving AWS Region in credential providers (e.g. STS region)](#resolving-aws-region-in-credential-providers-eg-sts-region)
+- [From Cognito Identity](#fromcognitoidentity)
+- [From Cognito Identity Pool](#fromcognitoidentitypool)
+- [From Temporary Credentials](#fromtemporarycredentials)
+- [From Web Token](#fromwebtoken)
+  - [Examples](#examples)
+- [From Token File](#fromtokenfile)
+- [From Instance and Container Metadata Service](#fromcontainermetadata-and-frominstancemetadata)
+- [From HTTP(S)](#fromhttp)
+- [From Shared INI files](#fromini)
+  - [Sample Files](#sample-files)
+- [From Environmental Variables](#fromenv)
+- [From Credential Process](#fromprocess)
+  - [Sample files](#sample-files-1)
+- [From Single Sign-On Service](#fromsso)
+  - [Supported Configuration](#supported-configuration)
+  - [SSO login with AWS CLI](#sso-login-with-the-aws-cli)
+  - [Sample Files](#sample-files-2)
+- [From Node.js default credentials provider chain](#fromnodeproviderchain)
+- [Creating a custom credentials chain](#createcredentialchain)
 
 ## Terminology
 
@@ -59,6 +62,17 @@ An `AwsCredentialIdentityProvider` is any function that matches the signature:
   }>;
 ```
 
+That is, an async function which returns an object containing AWS credentials.
+
+Whether you write your own such function or use one of the providers from this package, when used in
+conjunction with an AWS SDK Client, the client will cache the resulting credentials
+until there is less than 5 minutes remaining to their expiration, at which point the
+function will be called again, and the new credentials cached.
+
+This is designed to minimize the number of credential requests. Each client
+instance has a separate cache of credentials, so if you want to share credential caching
+between clients, you'll need to implement your own cache outside the SDK.
+
 #### Outer and inner clients
 
 A "parent/outer/upper/caller" (position), or "data" (purpose) client refers
@@ -80,6 +94,77 @@ In the above example, `S3Client` is the outer client, and
 if the `fromIni` credentials provider uses STS::AssumeRole, the
 `STSClient` initialized by the SDK is the inner client.
 
+## Resolving AWS Region in credential providers (e.g. STS region)
+
+When a credential provider uses an SDK client to retrieve credentials, commonly STS, the
+control of the STS region follows this logic:
+
+```js
+import { fromIni } from "@aws-sdk/credential-providers";
+
+/*
+# AWS config file contents
+[profile default]
+region = profile-region
+role_arn = ROLE_ARN
+source_profile = assume
+
+[profile assume]
+...
+ */
+
+process.env.AWS_REGION = "env-region";
+
+const provider = fromIni({
+  clientConfig: {
+    region: "credential-provider-config-region",
+  },
+});
+
+const client = new SDKClient({
+  region: "context-client-region",
+  credentials: provider,
+});
+
+const fallbackRegion = "us-east-1";
+```
+
+As shown above, there are many sources of region information. The priority order is:
+
+1. `credential-provider-config-region` - given in code to the credential provider itself.
+2. `profile-region` **\*** - if credential provider is resolving credentials from the config file, the config file's
+   region takes precedence in this case over AWS_REGION env.
+3. `context-client-region` - the region resolved by an SDK client using the credential provider.
+4. `env-region` - AWS_REGION environment variable.
+5. `profile-region` **\*** - if credential provider is not resolving credentials from the config file, the config file's
+   region is lower priority than AWS_REGION env.
+6. `us-east-1` (fallback) - this is a legacy fallback value. It's more likely that the client will fail to execute any
+   operation if none of the other region sources were set.
+
+This differs from _direct_ instantiation of the STSClient, which follows this order, which is the same for all clients:
+
+```js
+import { STSClient } from "@aws-sdk/client-sts";
+/*
+# AWS config file contents
+[profile default]
+region = profile-region
+ */
+
+process.env.AWS_REGION = "env-region";
+
+const client = new STSClient({
+  region: "client-region",
+});
+```
+
+1. `client-region`
+2. `env-region`
+3. `profile-region` (config file)
+4. thrown error (no us-east-1 fallback)
+
+# Credential providers
+
 ## `fromCognitoIdentity()`
 
 - Uses `@aws-sdk/client-cognito-identity`
@@ -91,7 +176,6 @@ for more information.
 
 ```javascript
 import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromCognitoIdentity } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   region,
@@ -133,7 +217,6 @@ Results from `GetId` are cached internally, but results from `GetCredentialsForI
 
 ```javascript
 import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromCognitoIdentityPool } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   region,
@@ -178,7 +261,6 @@ credentials from [STS AssumeRole API][assumerole_api].
 
 ```javascript
 import { fromTemporaryCredentials } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromTemporaryCredentials } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   region,
@@ -217,12 +299,11 @@ const client = new FooClient({
 - Uses `@aws-sdk/client-sts`
 - Available in browsers & native apps
 
-The function `fromWebToken` returns `AwsCredentialIdentityProvider` that gets credentials calling
+The function `fromWebToken` returns an `AwsCredentialIdentityProvider` that gets credentials calling
 [STS AssumeRoleWithWebIdentity API][assumerolewithwebidentity_api]
 
 ```javascript
 import { fromWebToken } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromWebToken } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   region,
@@ -292,7 +373,6 @@ read from the ECS container metadata service and the EC2 instance metadata servi
 
 ```javascript
 import { fromInstanceMetadata } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromInstanceMetadata } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   credentials: fromInstanceMetadata({
@@ -308,7 +388,6 @@ const client = new FooClient({
 
 ```javascript
 import { fromContainerMetadata } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromContainerMetadata } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   credentials: fromContainerMetadata({
@@ -322,12 +401,12 @@ const client = new FooClient({
 });
 ```
 
-A `AwsCredentialIdentityProvider` function created with `fromContainerMetadata` will return a promise that will
+An `AwsCredentialIdentityProvider` function created with `fromContainerMetadata` will return a promise that will
 resolve with credentials for the IAM role associated with containers in an Amazon ECS task. Please
 see [IAM Roles for Tasks][iam_roles_for_tasks] for more information on using IAM roles with Amazon
 ECS.
 
-A `AwsCredentialIdentityProvider` function created with `fromInstanceMetadata` will return a promise that will
+An `AwsCredentialIdentityProvider` function created with `fromInstanceMetadata` will return a promise that will
 resolve with credentials for the IAM role associated with an EC2 instance.
 Please see [IAM Roles for Amazon EC2][iam_roles_for_ec2] for more information on using IAM roles
 with Amazon EC2. Both IMDSv1 (a request/response method) and IMDSv2 (a session-oriented method) are
@@ -369,7 +448,6 @@ Node.js:
 
 ```js
 import { fromHttp } from "@aws-sdk/credential-providers";
-// const { fromHttp } = require("@aws-sdk/credential-providers");
 
 const client = new FooClient({
   credentials: fromHttp({
@@ -454,7 +532,6 @@ credentials file will be given precedence over the profile found in the config f
 
 ```javascript
 import { fromIni } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromIni } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   // As of v3.714.0, an easy way to select a profile is to set it on the client.
@@ -597,14 +674,13 @@ See [`fromSSO()`](#fromsso) for more information
 
 ```javascript
 import { fromEnv } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromEnv } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   credentials: fromEnv(),
 });
 ```
 
-`fromEnv` returns a `AwsCredentialIdentityProvider` function, that reads credentials from the following
+`fromEnv` returns an `AwsCredentialIdentityProvider` function, that reads credentials from the following
 environment variables:
 
 - `AWS_ACCESS_KEY_ID` - The access key for your AWS account.
@@ -624,7 +700,6 @@ contains a falsy value, the promise returned by the `fromEnv` function will be r
 
 ```javascript
 import { fromProcess } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromProcess } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   // Optional, available on clients as of v3.714.0.
@@ -647,7 +722,7 @@ const client = new FooClient({
 });
 ```
 
-`fromSharedConfigFiles` creates a `AwsCredentialIdentityProvider` functions that executes a given process and
+`fromProcess` creates an `AwsCredentialIdentityProvider` functions that executes a given process and
 attempt to read its standard output to receive a JSON payload containing the credentials. The
 process command is read from a shared credentials file at `~/.aws/credentials` and a shared
 configuration file at `~/.aws/config`. Both files are expected to be INI formatted with section
@@ -706,7 +781,6 @@ The function `fromTokenFile` returns `AwsCredentialIdentityProvider` that reads
 
 ```javascript
 import { fromTokenFile } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromTokenFile } = require("@aws-sdk/credential-providers"); // CommonJS import
 
 const client = new FooClient({
   region: "us-west-2",
@@ -714,8 +788,8 @@ const client = new FooClient({
     // Optional overrides. This is passed to an inner STS client
     // instantiated to resolve the credentials. Region is inherited
     // from the upper client if present unless overridden.
-    clientConfig: {}
-  });
+    clientConfig: {},
+  }),
 });
 ```
 
@@ -747,12 +821,11 @@ function. You can either load the SSO config from shared INI credential files, o
 
 ```javascript
 import { fromSSO } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromSSO } = require("@aws-sdk/credential-providers") // CommonJS import
 
 const client = new FooClient({
   // Optional, available on clients as of v3.714.0.
   profile: "my-sso-profile",
-  credentials: fromProcess({
+  credentials: fromSSO({
     // Optional. Defaults to the client's profile if that is set.
     // You can specify a profile here as well, but this applies
     // only to the credential resolution and not to the upper client.
@@ -876,7 +949,7 @@ messages be sent to the Instance Metadata Service
 
 ```js
 import { fromNodeProviderChain } from "@aws-sdk/credential-providers"; // ES6 import
-// const { fromNodeProviderChain } = require("@aws-sdk/credential-providers") // CommonJS import
+
 const credentialProvider = fromNodeProviderChain({
   // This provider accepts any input of fromEnv(), fromSSO(), fromTokenFile(),
   // fromIni(), fromProcess(), fromInstanceMetadata(), fromContainerMetadata()
@@ -898,20 +971,26 @@ const credentialProvider = fromNodeProviderChain({
 
 You can use this helper to create a credential chain of your own.
 
-A credential chain is created from a list of functions of the signature () => Promise<[AwsCredentialIdentity](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-types/Interface/AwsCredentialIdentity/)>,
+A credential chain is created from a list of functions of the signature () =>
+Promise<[AwsCredentialIdentity](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-types/Interface/AwsCredentialIdentity/)>,
 composed together such that the overall chain has the **same** signature.
 
-That is why you can provide the chained credential provider to the same field (`credentials`) as any single provider function.
+That is why you can provide the chained credential provider to the same field (`credentials`) as any single provider
+function.
 
 All the providers from this package are compatible, and can be used to create such a chain.
 
-As with _any_ function provided to the `credentials` SDK client constructor configuration field, if the credential object returned does not contain
-an `expiration` (type `Date`), the client will only ever call the provider function once. You do not need to memoize this function.
+As with _any_ function provided to the `credentials` SDK client constructor configuration field, if the credential
+object returned does not contain
+an `expiration` (type `Date`), the client will only ever call the provider function once. You do not need to memoize
+this function.
 
-To enable automatic refresh, the credential provider function should set an `expiration` (`Date`) field. When this expiration approaches within 5 minutes, the
+To enable automatic refresh, the credential provider function should set an `expiration` (`Date`) field. When this
+expiration approaches within 5 minutes, the
 provider function will be called again by the client in the course of making SDK requests.
 
-To assist with this, the `createCredentialChain` has a chainable helper `.expireAfter(milliseconds: number)`. An example is included below.
+To assist with this, the `createCredentialChain` has a chainable helper `.expireAfter(milliseconds: number)`. An example
+is included below.
 
 ```ts
 import { fromEnv, fromIni, createCredentialChain } from "@aws-sdk/credential-providers";

package/dist-cjs/createCredentialChain.js

@@ -25,13 +25,12 @@ const createCredentialChain = (...credentialProviders) => {
 exports.createCredentialChain = createCredentialChain;
 const propertyProviderChain = (...providers) => async (awsIdentityProperties) => {
     if (providers.length === 0) {
-        throw new property_provider_1.ProviderError("No providers in chain");
+        throw new property_provider_1.ProviderError("No providers in chain", { tryNextLink: false });
     }
     let lastProviderError;
     for (const provider of providers) {
         try {
-            const credentials = await provider(awsIdentityProperties);
-            return credentials;
+            return await provider(awsIdentityProperties);
         }
         catch (err) {
             lastProviderError = err;

package/dist-es/createCredentialChain.js

@@ -21,13 +21,12 @@ export const createCredentialChain = (...credentialProviders) => {
 };
 export const propertyProviderChain = (...providers) => async (awsIdentityProperties) => {
     if (providers.length === 0) {
-        throw new ProviderError("No providers in chain");
+        throw new ProviderError("No providers in chain", { tryNextLink: false });
     }
     let lastProviderError;
     for (const provider of providers) {
         try {
-            const credentials = await provider(awsIdentityProperties);
-            return credentials;
+            return await provider(awsIdentityProperties);
         }
         catch (err) {
             lastProviderError = err;

package/dist-types/fromSSO.d.ts

@@ -1,4 +1,4 @@
-import { FromSSOInit } from "@aws-sdk/credential-provider-sso";
+import { fromSSO as _fromSSO } from "@aws-sdk/credential-provider-sso";
 import { AwsCredentialIdentityProvider } from "@smithy/types";
 /**
  * Creates a credential provider function that reads from the _resolved_ access token from local disk then requests
@@ -43,4 +43,4 @@ import { AwsCredentialIdentityProvider } from "@smithy/types";
  *
  * @public
  */
-export declare const fromSSO: (init?: FromSSOInit) => AwsCredentialIdentityProvider;
+export declare const fromSSO: (init?: Parameters<typeof _fromSSO>[0]) => AwsCredentialIdentityProvider;

package/dist-types/ts3.4/fromSSO.d.ts

@@ -1,5 +1,5 @@
-import { FromSSOInit } from "@aws-sdk/credential-provider-sso";
+import { fromSSO as _fromSSO } from "@aws-sdk/credential-provider-sso";
 import { AwsCredentialIdentityProvider } from "@smithy/types";
 export declare const fromSSO: (
-  init?: FromSSOInit
+  init?: Parameters<typeof _fromSSO>[0]
 ) => AwsCredentialIdentityProvider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-sdk/credential-providers",
-  "version": "3.918.0",
+  "version": "3.920.0",
   "description": "A collection of credential providers, without requiring service clients like STS, Cognito",
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",
@@ -31,18 +31,18 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@aws-sdk/client-cognito-identity": "3.918.0",
-    "@aws-sdk/core": "3.916.0",
-    "@aws-sdk/credential-provider-cognito-identity": "3.918.0",
-    "@aws-sdk/credential-provider-env": "3.916.0",
-    "@aws-sdk/credential-provider-http": "3.916.0",
-    "@aws-sdk/credential-provider-ini": "3.918.0",
-    "@aws-sdk/credential-provider-node": "3.918.0",
-    "@aws-sdk/credential-provider-process": "3.916.0",
-    "@aws-sdk/credential-provider-sso": "3.916.0",
-    "@aws-sdk/credential-provider-web-identity": "3.918.0",
-    "@aws-sdk/nested-clients": "3.916.0",
-    "@aws-sdk/types": "3.914.0",
+    "@aws-sdk/client-cognito-identity": "3.920.0",
+    "@aws-sdk/core": "3.920.0",
+    "@aws-sdk/credential-provider-cognito-identity": "3.920.0",
+    "@aws-sdk/credential-provider-env": "3.920.0",
+    "@aws-sdk/credential-provider-http": "3.920.0",
+    "@aws-sdk/credential-provider-ini": "3.920.0",
+    "@aws-sdk/credential-provider-node": "3.920.0",
+    "@aws-sdk/credential-provider-process": "3.920.0",
+    "@aws-sdk/credential-provider-sso": "3.920.0",
+    "@aws-sdk/credential-provider-web-identity": "3.920.0",
+    "@aws-sdk/nested-clients": "3.920.0",
+    "@aws-sdk/types": "3.920.0",
     "@smithy/config-resolver": "^4.4.0",
     "@smithy/core": "^3.17.1",
     "@smithy/credential-provider-imds": "^4.2.3",