Handle AWS Secrets easily with Cypress

Managing secrets securely and efficiently is crucial for any application. This plugin integrates AWS Secrets Manager into your Cypress tests, ensuring that sensitive data like API keys, passwords, and tokens remain secure during testing. It allows for secure loading and updating of secrets directly from your tests.

Table of Contents

• Main Changes From V1
  • Library Import in setupNodeEvents
  • Storing AWS_SECRET_MANAGER_CONFIG
• Installation
• Prerequisites
• Configuration
  • Code in cypress.config.js
• Functions
  • getSecretFromAWS
  • updateSecret
• Environment variables
  • Define AWS_SECRET_MANAGER_CONFIG object
  • AWS Login Strategies
  • Log Mode (ENV_LOG_MODE)
• Pass your AWS configuration to cypress
• Running on CI
  • Overwriting variables
  • Importing Secrets from local file
• Results
• Best Practices for AWS Login
  • AWS SSO
  • AWS IAM
• THE JOB IS DONE

Upgrading to Version 2

This is version 2 of the library, which includes significant performance improvements and several changes. Please update your configuration according to the new instructions provided below to avoid any issues. See Main Changes for more details.

Installation

1$ npm install cypress-aws-secrets-manager --save-dev

or as a global module

1$ npm install -g cypress-aws-secrets-manager

Prerequisites

• AWS CLI Install/Update
• A user to SSO via AWS Identity and Access Management.

Configuration

Code in cypress.config.js

In your cypress.config.js file:

1// cypress.config.js
2module.exports = defineConfig({
3  e2e: {
4    async setupNodeEvents(on, config) {
5      const { getSecretFromAWS } = require('cypress-aws-secrets-manager')
6      config.env = await getSecretFromAWS(config.env, __dirname)
7      require('cypress-aws-secrets-manager/tasks')(on, config)
8      return config
9    }
10  }
11})

Functions

getSecretFromAWS

1getSecretFromAWS(config.env, __dirname)

The getSecretFromAWS function allows you to update your environment variables by adding secrets stored in AWS Secrets Manager. This function merges existing environment variables with new secrets from AWS Secrets Manager.

getSecretFromAWS Usage

1// cypress.config.js
2module.exports = defineConfig({
3  e2e: {
4    async setupNodeEvents(on, config) {
5      const { getSecretFromAWS } = require('cypress-aws-secrets-manager')
6      config.env = await getSecretFromAWS(config.env, __dirname)
7      return config
8    }
9  }
10})

updateSecret

1cy.task('updateSecret', secretValue)

The updateSecret task allows you to update secrets stored in AWS Secrets Manager. This function merges existing secrets with new values and updates the secret in AWS Secrets Manager.

Features

• Adding Secrets: Introduce a new key-value pair (e.g., here)
• Updating Secrets: Change the value of an existing key (e.g., here).

secretValue Must be an object containing the new secretString for the secretKey to update & to merge with the existing ones.

Returns: A promise that resolves with the AWS Secrets Manager response if the secret is updated successfully, or rejects with an error if the update fails.

updateSecret Usage

1// cypress.config.js
2module.exports = defineConfig({
3  e2e: {
4    async setupNodeEvents(on, config) {
5      require('cypress-aws-secrets-manager/tasks')(on, config)
6      return config
7    }
8  }
9})
10
11// inside a spec file (e.g. spec.cy.js)
12const secretValue = { secretKey: 'secretString' }
13cy.task('updateSecret', secretValue).then((result) => {
14  cy.log(JSON.stringify(result))
15})

Environment variables

Environment variables should be easily modifiable from the command line (see here), whereas the other configurations should not.

Parameter	Mandatory	Notes	Default
AWS_SSO_STRATEGY	TRUE	A string that defines the AWS login strategy (see here for details)	—
AWS_SECRET_MANAGER_CONFIG	TRUE	An object that contains the essential configuration parameters (see here for details)	—
AWS_SECRETS_LOCAL_DIR	FALSE	Directory path where secrets should be saved locally. If not specified, secrets will not be saved.	—
ENV_LOG_MODE	FALSE	When set to 'silent', restricts plugin log output to only key status messages (see Silent mode).	''

