Skip to content

Commit

Permalink
feat(credential-providers): collect credential providers in single pa…
Browse files Browse the repository at this point in the history 
…ckage (#2672)

* feat(credential-providers): collect credential providers in public facing package

* feat(credential-providers): support temporary credentials provider

Equivalent to ChainableTemporaryCredentials class in v2 SDK. The provider
is not re-exported from standalone package or used in the credential-
provider-ini because the roleAssumers function interface in other
packages does not suite the usecase of this provider. In roleAssumer
interface, the master credential is required. It's not true for
fromTemporaryCredentials, where master credentials can be skipped,
in which case the default credential will be used.

* docs: remove inline import to improve docs

* docs(credentail-providers): wrap other providers and add README

* docs(credential-provider): mark other provider as internal

* docs(upgrading): update the upgrading guide

* docs: use clientConfig to override all creds providers client config

Co-authored-by: Trivikram Kamat <16024985+trivikr@users.noreply.github.com>
  • Loading branch information
@AllanZhengYP @trivikr
AllanZhengYP and trivikr committed Aug 18, 2021
1 parent fac5f27 commit 5375c91
Show file tree
Hide file tree
Showing 34 changed files with 1,983 additions and 567 deletions.
113 changes: 49 additions & 64 deletions UPGRADING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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({
masterCredentials: sourceCredentials,
params: { RoleArn },
}),
});
```

Expand All @@ -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

Expand All @@ -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: {
Expand All @@ -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: {
Expand All @@ -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({
Expand All @@ -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({
Expand Down Expand Up @@ -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({
Expand All @@ -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
}),
});
```
Expand All @@ -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 },
}),
});
```

Expand All @@ -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 },
}),
});
```

Expand Down
7 changes: 7 additions & 0 deletions packages/credential-provider-cognito-identity/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
19 changes: 4 additions & 15 deletions packages/credential-provider-env/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
32 changes: 4 additions & 28 deletions packages/credential-provider-imds/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading

0 comments on commit 5375c91

Please sign in to comment.