Applying Secret Rotation for Salesforce in Secret Manager

Background:

In Assured Allies, our mission is to help older adults age successfully via targeted educational materials and low-cost interventions, wellness support, and human support by our team of Allies or aging professionals.

For our AgeAssured product, which helps long-term care policyholders age in place and reduce claims, Salesforce is our main CRM.

Because security is a critical company priority, both to protect our members’ PHI and to comply with industry regulations, we had to implement secret rotation on Salesforce.

This article examines both regular secret rotations and the challenge of Salesforce's specific use case and proposes a solution that I hope will be helpful to developers in similar situations.

Introduction to Secret Rotation

By rotating the secret, the code automatically changes the credentials to the database.

In Salesforce, the security token must also be updated in addition to the password.

Motivation for the Secret Rotation:

• Security - Refreshing the secret of the DB will make it more secure.

• Stability - Prevent lambdas from failing when passwords expire automatically.

• Compliance - Consistently updating credentials as stipulated in compliance agreements.

• Time-saving - Reduce development team workload.

General Template by AWS

There is a basic flow and template recommended by AWS, which can be found here:

Secrets Manager rotation function templates - AWS Secrets Manager

Templates are available for various DBs like DynamoDB, MySQL, and PostgreSQL.

Secret Versions:

Each secret has three predefined versions:

• AWSPREVIOUS - The previous version of the secret with the last good credentials. It can be used to revert the current version in the secret manager to the previous version.

• AWSCURRENT - Currently working secret credentials are available in this stage.

• AWSPENDING - The pending version of the secret we wish to update on the secret manager. When the secret rotation is triggered, this version is created. The following will be our new secret credentials.

Rotation Steps:

There are four standard steps, that AWS uses to rotate the secret on the secret manager:

Create - Creates a new random password and stores it in the AWSPENDING secret.

Set - Sets the generated password from the previous step to the database.

Test - Verifies that the AWSPENDING secret can be used to log in to the DB.

Finish - AWSCURRENT is updated with AWSPENDING as well as the secret manager. After moving AWSCURRENT, Secrets Manager automatically moves AWSPREVIOUS to the version that AWSCURRENT was removed from.
Steps are events triggering the lambda and implementing the above.

Diagram 1

Salesforce is not one of the templates available on AWS.

Our web search revealed that we could easily set the password in SF using the simple_salesforce API.

aws_pending_dict = get_secret_dict(service_client, arn, AWS_PENDING)
sf_obj.set_password(client_id, pending_dict_password_only['password'])

Note: If the rotation fails, a manual update is required once it is completed on Salesforce because the password has already changed.

An e-mail with the security token is automatically sent whenever the password is updated.

Since this layer of protection complicates the rotation of the Salesforce secret, it's not included in the AWS examples.

For the task to be completed, we had to build a flow to extract the security token.

Security token flow:

Salesforce automatically sends the security token email when the API sets the new password.

The e-mail is sent into WorkMail so it can be scraped from there.

The WorkMail is configured to SES which sends it to the SNS topic and publishes it to an SQS queue.

It gets the message from the SQS queue and returns the security token if the sender and username match. If not, it removes it from the queue and places it on an SQS_DLQ queue instead.

Diagram 2

SF API secrets that have all four fields can be rotated by a lambda.

This is the basic flow. To have a separation between the environments, those services should be created separately for each environment.

Services

Amazon WorkMail:

In WorkMail, the organization specifies the domain of the e-mail address that will receive emails.

The e-mail address configured on Salesforce will be the user in each environment.

Amazon Simple Email Service (SES):

SNS receives the e-mail address from SES.

Whenever a new user is created on workmail, SES is automatically updated.

Amazon Simple Notification Service (SNS):

The SNS is configured to the SQS_.

Amazon Simple Queue Service (SQS):

The SQS subscribed to the SNS topic

The SQS configured to the SQS__DLQ.

Amazon SQS dead-letter queue (SQS_DLQ):

The SQS subscribed to the SNS topic SQS__DLQ

Security

The Salesforce secret rotation flow was designed with a strong, defense-in-depth security model. Key security controls included:

Environment Isolation
The entire architecture was deployed separately per environment, with isolated infrastructure for production, staging, and development. This guarantees that production secrets and resources cannot be accessed or influenced by non-production systems.

VPC Containment with Service-to-Service Encryption
All components, including the rotation Lambda function, were deployed inside a VPC, with private connectivity to AWS services through VPC interface endpoints. This ensured that no traffic ever traversed the public internet.
All communication between services — such as from SES to SNS, SNS to SQS, SQS to Lambda, and Lambda to Secrets Manager — was conducted over the AWS internal network using TLS, ensuring full service-to-service encryption in transit.

Dedicated KMS Keys and Encryption Isolation
Each AWS service involved in the pipeline (Secrets Manager, SQS, SNS) used its own customer-managed KMS key.
Combined with VPC isolation, this enforced end-to-end service-to-service encryption, where each service could only decrypt or encrypt data using its own key, and only if explicitly permitted through tightly scoped KMS policies.

IAM Least Privilege Enforcement
The Lambda function was assigned a narrowly scoped IAM role, with permissions limited to only the specific resources it required.

Sender Validation Logic
The Lambda code implemented strict sender validation, ensuring that only emails originating from Salesforce were processed.

Logging and Monitoring

The Lambda function was fully instrumented with CloudWatch logging, tracking every stage of the AWS Secrets Manager rotation lifecycle: createSecret, setSecret, testSecret, and finishSecret.

Each step was logged clearly with structured messages that captured progress, errors, and flow decisions — but never logged any sensitive information such as passwords or tokens. This ensured operational visibility without risking credential exposure.

In addition to CloudWatch logs, CloudTrail was enabled for all relevant services, including Secrets Manager, KMS, IAM, and Lambda. This provided a complete audit trail of every sensitive action.

CloudWatch metrics and alarms were also configured to alert on failures, timeouts, or message processing issues in the SQS queue. This proactive monitoring ensured timely detection of problems and supported continuous operational integrity.

Pros and cons:

Pros:

1. The secret can now be automatically updated without any involvement from the DEV team.
2. For every user who has the Username, Password, Domain, and Security Token requirements needed to use a Salesforce sign-in, this possibility exists. It works for API users as well as regular users.
3. As long as the configuration is right, it will work with any Salesforce environment.

Cons:

1. A lambda's success depends directly on the arrival of the Salesforce security token email. The lambda will fail if the e-mail does not arrive. It is also true for manual password updates.
2. A failure of the rotation will cost us the manual rotation that we worked so hard to replace.
3. For all of this to be developed, it costs some DEV time. The lambda can also be triggered from outside after the refreshment, but enabling this option will take more work since the password is automatically changed. In my opinion, this is more of an optional feature aimed at eliminating the other cases where passwords need to be changed manually.

Thank you for reading this article. I hope you found it helpful.

Anna Chaykovsky

Software Developer, Assured Allies.

Assured Allies is on a mission to help people make the most out of life by aging on their own terms. Since 2018, Assured Allies has been developing technologies and expertise in aging, working with long-term care industry leaders and insurance companies to better support successful aging.