The Serverless Better Credentials plugin replaces the existing AWS credential resolution mechanism in the Serverless Framework with an extended version that:

• Supports AWS Single Sign On natively.
• Supports the credential_process mechanism for sourcing credentials from an external process.
• Respects all of the configuration environmental variables that the javascript aws-sdk v2 supports (e.g. 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.

1. Install

npm install --save-dev serverless-better-credentials
# or
yarn add --dev serverless-better-credentials

2. Configure

Add the following to your serverless.yml:

plugins:
  - serverless-better-credentials # as the first plugin
  # - ... other plugins

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:

• from profile: cli flag --aws-profile
• from profile: env AWS_${STAGE}_PROFILE
• from env - AWS_${STAGE}_X
• from profile - AWS_PROFILE
• from env - AWS_X
• from profile - serverless.yml > provider.profile (unless --aws-profile is specified)
• from config - serverless.yml > provider.credentials
• from profile - AWS_DEFAULT_PROFILE || default

Where:

• profile credentials resolve against the matching [profile_name] configuration:
  • first directly as SharedIniFileCredentials (i.e. key id/secret or STS role)
  • then using ProcessCredentials, if an credential_process is specified
  • then using the built-in SSO Credentials if sso_start_url, etc. is specified
• env credentials resolve as EnvironmentCredentials (i.e. from the running process environment)
• config credentials resolve directly as Credentials (i.e. from an explicitly set key id and secret)

If 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):

• If you're using an ~/.aws/config file, make sure you have AWS_SDK_LOAD_CONFIG=1 set in your environment
• Make sure you're not using a global installation of serverless (e.g. run npm install --save-dev serverless in your project directory)