Define AWS_SECRET_MANAGER_CONFIG object

The main object required by this library is AWS_SECRET_MANAGER_CONFIG, which contains the following parameters:

1{
2  "AWS_SECRET_MANAGER_CONFIG": {
3    "secretName": "AWS_SECRET_NAME",
4    "profile": "AWS_PROFILE_NAME",
5    "region": "AWS_REGION",
6    "kmsKeyId": "AWS_SECRET_KMS_KEY",
7    "pathToCredentials": "PATH_TO_AWS_CREDENTIALS.JSON"
8  }
9}

Parameter	Required	Description	Default
secretName	✅ Yes	AWS secret name	—
region	✅ Yes	AWS Secrets Manager region	—
profile	❌ No	AWS SSO profile name	'default' profile
kmsKeyId	Required only when updating a secret from another AWS account	AWS KMS key ID used for secret encryption	—
pathToCredentials	❌ No	Path to credentials file (used with credentials to write them to a file)	Same folder as cypress.config.js

AWS Login Strategies

The next configurations are external to the AWS_SECRET_MANAGER_CONFIG because they can vary for the same project when executed locally and on CI. The variables within AWS_SECRET_MANAGER_CONFIG are more dependent on the execution environment.

• If profile is set, the plugin will use the profile name specified inside the AWS_SECRET_MANAGER_CONFIG (if not specified, the default profile will be used).

• AWS_SSO_STRATEGY: 'profile' | 'default' | 'credentials' | 'unset' | 'multi'

  • profile or default → AWS SSO
  • credentials or unset → AWS IAM (using environment variables or credentials file)
  • multi → Try all strategies in order, fail only after all attempts.

AWS_SSO_STRATEGY	AWS Auth Type
profile	AWS SSO
default	AWS SSO
credentials	AWS IAM
unset	AWS IAM
multi	Mixed

Credential File example

This credential file is used with the AWS IAM strategy. It is optional.

1// pathToCredentials.json
2{
3  "accessKeyId": "XXXXXX",
4  "secretAccessKey": "XXXXXX",
5  "sessionToken": "XXXXXX"
6}

Log Mode (ENV_LOG_MODE)

By default, the plugin emits detailed logs for each step (login attempts, secret extraction, etc.). If you want to restrict log verbosity, set the environment variable:

1npx cypress run -e ENV_LOG_MODE=silent

• silent: Only key status messages are logged, omitting detailed steps and AWS SDK messages.

See Silent mode in the Results section for examples.

Pass your AWS configuration to cypress

After defining your strategy and your AWS_SECRET_MANAGER_CONFIG, you can import this configuration into Cypress in two ways.

"Easy" way with cypress-env plugin

IMPORTANT: Import cypress-env before cypress-aws-secrets-manager

1// cypress.config.js
2module.exports = defineConfig({
3  e2e: {
4    async setupNodeEvents(on, config) {
5      require('cypress-env')(on, config)
6      const { getSecretFromAWS } = require('cypress-aws-secrets-manager')
7      config.env = await getSecretFromAWS(config.env, __dirname)
8      require('cypress-aws-secrets-manager/tasks')(on, config)
9      return config
10    }
11  }
12})

PRO: Zero code for environment injection CON: Requires cypress-env plugin

Your environment.json will look like:

1// environment.json
2{
3  "baseUrl": "https://www.google.com",
4  "env": {
5    "var1": "value1",
6    "var2": "value2",
7    "var3": "value3",
8    "AWS_SSO_STRATEGY": "strategy_type",
9    "AWS_SECRET_MANAGER_CONFIG": {
10      "secretName": "AWS_SECRET_NAME",
11      "profile": "AWS_PROFILE_NAME",
12      "region": "AWS_REGION",
13      "kmsKeyId": "AWS_SECRET_KMS_KEY",
14      "pathToCredentials": "PATH_TO_AWS_CREDENTIALS.JSON"
15    }
16  }
17}

"Complex" way inside cypress.config.js

