5.21 kBMarkdownView Raw
1# @aws-sdk/credential-provider-node
3[![NPM version](https://img.shields.io/npm/v/@aws-sdk/credential-provider-node/latest.svg)](https://www.npmjs.com/package/@aws-sdk/credential-provider-node)
4[![NPM downloads](https://img.shields.io/npm/dm/@aws-sdk/credential-provider-node.svg)](https://www.npmjs.com/package/@aws-sdk/credential-provider-node)
6## AWS Credential Provider for Node.JS
8This module provides a factory function, `fromEnv`, that will attempt to source
9AWS credentials from a Node.JS environment. It will attempt to find credentials
10from the following sources (listed in order of precedence):
12- Environment variables exposed via `process.env`
13- SSO credentials from token cache
14- Web identity token credentials
15- Shared credentials and config ini files
16- The EC2/ECS Instance Metadata Service
18The default credential provider will invoke one provider at a time and only
19continue to the next if no credentials have been located. For example, if the
20process finds values defined via the `AWS_ACCESS_KEY_ID` and
21`AWS_SECRET_ACCESS_KEY` environment variables, the files at `~/.aws/credentials`
22and `~/.aws/config` will not be read, nor will any messages be sent to the
23Instance Metadata Service.
25If invalid configuration is encountered (such as a profile in
26`~/.aws/credentials` specifying as its `source_profile` the name of a profile
27that does not exist), then the chained provider will be rejected with an error
28and will not invoke the next provider in the list.
30_IMPORTANT_: if you intend to acquire credentials using EKS
31[IAM Roles for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
32then you must explicitly specify a value for `roleAssumerWithWebIdentity`. There is a
33default function available in `@aws-sdk/client-sts` package. An example of using
37const { getDefaultRoleAssumerWithWebIdentity } = require("@aws-sdk/client-sts");
38const { defaultProvider } = require("@aws-sdk/credential-provider-node");
39const { S3Client, GetObjectCommand } = require("@aws-sdk/client-s3");
41const provider = defaultProvider({
42 roleAssumerWithWebIdentity: getDefaultRoleAssumerWithWebIdentity(),
45const client = new S3Client({ credentialDefaultProvider: provider });
48_IMPORTANT_: We provide a wrapper of this provider in `@aws-sdk/credential-providers`
49package to save you from importing `getDefaultRoleAssumerWithWebIdentity()` or
50`getDefaultRoleAssume()` from STS package. Similarly, you can do:
53const { fromNodeProviderChain } = require("@aws-sdk/credential-providers");
55const credentials = fromNodeProviderChain();
57const client = new S3Client({ credentials });
60## Supported configuration
62You may customize how credentials are resolved by providing an options hash to
63the `defaultProvider` factory function. The following options are
66- `profile` - The configuration profile to use. If not specified, the provider
67 will use the value in the `AWS_PROFILE` environment variable or a default of
68 `default`.
69- `filepath` - The path to the shared credentials file. If not specified, the
70 provider will use the value in the `AWS_SHARED_CREDENTIALS_FILE` environment
71 variable or a default of `~/.aws/credentials`.
72- `configFilepath` - The path to the shared config file. If not specified, the
73 provider will use the value in the `AWS_CONFIG_FILE` environment variable or a
74 default of `~/.aws/config`.
75- `mfaCodeProvider` - A function that returns a a promise fulfilled with an
76 MFA token code for the provided MFA Serial code. If a profile requires an MFA
77 code and `mfaCodeProvider` is not a valid function, the credential provider
78 promise will be rejected.
79- `roleAssumer` - A function that assumes a role and returns a promise
80 fulfilled with credentials for the assumed role. If not specified, the SDK
81 will create an STS client and call its `assumeRole` method.
82- `roleArn` - ARN to assume. If not specified, the provider will use the value
83 in the `AWS_ROLE_ARN` environment variable.
84- `webIdentityTokenFile` - File location of where the `OIDC` token is stored.
85 If not specified, the provider will use the value in the `AWS_WEB_IDENTITY_TOKEN_FILE`
86 environment variable.
87- `roleAssumerWithWebIdentity` - A function that assumes a role with web identity and
88 returns a promise fulfilled with credentials for the assumed role.
89- `timeout` - The connection timeout (in milliseconds) to apply to any remote
90 requests. If not specified, a default value of `1000` (one second) is used.
91- `maxRetries` - The maximum number of times any HTTP connections should be
92 retried. If not specified, a default value of `0` will be used.
94## Related packages:
96- [AWS Credential Provider for Node.JS - Environment Variables](../credential-provider-env)
97- [AWS Credential Provider for Node.JS - SSO](../credential-provider-sso)
98- [AWS Credential Provider for Node.JS - Web Identity](../credential-provider-web-identity)
99- [AWS Credential Provider for Node.JS - Shared Configuration Files](../credential-provider-ini)
100- [AWS Credential Provider for Node.JS - Instance and Container Metadata](../credential-provider-imds)
101- [AWS Shared Configuration File Loader](../shared-ini-file-loader)