feat(credential-providers): collect credential providers in single package

UPGRADING.md

@@ -221,33 +221,25 @@ Default credential provider is how SDK resolve the AWS credential if you DO NOT
   masterCredentials during instantiation, precluding the ability to refresh credentials which require intermediate, temporary credentials.
 
   The original [`TemporaryCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html)
-  has been **deprecated** in favor of `ChainableTemporaryCredentials` in v2 and ``
+  has been **deprecated** in favor of `ChainableTemporaryCredentials` in v2.
 
-- **v3**: Partially supported. You can retrieve the temporary credential from STS with the
-  [role assumer function based on `sts:AssumeRole`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-sts/globals.html#getdefaultroleassumer). The difference to v2 is that `sts:getSessionToken` is not called
-  if no `RoleArn` is supplied. Please open a [feature request](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=)
-  if you need it.
-  Here's an example:
+- **v3**: [`Temporary Credentials Provider`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html).
+  You can call `fromTemporaryCredentials()` from `@aws-sdk/credential-providers` package. Here's an example:
 
   ```javascript
   import { FooClient } from "@aws-sdk/client-foo";
-  import { getDefaultRoleAssumer } from "@aws-sdk/client-sts"; // ES6 import
+  import { fromTemporaryCredentials } from "@aws-sdk/credential-providers"; // ES6 import
   // const { FooClient } = require("@aws-sdk/client-foo");
-  // const { getDefaultRoleAssumer } = require("@aws-sdk/client-sts"); // CommonJS import
+  // const { fromTemporaryCredentials } = require("@aws-sdk/credential-providers"); // CommonJS import
 
-  /* role assumer function that calls sts:AssumeRole API */
-  const roleAssumer = getDefaultRoleAssumer();
-  const sourceCredential = {
-    /* A credential can be a credential object or an async function that returns a credential object */
+  const sourceCredentials = {
+    // A credential can be a credential object or an async function that returns a credential object
   };
-  /* A credential can be a credential object or an async function that returns a credential object */
-  const derivativeCredentials = () =>
-    roleAssumer(sourceCredentials, {
-      RoleArn,
-      RoleSessionName,
-    });
   const client = new FooClient({
-    credentials: derivativeCredentials,
+    credentials: fromTemporaryCredentials({
+      sourceCredentials,
+      params: { RoleArn },
+    }),
   });
   ```
 
@@ -257,11 +249,11 @@ Load credentials from Cognito Identity service, normally used in browsers.
 
 - **v2**: [`CognitoIdentityCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html)
   Represents credentials retrieved from STS Web Identity Federation using the Amazon Cognito Identity service.
-- **v3**: [`Cognito Identity Credential Provider`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_cognito_identity.html#fromcognitoidentity-1)
-  The [`@aws/credential-provider-cognito-identity` package](https://www.npmjs.com/package/@aws-sdk/credential-provider-cognito-identity)
-  provides two credential provider functions, one of which [`fromCognitoIdentity`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_cognito_identity.html#fromcognitoidentity-1)
+- **v3**: [`Cognito Identity Credential Provider`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)
+  The [`@aws/credential-providers` package](https://www.npmjs.com/package/@aws-sdk/credential-providers)
+  provides two credential provider functions, one of which [`fromCognitoIdentity`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)
   takes an identity ID and calls `cognitoIdentity:GetCredentialsForIdentity`, while the other
-  [`fromCognitoIdentityPool`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_cognito_identity.html#fromcognitoidentitypool-1)
+  [`fromCognitoIdentityPool`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)
   takes an identity pool ID, calls `cognitoIdentity:GetId` on the first invocation, and then calls`fromCognitoIdentity`.
   Subsequent invocations of the latter do not re-invoke GetId
 
@@ -272,18 +264,13 @@ Load credentials from Cognito Identity service, normally used in browsers.
 
   ```javascript
   // fromCognitoIdentityPool example
-  import { fromCognitoIdentityPool } from "@aws-sdk/credential-provider-cognito-identity";
-  import { CognitoIdentityClient } from "@aws-sdk/client-cognito-identity"; // ES6 import
-  // const { fromCognitoIdentityPool } = require("@aws-sdk/credential-provider-cognito-identity");
-  // const { CognitoIdentityClient } = require("@aws-sdk/client-cognito-identity"); // CommonJS import
+  import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers"; // ES6 import
+  // const { fromCognitoIdentityPool } = require("@aws-sdk/credential-providers"); // CommonJS import
 
   const client = new FooClient({
     region: "us-east-1",
     credentials: fromCognitoIdentityPool({
-      client: new CognitoIdentityClient({
-        // specify Cognito Identity client config here
-        region: "us-east-1",
-      }),
+      clientConfig: cognitoIdentityClientConfig, // Optional
       identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
       customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
       logins: {
@@ -298,15 +285,13 @@ Load credentials from Cognito Identity service, normally used in browsers.
 
   ```javascript
   // fromCognitoIdentity example
-  import { fromCognitoIdentity } from "@aws-sdk/credential-provider-cognito-identity";
-  import { CognitoIdentityClient } from "@aws-sdk/client-cognito-identity"; // ES6 import
+  import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; // ES6 import
   // const { fromCognitoIdentity } = require("@aws-sdk/credential-provider-cognito-identity");
-  // const { CognitoIdentityClient } = require("@aws-sdk/client-cognito-identity"); // CommonJS import
 
   const client = new FooClient({
     region: "us-east-1",
     credentials: fromCognitoIdentity({
-      client: new CognitoIdentityClient({ region: "us-east-1" }),
+      clientConfig: cognitoIdentityClientConfig, // Optional
       identityId: "us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f",
       customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
       logins: {
@@ -324,11 +309,12 @@ Load credentials from Cognito Identity service, normally used in browsers.
 Represents credentials received from the metadata service on an EC2 instance.
 
 - **v2**: [`EC2MetadataCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html)
-- **v3**: [`fromInstanceMetadata`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_imds.html#frominstancemetadata-1): Creates a credential provider that will source credentials from the EC2 Instance Metadata Service.
+- **v3**: [`fromInstanceMetadata`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html):
+  Creates a credential provider that will source credentials from the EC2 Instance Metadata Service.
 
   ```javascript
-  import { fromInstanceMetadata } from "@aws-sdk/credential-provider-imds"; // ES6 import
-  // const { fromInstanceMetadata } = require("@aws-sdk/credential-provider-imds"); // CommonJS import
+  import { fromInstanceMetadata } from "@aws-sdk/credential-providers"; // ES6 import
+  // const { fromInstanceMetadata } = require("@aws-sdk/credential-providers"); // CommonJS import
 
   const client = new FooClient({
     credentials: fromInstanceMetadata({
@@ -345,11 +331,11 @@ URI specified by the `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` or the `AWS_CONTAI
 variable.
 
 - **v2**: `ECSCredentials` or [`RemoteCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html).
-- **v3**: [`fromContainerMetadata`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_imds.html#fromcontainermetadata-1) creates a credential provider that will source credentials from the ECS Container Metadata Service.
+- **v3**: [`fromContainerMetadata`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)
+  creates a credential provider that will source credentials from the ECS Container Metadata Service.
 
   ```javascript
-  import { fromContainerMetadata } from "@aws-sdk/credential-provider-imds"; // ES6 import
-  // const { fromContainerMetadata } = require("@aws-sdk/credential-provider-imds"); // CommonJS import
+  import { fromContainerMetadata } from "@aws-sdk/credential-providers"; // ES6 import
 
   const client = new FooClient({
     credentials: fromContainerMetadata({
@@ -382,13 +368,11 @@ refer to the [shared config and credentials files document](https://docs.aws.ama
 for more information.
 
 - **v2**: [`SharedIniFileCredentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html)
-- **v3**: [`fromIni`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_ini.html).
+- **v3**: [`fromIni`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html).
 
   ```javascript
-  import { fromIni } from "@aws-sdk/credential-provider-ini";
-  import { getDefaultRoleAssumer, getDefaultRoleAssumerWithWebIdentity } from "@aws-sdk/client-sts"; // ES6 import
-  // const { fromIni } from("@aws-sdk/credential-provider-ini");
-  // const { getDefaultRoleAssumer, getDefaultRoleAssumerWithWebIdentity } = require("@aws-sdk/client-sts"); // CommonJS import
+  import { fromIni } from "@aws-sdk/credential-providers";
+  // const { fromIni } from("@aws-sdk/credential-providers");
 
   const client = new FooClient({
     credentials: fromIni({
@@ -399,8 +383,7 @@ for more information.
         return "some_code";
       }, // Optional
       profile: "default", // Optional
-      roleAssumer: getDefaultRoleAssumer(), // Optional. Required if you specify role to assume
-      roleAssumerWithWebIdentity: getDefaultRoleAssumerWithWebIdentity(), // Optional. Required if you specify role to assume using `sts:AssumeRoleWithWebIdentity` API
+      clientConfig: { region }, // Optional
     }),
   });
   ```
@@ -413,17 +396,18 @@ Retrieves credentials using OIDC token from a file on disk. It's commonly used i
 - **v3**: [`fromTokenFile`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_web_identity.html#fromtokenfile-1)
 
   ```javascript
-  import { fromTokenFile } from "@aws-sdk/credential-provider-web-identity";
-  import { getDefaultRoleAssumerWithWebIdentity } from "@aws-sdk/client-sts"; // ES6 import
-  // const { fromIni } from("@aws-sdk/credential-provider-ini");
-  // const { getDefaultRoleAssumerWithWebIdentity } = require("@aws-sdk/client-sts"); // CommonJS import
+  import { fromTokenFile } from "@aws-sdk/credential-providers"; // ES6 import
+  // const { fromIni } from("@aws-sdk/credential-providers"); // CommonJS import
 
   const client = new FooClient({
     credentials: fromTokenFile({
-      roleAssumerWithWebIdentity: getDefaultRoleAssumerWithWebIdentity(),
-      roleArn: "arn:xxxx" // Optional. Otherwise read from `AWS_ROLE_ARN` environmental variable
-      roleSessionName: "session:a" // Optional. Otherwise read from `AWS_ROLE_SESSION_NAME` environmental variable
-    })
+      // Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
+      roleArn: "arn:xxxx",
+      // Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
+      roleSessionName: "session:a",
+      // Optional. STS client config to make the assume role request.
+      clientConfig: { region },
+    }),
   });
   ```
 
@@ -435,17 +419,18 @@ Retrieves credentials from STS web identity federation support.
 - **v3**: [`fromWebToken`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_provider_web_identity.html#fromwebtoken-1)
 
   ```javascript
-  import { fromWebToken } from "@aws-sdk/credential-provider-web-identity";
-  import { getDefaultRoleAssumerWithWebIdentity } from "@aws-sdk/client-sts"; // ES6 import
-  // const { fromWebToken } from("@aws-sdk/credential-provider-web-identity");
-  // const { getDefaultRoleAssumerWithWebIdentity } = require("@aws-sdk/client-sts"); // CommonJS import
+  import { fromWebToken } from "@aws-sdk/credential-providers"; // ES6 import
+  // const { fromWebToken } from("@aws-sdk/credential-providers"); // CommonJS import
 
   const client = new FooClient({
     credentials: fromWebToken({
-      roleAssumerWithWebIdentity: getDefaultRoleAssumerWithWebIdentity(),
-      roleArn: "arn:xxxx" // Otherwise read from `AWS_ROLE_ARN` environmental variable
-      roleSessionName: "session:a" // Otherwise read from `AWS_ROLE_SESSION_NAME` environmental variable
-    })
+      // Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
+      roleArn: "arn:xxxx",
+      // Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
+      roleSessionName: "session:a",
+      // Optional. STS client config to make the assume role request.
+      clientConfig: { region },
+    }),
   });
   ```
 

packages/credential-provider-cognito-identity/README.md

@@ -2,3 +2,10 @@
 
 [![NPM version](https://img.shields.io/npm/v/@aws-sdk/credential-provider-cognito-identity/latest.svg)](https://www.npmjs.com/package/@aws-sdk/credential-provider-cognito-identity)
 [![NPM downloads](https://img.shields.io/npm/dm/@aws-sdk/credential-provider-cognito-identity.svg)](https://www.npmjs.com/package/@aws-sdk/credential-provider-cognito-identity)
+
+> An internal package
+
+## Usage
+
+You probably shouldn't, at least directly. Please use [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers)
+instead.

packages/credential-provider-env/README.md

@@ -3,20 +3,9 @@
 [![NPM version](https://img.shields.io/npm/v/@aws-sdk/credential-provider-env/latest.svg)](https://www.npmjs.com/package/@aws-sdk/credential-provider-env)
 [![NPM downloads](https://img.shields.io/npm/dm/@aws-sdk/credential-provider-env.svg)](https://www.npmjs.com/package/@aws-sdk/credential-provider-env)
 
-## AWS Credential Provider for Node.JS - Environment Variables
+> An internal package
 
-This module provides a `CredentialProvider` function, `fromEnv`, that reads from
-the following environment variables:
+## Usage
 
-- `AWS_ACCESS_KEY_ID` - The access key for your AWS account.
-- `AWS_SECRET_ACCESS_KEY` - The secret key for your AWS account.
-- `AWS_SESSION_TOKEN` - The session key for your AWS account. This is only
-  needed when you are using temporary credentials.
-- `AWS_CREDENTIAL_EXPIRATION` - The expiration time of the credentials contained
-  in the environment variables described above. This value must be in a format
-  compatible with the [ISO-8601 standard](https://en.wikipedia.org/wiki/ISO_8601)
-  and is only needed when you are using temporary credentials.
-
-If either the `AWS_ACCESS_KEY_ID` or `AWS_SECRET_ACCESS_KEY` environment
-variable is not set or contains a falsy value, the promise returned by the
-`fromEnv` function will be rejected.
+You probably shouldn't, at least directly. Please use [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers)
+instead.

packages/credential-provider-imds/README.md

@@ -3,33 +3,9 @@
 [![NPM version](https://img.shields.io/npm/v/@aws-sdk/credential-provider-imds/latest.svg)](https://www.npmjs.com/package/@aws-sdk/credential-provider-imds)
 [![NPM downloads](https://img.shields.io/npm/dm/@aws-sdk/credential-provider-imds.svg)](https://www.npmjs.com/package/@aws-sdk/credential-provider-imds)
 
-## AWS Credential Provider for Node.JS - Instance and Container Metadata
+> An internal package
 
-This module provides two `CredentialProvider` factory functions,
-`fromContainerMetadata` and `fromInstanceMetadata`, that will create
-`CredentialProvider` functions that read from the ECS container metadata service
-and the EC2 instance metadata service, respectively.
+## Usage
 
-A `CredentialProvider` 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](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)
-for more information on using IAM roles with Amazon ECS.
-
-A `CredentialProvider` 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](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)
-for more information on using IAM roles with Amazon EC2.
-Both IMDSv1 (a request/response method) and IMDSv2 (a session-oriented method) are supported.
-Please see [Configure the instance metadata service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) for more information.
-
-## Supported configuration
-
-You may customize how credentials are resolved by providing an options hash to
-the `fromContainerMetadata` and `fromInstanceMetadata` factory functions. The
-following options are supported:
-
-- `timeout` - The connection timeout (in milliseconds) to apply to any remote
-  requests. If not specified, a default value of `1000` (one second) is used.
-- `maxRetries` - The maximum number of times any HTTP connections should be
-  retried. If not specified, a default value of `0` will be used.
+You probably shouldn't, at least directly. Please use [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers)
+instead.