PRO: No additional plugin needed CON: Requires a bit more code

1// cypress.config.js
2module.exports = defineConfig({
3  e2e: {
4    async setupNodeEvents(on, config) {
5      const { getSecretFromAWS } = require('cypress-aws-secrets-manager')
6      config.env = await getSecretFromAWS(config.env, __dirname)
7      return config
8    }
9  },
10  env: {
11    AWS_SSO_STRATEGY: 'strategy_type',
12    AWS_SECRET_MANAGER_CONFIG: {
13      secretName: 'AWS_SECRET_NAME',
14      profile: 'AWS_PROFILE_NAME',
15      region: 'AWS_REGION',
16      kmsKeyId: 'AWS_SECRET_KMS_KEY',
17      pathToCredentials: 'PATH_TO_AWS_CREDENTIALS.JSON'
18    }
19  }
20})

Running on CI

Overriding environment variables in CI or local setup

In certain cases, you may need to override specific environment variables like AWS_SSO_STRATEGY or AWS_SECRETS_LOCAL_DIR that are pre-configured in your cypress.config.env. This is particularly useful when running tests in different environments (e.g., local development vs CI) where different AWS configurations are required.

To override these variables when running Cypress, use the following command:

1npx cypress run -e AWS_SSO_STRATEGY=$NEW_AWS_SSO_STRATEGY,AWS_SECRETS_LOCAL_DIR=$CUSTOM_SECRETS_DIR

• $NEW_AWS_SSO_STRATEGY: The new value for the AWS SSO strategy that overrides the default strategy configured in your project.
• $CUSTOM_SECRETS_DIR: The directory where you want to store or retrieve AWS secrets locally for reuse across multiple test sessions.

This allows for flexible configuration across different environments, ensuring that secrets and authentication strategies are handled correctly depending on where the tests are executed (e.g., in a CI pipeline or on a developer's machine).

Importing Secrets from a Local File

I understand that allowing users to load secrets from a local file might seem counterintuitive. However, this approach becomes necessary especially when using a cloud provider like AWS, in scenarios involving assume-role chains that are limited to an hour in duration.

When conducting sequential tests, particularly with tools like Cypress that restart and reload environment variables for each new session, obtaining AWS secrets after the initial hour can be cumbersome. This can interrupt testing workflows, especially when secrets are needed across multiple sessions. To mitigate this issue, I’ve added the option for users to specify a AWS_SECRETS_LOCAL_DIR variable.

If AWS_SECRETS_LOCAL_DIR is specified and the temporary file doesn't exist, the plugin will retrieve the secrets during the first session and store them locally. These stored secrets will then be reused in subsequent sessions, eliminating the need to continuously fetch them from AWS after the role chain expires.Every secrets will be saved in a JSON file named by the secret name.

This solution simplifies running multiple test sequences without worrying about refreshing the role or secret access within the limited session time frame.

See here to understand how to use different behavior on CI.

1// environment.json
2{
3  "baseUrl": "https://www.google.com",
4  "env": {
5    "AWS_SSO_STRATEGY": "strategy_type",
6    "AWS_SECRETS_LOCAL_DIR": "aws_secrets_folder",
7    "AWS_SECRET_MANAGER_CONFIG": {
8      "secretName": "AWS_SECRET_NAME",
9      "profile": "AWS_PROFILE_NAME",
10      "region": "AWS_REGION",
11      "kmsKeyId": "AWS_SECRET_KMS_KEY",
12      "pathToCredentials": "PATH_TO_AWS_CREDENTIALS.JSON"
13    }
14  }
15}

Results

Correct configuration

1====================================================================================================
2
3Starting plugin: cypress-aws-secrets-manager
4
5AWS SSO strategy: profile
6
71st attempt: Trying to login into AWS with profile: "AWS_PROFILE_NAME"
8
9AWS SDK credentials are set up correctly!
10
11Extracting secret from: "AWS Secrets Manager"
12
13secret: "{
14    "username": "*****",
15    "password": "*****"
16}"
17
18√ Secret loaded correctly from: "AWS_SECRET_NAME"
19
20====================================================================================================

