@aws-sdk/credential-provider-ini

What is @aws-sdk/credential-provider-ini?

The @aws-sdk/credential-provider-ini package is a module that allows Node.js developers to load AWS credentials from INI-formatted files, such as the ones created by the AWS CLI. This package is part of the AWS SDK for JavaScript (v3) and is used to retrieve AWS credentials from local configuration files, enabling developers to authenticate AWS SDK calls.

What are @aws-sdk/credential-provider-ini's main functionalities?

Loading credentials from a shared INI file

This feature allows developers to load AWS credentials from a shared INI file, typically located at `~/.aws/credentials`. The `fromIni` function reads the file and returns the credentials for the default profile or a specified profile.

const { fromIni } = require('@aws-sdk/credential-provider-ini');
const credentials = fromIni();

Specifying a custom profile

Developers can specify a custom profile to load credentials for a specific AWS account or role. This is useful when working with multiple AWS accounts or when different permissions are needed.

const { fromIni } = require('@aws-sdk/credential-provider-ini');
const credentials = fromIni({ profile: 'myCustomProfile' });

Assuming a role with MFA

This feature supports assuming an IAM role that requires Multi-Factor Authentication (MFA). The `mfaCodeProvider` is a function that returns the MFA code, which is then used to assume the role.

const { fromIni } = require('@aws-sdk/credential-provider-ini');
const credentials = fromIni({
  profile: 'myRoleProfile',
  mfaCodeProvider: async () => '123456', // Replace with actual MFA code provider
});

Other packages similar to @aws-sdk/credential-provider-ini

aws-sdk

The original AWS SDK for JavaScript (v2) includes credential loading capabilities similar to @aws-sdk/credential-provider-ini. It allows loading credentials from INI files, but it is part of a larger package rather than a modular approach taken by the newer AWS SDK (v3).

aws-profile-utils

This package provides utilities for working with AWS profiles stored in INI files. It offers similar functionality for loading credentials but is not officially maintained by AWS and may not have the same level of support or integration with the AWS SDK.

awscred

awscred is another npm package that can load AWS credentials from various sources, including INI files. It provides a simple interface for retrieving credentials but does not offer the modular, per-service approach of the AWS SDK (v3).

README

@aws-sdk/credential-provider-ini

AWS Credential Provider for Node.JS - Shared Configuration Files

This module provides a function, fromIni that will create CredentialProvider functions that 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 names corresponding to profiles. Sections in the credentials file are treated as profile names, whereas profile sections in the config file must have the format of[profile profile-name], except for the default profile. Please see the sample files below for examples of well-formed configuration and credentials files.

Profiles that appear in both files will not be merged, and the version that appears in the credentials file will be given precedence over the profile found in the config file.

Supported configuration

You may customize how credentials are resolved by providing an options hash to the fromIni factory function. The following options are supported:

• profile - The configuration profile to use. If not specified, the provider will use the value in the AWS_PROFILE environment variable or a default of default.
• filepath - The path to the shared credentials file. If not specified, the provider will use the value in the AWS_SHARED_CREDENTIALS_FILE environment variable or a default of ~/.aws/credentials.
• configFilepath - The path to the shared config file. If not specified, the provider will use the value in the AWS_CONFIG_FILE environment variable or a default of ~/.aws/config.
• mfaCodeProvider - A function that returns a a promise fulfilled with an MFA token code for the provided MFA Serial code. If a profile requires an MFA code and mfaCodeProvider is not a valid function, the credential provider promise will be rejected.
• roleAssumer - A function that assumes a role and returns a promise fulfilled with credentials for the assumed role. You may call sts:assumeRole API within this function.
• roleAssumerWithWebIdentity - A function that assumes a role with web identity and returns a promise fulfilled with credentials for the assumed role. You may call sts:assumeRoleWithWebIdentity API within this function.

Sample files

~/.aws/credentials

[default]
aws_access_key_id=foo
aws_secret_access_key=bar

[dev]
aws_access_key_id=foo2
aws_secret_access_key=bar2

[prod]
aws_access_key_id=foo3
aws_secret_access_key=bar3

~/.aws/config

[default]
aws_access_key_id=foo
aws_secret_access_key=bar

[profile dev]
aws_access_key_id=foo2
aws_secret_access_key=bar2

[profile prod]
aws_access_key_id=foo3
aws_secret_access_key=bar3

[profile "testing host"]
aws_access_key_id=foo4
aws_secret_access_key=bar4

profile with source profile

[second]
aws_access_key_id=foo
aws_secret_access_key=bar

[first]
source_profile=second
role_arn=arn:aws:iam::123456789012:role/example-role-arn

profile with source provider

You can supply credential_source options to tell the SDK where to source credentials for the call to AssumeRole. The supported credential providers are listed bellow:

[default]
role_arn=arn:aws:iam::123456789012:role/example-role-arn
credential_source = Ec2InstanceMetadata

[default]
role_arn=arn:aws:iam::123456789012:role/example-role-arn
credential_source = Environment

[default]
role_arn=arn:aws:iam::123456789012:role/example-role-arn
credential_source = EcsContainer

profile with web_identity_token_file

[default]
web_identity_token_file=/temp/token
role_arn=arn:aws:iam::123456789012:role/example-role-arn

You can specify another profile(second) whose credentials are used to assume the role by the role_arn setting in this profile(first).

[second]
web_identity_token_file=/temp/token
role_arn=arn:aws:iam::123456789012:role/example-role-2

[first]
source_profile=second
role_arn=arn:aws:iam::123456789012:role/example-role

profile with sso credentials

Please refer the the sso credential provider package for how to configure the SSO credentials.

[default]
sso_account_id = 012345678901
sso_region = us-east-1
sso_role_name = SampleRole
sso_start_url = https://d-abc123.awsapps.com/start

You can specify another profile(second) whose credentials derived from SSO are used to assume the role by the role_arn setting in this profile(first).

[second]
sso_account_id = 012345678901
sso_region = us-east-1
sso_role_name = example-role-2
sso_start_url = https://d-abc123.awsapps.com/start

[first]
source_profile=second
role_arn=arn:aws:iam::123456789012:role/example-role

Changelog

3.25.0 (2021-08-05)

Bug Fixes

• md5-js: call fromUtf8 from correct environment (#2641) (affa927)
• middleware-apply-body-checksum: use lowercase content-md5 header (#2645) (e1f2dfc)
• packages: use HashConstructor instead of { new: Hash } (#2638) (6890a47)

Features

• clients: update clients as of 08/05/2021 (#2647) (4dc7ff7)