Better AWS credentials resolution plugin for serverless
The Serverless Better Credentials plugin replaces the existing AWS credential resolution mechanism in the Serverless Framework with an extended version that:
credential_process
mechanism for sourcing credentials from an external process.AWS_SHARED_CREDENTIALS_FILE
/ AWS_SDK_LOAD_CONFIG
).It is designed to be a drop-in replacement; respecting the current credentials resolution order and extensions already provided by the Serverless Framework.
npm install --save-dev serverless-better-credentials
# or
yarn add --dev serverless-better-credentials
Add the following to your serverless.yml:
plugins:
- serverless-better-credentials # as the first plugin
# - ... other plugins
The following options are supported:
custom:
betterCredentials:
# Use this flag to turn off the plugin entirely, which you may want for certain stages.
# Defaults to true.
enabled: true
AWS SSO profiles configured to work with the AWS CLI should "just work" when this plugin is enabled. This includes prompting and attempting to automatically open the SSO authorization page in your default browser when the credentials require refreshing.
Full details about how to configure AWS SSO can be found in the AWS CLI documentation.
Take note that if you are using SSO with the approach AWS document (a shared .aws/config
file) you'll also need to set the AWS_SDK_LOAD_CONFIG
enviornment value to something truthy (e.g. AWS_SDK_LOAD_CONFIG=1
), as described in the AWS SDK documentation.
Credentials are resolved in the same order the Serverless Framework currently uses. This order is:
--aws-profile
AWS_${STAGE}_PROFILE
AWS_${STAGE}_X
AWS_PROFILE
AWS_X
provider.profile
(unless --aws-profile is specified)provider.credentials
AWS_DEFAULT_PROFILE
|| default
Where:
[profile_name]
configuration:
credential_process
is specifiedsso_start_url
, etc. is specifiedIf you have an issue, suggestion, or want to contribute, please open an issue or create a pull request and I'll take a look.
There are a handful of common issues that people have trying to run this plugin. Mostly they surround either the confusing way that AWS resolves credentials, or the way that the Serverless Framework loads plugins.
It's always worth trying the following steps (but feel free to raise an issue if you're still having problems):
~/.aws/config
file, make sure you have AWS_SDK_LOAD_CONFIG=1
set in your environmentnpm install --save-dev serverless
in your project directory)If you are having trouble in a CI/CD environment (like GitHub actions), it is probably because you are using a plugin that has migrated to AWS-SDK v3. The easiest workaround is to add a step where you create the ~/.aws/credentials
file, for example:
mkdir -p ~/.aws
rm -rf ~/.aws/credentials
echo "[YOUR_PROFILE_NAME]" >> ~/.aws/credentials
echo "aws_access_key_id = ${AWS_ACCESS_KEY_ID}" >> ~/.aws/credentials
echo "aws_secret_access_key = ${AWS_SECRET_ACCESS_KEY}" >> ~/.aws/credentials
echo "aws_session_token = ${AWS_SESSION_TOKEN}" >> ~/.aws/credentials
echo "region = eu-west-1" >> ~/.aws/credentials
echo "output = json" >> ~/.aws/credentials