---

Silent mode (ENV_LOG_MODE: 'silent')

When you set ENV_LOG_MODE: 'silent', the plugin omits detailed steps and intermediate AWS SDK messages:

1====================================================================================================
2
3Starting plugin: cypress-aws-secrets-manager
4
5√ Secret loaded correctly from: "AWS_SECRET_NAME"
6
7====================================================================================================

---

Missing configuration

Description Cypress started without plugin configurations

1====================================================================================================
2
3Starting plugin: cypress-aws-secrets-manager
4√ Missing AWS_SECRET_MANAGER_CONFIG, continue without secrets!
5
6
7====================================================================================================

---

Wrong configuration

Description secretName & region are mandatory

1====================================================================================================
2
3Starting plugin: cypress-aws-secrets-manager
4
5"AWS_SECRET_MANAGER_CONFIG" object MUST contain these mandatory properties: secretName, region
6ConfigurationError!
7
8Passed: [
9 "profile": "AWS_PROFILE_NAME"
10]
11Missing: [
12 "secretName",
13 "region"
14]
15
16====================================================================================================

Wrong credentials

Description Your credentials are invalid

1====================================================================================================
2
3Starting plugin: cypress-aws-secrets-manager
4
5AWS SSO strategy: "multi"
6
71st attempt: Trying to login into AWS with profile: "AWS_PROFILE_NAME"
8
92nd attempt: Trying to login into AWS with profile: "default"
10
113rd attempt: Trying without specifying credentials
12
13Incorrect plugin configuration!
14ERROR: Could not load credentials from any providers
15
16====================================================================================================

---

Adding Secrets Example

Initial Secret on AWS:

1{
2  "dbUsername": "admin",
3  "apiKey": "someAPIKey"
4}

Cypress Test:

1// spec.cy.js
2describe('Adding Secrets', () => {
3  it('should add a new dbPassword', () => {
4    cy.task('updateSecret', { dbPassword: 'oldSecurePassword456!' })
5  })
6})

Resulting Secret:

1{
2  "dbUsername": "admin",
3  "dbPassword": "oldSecurePassword456!",
4  "apiKey": "someAPIKey"
5}

---

Updating Secrets Example

Current Secret on AWS:

1{
2  "dbUsername": "admin",
3  "dbPassword": "oldSecurePassword456!",
4  "apiKey": "someAPIKey"
5}

Cypress Test:

1// spec.cy.js
2describe('Updating Secrets', () => {
3  it('should update the dbPassword', () => {
4    cy.task('updateSecret', { dbPassword: 'newSecurePassword456!' })
5  })
6})

Resulting Secret:

1{
2  "dbUsername": "admin",
3  "dbPassword": "newSecurePassword456!",
4  "apiKey": "someAPIKey"
5}

Best Practices for AWS Login

When working with AWS, particularly in environments like development and testing, it's essential to ensure that you have authenticated access to your AWS account. Below are some best practices for managing AWS logins effectively, using either AWS SSO or Assume Role methods.

AWS SSO (Single Sign-On)

If your organization uses AWS SSO, you can utilize the following scripts to handle authentication seamlessly:

• aws_authenticate.sh This sets the needed environment variables and starts the aws_sso.sh script.

• aws_sso.sh This script checks your AWS SSO authentication status and logs you in if you're not already.

AWS IAM (Assume Role)

For users and applications that need to assume roles to access specific AWS resources, use these scripts:

• aws_authenticate.sh Sets the needed environment variables and starts the aws_assume_role.sh script.

• aws_assume_role.sh Verifies your role assumption and logs you in if you're not already.

Integrating with package.json

To streamline your workflow, add these scripts to your package.json:

1// package.json
2{
3  "scripts": {
4    "cy:open": "sh aws_authenticate $ENV \"npx cypress open\"",
5    "cy:run": "sh aws_authenticate $ENV \"npx cypress run\""
6  }
7}

Run with:

1npm run cy:open

THE JOB IS DONE!

Happy testing to everyone!

ALEC-JS

🙌 Donate to support my work & further development! 🙌