@aws-sdk/credential-providers
Advanced tools
A collection of credential providers, without requiring service clients like STS, Cognito
A collection of all credential providers.
An AwsCredentialIdentityProvider is any function that matches the signature:
() =>
Promise<{
/**
* AWS access key ID
*/
readonly accessKeyId: string;
/**
* AWS secret access key
*/
readonly secretAccessKey: string;
/**
* A security or session token to use with these credentials. Usually
* present for temporary credentials.
*/
readonly sessionToken?: string;
/**
* A `Date` when the identity or credential will no longer be accepted.
* You can set or override this on the client side to force a refresh
* call of the function supplying the credentials when 5 minutes remain.
*/
readonly expiration?: Date;
}>;
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.
A "parent/outer/upper/caller" (position), or "data" (purpose) client refers to a client being initialized explicitly by the SDK user.
An "inner" (position), or "credentials" (purpose) client refers to a client being initialized by the SDK in the course of retrieving credentials. Several AWS SDK credentials providers make use of inner clients such as Cognito, SSO, STS, and SSO-OIDC.
// Example: outer client and inner client
const s3 = new S3Client({
credentials: fromIni(),
});
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.
When a credential provider uses an SDK client to retrieve credentials, commonly STS, the control of the STS region follows this logic:
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:
credential-provider-config-region - given in code to the credential provider itself.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.context-client-region - the region resolved by an SDK client using the credential provider.env-region - AWS_REGION environment variable.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.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:
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",
});
client-regionenv-regionprofile-region (config file)fromCognitoIdentity()@aws-sdk/client-cognito-identityThe function fromCognitoIdentity() returns a credentials provider that retrieves credentials for
the provided identity ID. See GetCredentialsForIdentity API
for more information.
import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
region,
credentials: fromCognitoIdentity({
// Required. The unique identifier for the identity against which credentials
// will be issued.
identityId: "us-east-1:128d0a74-c82f-4553-916d-90053example",
// Optional. The ARN of the role to be assumed when multiple roles were received in the token
// from the identity provider.
customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity",
// Optional. A set of name-value pairs that map provider names to provider tokens.
// Required when using identities associated with external identity providers such as Facebook.
logins: {
"graph.facebook.com": "FBTOKEN",
"www.amazon.com": "AMAZONTOKEN",
"accounts.google.com": "GOOGLETOKEN",
"api.twitter.com": "TWITTERTOKEN'",
"www.digits.com": "DIGITSTOKEN",
},
// Optional overrides. This is passed to an inner Cognito client
// instantiated to resolve the credentials. Region and profile
// are inherited from the upper client if present unless overridden.
clientConfig: {},
}),
});
fromCognitoIdentityPool()@aws-sdk/client-cognito-identityThe function fromCognitoIdentityPool() returns AwsCredentialIdentityProvider that calls GetId API
to obtain an identityId, then generates temporary AWS credentials with
GetCredentialsForIdentity API, see
fromCognitoIdentity().
Results from GetId are cached internally, but results from GetCredentialsForIdentity are not.
import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
region,
credentials: fromCognitoIdentityPool({
// Required. The unique identifier for the identity pool from which an identity should be
// retrieved or generated.
identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
// Optional. A standard AWS account ID (9+ digits)
accountId: "123456789",
// Optional. A cache in which to store resolved Cognito IdentityIds.
cache: custom_storage,
// Optional. A unique identifier for the user used to cache Cognito IdentityIds on a per-user
// basis.
userIdentifier: "user_0",
// Optional. The ARN of the role to be assumed when multiple roles were received in the token
// from the identity provider.
customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity",
// Optional. A set of name-value pairs that map provider names to provider tokens.
// Required when using identities associated with external identity providers such as Facebook.
logins: {
"graph.facebook.com": "FBTOKEN",
"www.amazon.com": "AMAZONTOKEN",
"accounts.google.com": "GOOGLETOKEN",
"api.twitter.com": "TWITTERTOKEN",
"www.digits.com": "DIGITSTOKEN",
},
// Optional overrides. This is passed to an inner Cognito client
// instantiated to resolve the credentials. Region and profile
// are inherited from the upper client if present unless overridden.
clientConfig: {},
}),
});
fromTemporaryCredentials()@aws-sdk/client-stsThe function fromTemporaryCredentials returns AwsCredentialIdentityProvider that retrieves temporary
credentials from STS AssumeRole API.
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
region,
credentials: fromTemporaryCredentials({
// Optional. The master credentials used to get and refresh temporary credentials from AWS STS.
// If skipped, it uses the default credential resolved by internal STS client.
masterCredentials: fromTemporaryCredentials({
params: { RoleArn: "arn:aws:iam::1234567890:role/RoleA" },
}),
// Required. Options passed to STS AssumeRole operation.
params: {
// Required. ARN of role to assume.
RoleArn: "arn:aws:iam::1234567890:role/RoleB",
// Optional. An identifier for the assumed role session. If skipped, it generates a random
// session name with prefix of 'aws-sdk-js-'.
RoleSessionName: "aws-sdk-js-123",
// Optional. The duration, in seconds, of the role session.
DurationSeconds: 3600,
// ... For more options see https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html
},
// Optional. A function that returns a promise fulfilled with an MFA token code for the provided
// MFA Serial code. Required if `params` has `SerialNumber` config.
mfaCodeProvider: async (mfaSerial) => {
return "token";
},
// Optional overrides. This is passed to an inner STS client instantiated to
// resolve the credentials. Region and profile
// are inherited from the upper client if present unless overridden.
clientConfig: {},
}),
});
fromWebToken()@aws-sdk/client-stsThe function fromWebToken returns an AwsCredentialIdentityProvider that gets credentials calling
STS AssumeRoleWithWebIdentity API
import { fromWebToken } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
region,
credentials: fromWebToken({
// Required. ARN of the role that the caller is assuming.
roleArn: "arn:aws:iam::1234567890:role/RoleA",
// Required. The OAuth 2.0 access token or OpenID Connect ID token that is
// provided by the identity provider.
webIdentityToken: await openIdProvider(),
// Optional. A function that assumes a role with web identity and returns
// a promise fulfilled with credentials for the assumed role.
roleAssumerWithWebIdentity,
// Optional. An identifier for the assumed role session.
roleSessionName: "session_123",
// Optional. The fully qualified host component of the domain name of the
// identity provider.
providerId: "graph.facebook.com",
// Optional. ARNs of the IAM managed policies that you want to use as
// managed session.
policyArns: [{ arn: "arn:aws:iam::1234567890:policy/SomePolicy" }],
// Optional. An IAM policy in JSON format that you want to use as an
// inline session policy.
policy: "JSON_STRING",
// Optional. The duration, in seconds, of the role session. Default 3600.
durationSeconds: 7200,
// Optional overrides. This is passed to an inner STS client
// instantiated to resolve the credentials. Region and profile
// are inherited from the upper client if present unless overridden.
clientConfig: {},
}),
});
You can directly configure individual identity providers to access AWS resources using web identity federation. AWS currently supports authenticating users using web identity federation through several identity providers:
You must first register your application with the providers that your application supports. Next, create an IAM role and set up permissions for it. The IAM role you create is then used to grant the permissions you configured for it through the respective identity provider. For example, you can set up a role that allows users who logged in through Facebook to have read access to a specific Amazon S3 bucket you control.
After you have both an IAM role with configured privileges and an application registered with your chosen identity providers, you can set up the SDK to get credentials for the IAM role using helper code, as follows:
The value in the ProviderId parameter depends on the specified identity provider. The value in the WebIdentityToken parameter is the access token retrieved from a successful login with the identity provider. For more information on how to configure and retrieve access tokens for each identity provider, see the documentation for the identity provider.
fromContainerMetadata() and fromInstanceMetadata()fromContainerMetadata and fromInstanceMetadata will create AwsCredentialIdentityProvider functions that
read from the ECS container metadata service and the EC2 instance metadata service, respectively.
import { fromInstanceMetadata } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
credentials: fromInstanceMetadata({
// Optional. The connection timeout (in milliseconds) to apply to any remote requests.
// If not specified, a default value of `1000` (one second) is used.
timeout: 1000,
// Optional. The maximum number of times any HTTP connections should be retried. If not
// specified, a default value of `0` will be used.
maxRetries: 0,
}),
});
import { fromContainerMetadata } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
credentials: fromContainerMetadata({
// Optional. The connection timeout (in milliseconds) to apply to any remote requests.
// If not specified, a default value of `1000` (one second) is used.
timeout: 1000,
// Optional. The maximum number of times any HTTP connections should be retried. If not
// specified, a default value of `0` will be used.
maxRetries: 0,
}),
});
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 for more information on using IAM roles with Amazon
ECS.
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 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 for more information.
fromHttp()This creates a provider function that makes a GET request to
any provided HTTPS URL. A limited set of HTTP destinations are also accepted.
This is a general form of the fromContainerMetadata function.
The server is expected to respond with the following format in JSON:
type HttpProviderResponse = {
AccessKeyId: string;
SecretAccessKey: string;
Token: string;
AccountId?: string;
Expiration: string; // rfc3339
};
The acceptable non-HTTPS destinations are described in the validation error if encountered:
URL not accepted. It must either be HTTPS or match one of the following:
- loopback CIDR 127.0.0.0/8 or [::1/128]
- ECS container host 169.254.170.2
- EKS container host 169.254.170.23 or [fd00:ec2::23]
Node.js:
import { fromHttp } from "@aws-sdk/credential-providers";
const client = new FooClient({
credentials: fromHttp({
/**
* If this value is provided, it will be used as-is.
*/
awsContainerCredentialsFullUri: "...",
/**
* If this value is provided instead of the full URI, it
* will be appended to the default link local host of 169.254.170.2.
*/
awsContainerCredentialsRelativeUri: "...",
/**
* Will be read on each credentials request to
* add an Authorization request header value.
*/
awsContainerAuthorizationTokenFile: "...",
/**
* An alternative to awsContainerAuthorizationTokenFile,
* this is the token value itself.
*/
awsContainerAuthorizationToken: "...",
}),
});
If not provided in the JavaScript code, the following process envrionment variables will be read:
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
AWS_CONTAINER_CREDENTIALS_FULL_URI
AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE
AWS_CONTAINER_AUTHORIZATION_TOKEN
Browsers:
import { fromHttp } from "@aws-sdk/credential-providers";
const client = new FooClient({
credentials: fromHttp({
/**
* BROWSER ONLY.
*
* In browsers, a relative URI is not allowed, and a full URI must be provided.
* HTTPS is required.
*
* This value is required for the browser environment.
*/
credentialsFullUri: "...",
/**
* BROWSER ONLY.
*
* Providing this value will set an "Authorization" request
* header value on the GET request.
*/
authorizationToken: "...",
}),
});
fromIni()@aws-sdk/client-sso or @aws-sdk/client-sts depending
on how the file is configured.fromIni creates an AwsCredentialIdentityProvider function that reads 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.
import { fromIni } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
// As of v3.714.0, an easy way to select a profile is to set it on the client.
// This will read both client configuration and credentials instructions
// from that profile. The order of priority is:
// 1. this field (only applies to this client).
// 2. AWS_PROFILE environment variable (affects all clients).
// 3. the default profile.
profile: "my-profile",
// Please note that the data client's region
// will not be used by STS requests originating from the `fromIni`
// provider if the profile(s) used have their own configured regions.
// If the profile(s) have no regions set, then the data client's
// region will be the fallback for the inner STS client.
// For SSO via `fromIni`, the `sso_region` value will be used, since it is required.
region: "us-west-2",
credentials: fromIni({
// 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.
// Use this instead of the client profile if you need a separate profile
// for credentials.
profile: "my-profile",
// Optional. 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`.
filepath: "~/.aws/credentials",
// Optional. 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`.
configFilepath: "~/.aws/config",
// Optional. 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.
mfaCodeProvider: async (mfaSerial) => {
return "token";
},
// Optional overrides. This is passed to an inner STS or SSO client
// instantiated to resolve the credentials. Region and profile
// are inherited from the upper client if present unless overridden, so
// it should not be necessary to set those.
//
// Warning: setting a region here overrides the region set in the config file
// for the selected profile.
clientConfig: {},
}),
});
~/.aws/credentials[default]
aws_access_key_id=foo
aws_secret_access_key=bar
[dev]
aws_access_key_id=foo2
aws_secret_access_key=bar2
~/.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
[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
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 below:
[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
[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
See fromSSO() for more information
fromEnv()import { fromEnv } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
credentials: fromEnv(),
});
fromEnv returns an AwsCredentialIdentityProvider function, that reads credentials from the following
environment variables:
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 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.
fromProcess()import { fromProcess } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
// Optional, available on clients as of v3.714.0.
profile: "my-profile",
credentials: fromProcess({
// 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.
// Use this instead of the client profile if you need a separate profile
// for credentials.
profile: "my-profile",
// Optional. 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`.
filepath: "~/.aws/credentials",
// Optional. 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`.
configFilepath: "~/.aws/config",
}),
});
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
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.
~/.aws/credentials[default]
credential_process = /usr/local/bin/awscreds
[dev]
credential_process = /usr/local/bin/awscreds dev
~/.aws/config[default]
credential_process = /usr/local/bin/awscreds
[profile dev]
credential_process = /usr/local/bin/awscreds dev
fromTokenFile()@aws-sdk/client-stsThe function fromTokenFile returns AwsCredentialIdentityProvider that reads credentials as follows:
webIdentityTokenFile or environment variable AWS_WEB_IDENTITY_TOKEN_FILE.roleArn or environment
variable AWS_ROLE_ARN.roleSessionName or environment variable AWS_ROLE_SESSION_NAME. If session name is not defined,
it comes up with a role session name.roleAssumerWithWebIdentity option to get credentials.| Configuration Key | Environment Variable | Required | Description |
|---|---|---|---|
| webIdentityTokenFile | AWS_WEB_IDENTITY_TOKEN_FILE | true | File location of where the OIDC token is stored |
| roleArn | AWS_ROLE_ARN | true | The IAM role wanting to be assumed |
| roleSessionName | AWS_ROLE_SESSION_NAME | false | The IAM session name used to distinguish sessions |
import { fromTokenFile } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
region: "us-west-2",
credentials: fromTokenFile({
// 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: {},
}),
});
fromSSO()@aws-sdk/client-sso & @aws-sdk/client-sso-oidcThis credential provider ONLY supports profiles using the SSO credential. If you have a profile that assumes a role which derived from the SSO credential, you should use the
fromIni(), or@aws-sdk/credential-provider-nodepackage.
fromSSO, that creates AwsCredentialIdentityProvider functions that read from the resolved access token
from local disk then requests temporary AWS credentials. For guidance on the AWS Single Sign-On
service, please refer to AWS's Single Sign-On documentation.
You can create the AwsCredentialIdentityProvider functions using the inline SSO parameters(ssoStartUrl,
ssoAccountId, ssoRegion, ssoRoleName) or load them from
AWS SDKs and Tools shared configuration and credentials files.
Profiles in the credentials file are given precedence over profiles in the config file.
This credential provider is intended for use with the AWS SDK for Node.js.
You may customize how credentials are resolved by providing an options hash to the fromSSO factory
function. You can either load the SSO config from shared INI credential files, or specify the
ssoStartUrl, ssoAccountId, ssoRegion, and ssoRoleName directly from the code.
import { fromSSO } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
// Optional, available on clients as of v3.714.0.
profile: "my-sso-profile",
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.
// Use this instead of the client profile if you need a separate profile
// for credentials.
profile: "my-sso-profile",
// Optional. 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`.
filepath: "~/.aws/credentials",
// Optional. 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`.
configFilepath: "~/.aws/config",
// Optional. The URL to the AWS SSO service. Required if any of the `sso*` options(except for
// `ssoClient`) is provided.
ssoStartUrl: "https://d-abc123.awsapps.com/start",
// Optional. The ID of the AWS account to use for temporary credentials. Required if any of the
// `sso*` options(except for `ssoClient`) is provided.
ssoAccountId: "1234567890",
// Optional. The AWS region to use for temporary credentials. Required if any of the `sso*`
// options(except for `ssoClient`) is provided.
ssoRegion: "us-east-1",
// Optional. The name of the AWS role to assume. Required if any of the `sso*` options(except
// for `ssoClient`) is provided.
ssoRoleName: "SampleRole",
// Optional. Overwrite the configuration used construct the SSO service client. If not
// specified, a default SSO client will be created with the region specified in the profile
// `sso_region` entry.
clientConfig: { region },
}),
});
This credential provider relies on the AWS CLI to log into an AWS SSO session. Here's a brief walk-through:
$ aws configure sso
...
...
CLI profile name [123456789011_ReadOnly]: my-sso-profile<ENTER>
//...
const client = new FooClient({ credentials: fromSSO({ profile: "my-sso-profile" }) });
Alternatively, the SSO credential provider is supported in shared INI credentials provider
//...
const client = new FooClient({ credentials: fromIni({ profile: "my-sso-profile" }) });
$ aws sso logout
Successfully signed out of all SSO profiles.
This credential provider is only applicable if the profile specified in shared configuration and credentials files contain ALL of the following entries.
~/.aws/credentials[sample-profile]
sso_account_id = 012345678901
sso_region = us-east-1
sso_role_name = SampleRole
sso_start_url = https://d-abc123.awsapps.com/start
~/.aws/config[profile sample-profile]
sso_account_id = 012345678901
sso_region = us-east-1
sso_role_name = SampleRole
sso_start_url = https://d-abc123.awsapps.com/start
fromLoginCredentials()@aws-sdk/client-signinfromLoginCredentials creates an AwsCredentialIdentityProvider function that reads from cached login credentials stored on disk after authenticating with the AWS CLI using the aws login command. The provider automatically refreshes when the credentials are about to expire.
This provider is not typically used in an explicit fashion and is designed to simplify credential usage by allowing SDK clients to work seamlessly after running aws login with AWS CLI, without requiring any additional configuration.
import { fromLoginCredentials } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
// Optional, available on clients as of v3.714.0.
profile: "my-profile",
credentials: fromLoginCredentials({
// Optional. Defaults to the client's profile if that is set.
// Optional. Should match the profile name used with 'aws login --profile <name>'
// to ensure credentials are found in the cache. Uses 'default' if no
// --profile was specified during aws login or if this option is omitted.
profile: "my-profile",
// Optional. Overwrite the configuration used to construct the signin service client.
// If not specified, a default signin client will be created with the region specified in the profile.
// Warning: setting a region here overrides the region set in the config file
// for the selected profile.
clientConfig: { region },
}),
});
This credential provider relies on the AWS CLI to authenticate and cache login credentials. Here's how to set it up:
aws login command to authenticate using your existing AWS Management Console credentials:$ aws login
--profile option:$ aws login --profile my-dev-profile
No AWS region has been configured. The AWS region is the geographic location of
your AWS resources.
If you've used AWS before and already have resources in your account, tell us
which region they were created in. If you haven't created resources in your account
before, you can pick the region closest to you:
https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html.
You are able to change the region in the CLI at any time with the command
`aws configure set region NEW_REGION`.
AWS Region [us-east-1]:
Attempting to open the login page for `us-east-1` in your default browser.
If the browser does not open, use the following URL to complete your login:
https://signin.us-east-1.amazonaws.com/authorize?<abbreviated>
--no-browser option:$ aws login --no-browser
This will provide a URL for you to open on a browser-enabled device and prompt for an authorization code.
aws logout command:$ aws logout
$ aws logout --profile my-dev-profile
The temporary cached credentials, as well as the metadata required to refresh them are stored by default in ~/.aws/login/cache on Linux and macOS, or %USERPROFILE%\.aws\login\cache on Windows.
You can override this location by setting the AWS_LOGIN_CACHE_DIRECTORY environment variable.
After running aws login, the configuration file will contain a login_session entry:
~/.aws/config[default]
login_session = arn:aws:iam::0123456789012:user/username
region = us-east-1
fromNodeProviderChain()@aws-sdk/client-sts, @aws-sdk/client-sso, etc. depending on
which link in the chain finally resolves credentials.The credential provider used as default in the Node.js clients, but with default role assumers so you don't need to import them from STS client and supply them manually. You normally don't need to use this explicitly in the client constructor. It is useful for utility functions requiring credentials like S3 presigner, or RDS signer.
This credential provider will attempt to find credentials from the following sources (listed in order of precedence):
process.envThis credential provider will invoke one provider at a time and only
continue to the next if no credentials have been located. For example, if
the process finds values defined via the AWS_ACCESS_KEY_ID and
AWS_SECRET_ACCESS_KEY environment variables, the files at
~/.aws/credentials and ~/.aws/config will not be read, nor will any
messages be sent to the Instance Metadata Service
import { fromNodeProviderChain } from "@aws-sdk/credential-providers"; // ES6 import
const credentialProvider = fromNodeProviderChain({
// This provider accepts any input of fromEnv(), fromSSO(), fromTokenFile(),
// fromIni(), fromProcess(), fromInstanceMetadata(), fromContainerMetadata()
// that exist in the default credential chain.
// Optional client overrides. This is passed to an inner credentials client
// that may be STS, SSO, or other instantiated to resolve the credentials.
// Region and profile are inherited from the upper client if present
// unless overridden, so it should not be necessary to set those.
//
// Warning: setting a region here may override the region set in
// the config file for the selected profile if profile-based
// credentials are used.
clientConfig: {},
});
createCredentialChain()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>, 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.
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.
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.
import { fromEnv, fromIni, createCredentialChain } from "@aws-sdk/credential-providers";
import { S3 } from "@aws-sdk/client-s3";
// You can mix existing AWS SDK credential providers
// and custom async functions returning credential objects.
new S3({
credentials: createCredentialChain(
fromEnv(),
async () => {
// credentials customized by your code...
return credentials;
},
fromIni()
),
});
// Set a max duration on the credentials (client side only).
// A set expiration will cause the credentials function to be called again
// when the time left is less than 5 minutes.
new S3({
// This setting indicates expiry after 15 minutes (in milliseconds) with `15 * 60_000`.
// Due to the 5 minute expiry window, the function will be called approximately every
// 10 minutes under continuous usage of this client.
credentials: createCredentialChain(fromEnv(), fromIni()).expireAfter(15 * 60_000),
});
// Apply shared init properties.
const init = { logger: console };
new S3({
credentials: createCredentialChain(fromEnv(init), fromIni(init)),
});
The original AWS SDK for JavaScript (v2) includes credential management as part of its core functionality. It automatically handles credential provision from various sources similar to @aws-sdk/credential-providers but is less modular.
This package provides a way to load AWS credentials from environment variables or files. It is not as comprehensive or up-to-date as @aws-sdk/credential-providers and lacks support for newer AWS credential sources.
A utility package for managing AWS profiles and credentials. While it provides some similar functionality, it is more focused on profile management and does not offer the same level of integration with the AWS SDK.
FAQs
A collection of credential providers, without requiring service clients like STS, Cognito
The npm package @aws-sdk/credential-providers receives a total of 6,038,931 weekly downloads. As such, @aws-sdk/credential-providers popularity was classified as popular.
We found that @aws-sdk/credential-providers demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security Fundamentals
A pair of typosquatted Go packages posing as Google’s UUID library quietly turn helper functions into encrypted exfiltration channels to a paste site, putting developer and CI data at risk.
Security News
November CVE publications fell 25% YoY even as 2025 totals rose, showing how a few major CNAs can swing “global” counts and skew perceived risk.
Security News
React disclosed a CVSS 10.0 RCE in React Server Components and is advising users to upgrade affected packages and frameworks to patched versions now.