| name | service-account-credential-rotation |
| description | Use when designing credential rotation for integration users, connected apps, named credentials, and OAuth client secrets in Salesforce. Covers rotation cadence, zero-downtime handover, secret storage, and detection of stale credentials. Triggers: 'rotate integration user password', 'connected app secret rotation', 'named credential rotation', 'stale service account', 'zero downtime secret rotation'. NOT for end-user password policies. |
| category | security |
| salesforce-version | Spring '25+ |
| well-architected-pillars | ["Security","Reliability","Operational Excellence"] |
| triggers | ["how often to rotate integration user password","rotate connected app client secret without downtime","rotate named credential oauth token","detect stale service account","salesforce credential rotation runbook"] |
| tags | ["security","credentials","rotation","service-account","named-credentials"] |
| inputs | ["inventory of service accounts and their consumers","current rotation cadence and secret storage locations","downtime tolerance per integration"] |
| outputs | ["rotation cadence policy","zero-downtime rotation runbook","stale-credential detection plan"] |
| dependencies | [] |
| version | 1.0.0 |
| author | Pranav Nagrecha |
| updated | 2026-04-23T00:00:00.000Z |
Service Account Credential Rotation
Service account credentials are the forgotten middle layer of Salesforce security. Employees rotate passwords under MFA policy, connected apps rotate on explicit action, but "the integration user" often gets a password on day one of an integration and keeps it until a compliance audit forces a change years later. Similarly, connected app client secrets, JWT signing certs, and named credential OAuth tokens all have their own rotation story that no single team owns.
A workable rotation program has four parts: an inventory, a cadence, a zero-downtime pattern per credential type, and a stale-credential detector. Without the inventory, the other three are guesses.
Salesforce offers primitives for each credential type: integration user passwords (standard user policy), connected app client secrets (rotate via setup), JWT (replace cert), named credentials (refresh via setup or via a schedule). The patterns differ because the failure mode of a mid-rotation failure differs.
Before Starting
- Inventory service accounts, connected apps, JWT certs, and named credentials.
- Identify consumer integrations for each — who breaks if this credential is rotated incorrectly?
- Confirm secret storage (vault, secret manager, SIEM) for each consumer.
- Confirm downtime tolerance per integration.
Core Concepts
Credential Types And Their Rotation Mechanics
| Credential | Rotation Mechanic | Zero-Downtime? |
|---|
| Integration user password | Setup > User > Reset | No — simultaneous cutover |
| Connected App client secret | Setup > Connected Apps > rotate | Yes — previous+current grace window supported |
| JWT signing certificate | Replace cert on connected app | Yes — dual-cert grace window |
| Named credential OAuth token | Re-auth flow or manual refresh | Yes — token refresh handles it |
| API user session ID | Re-login | Yes — sessions auto-refresh |
Zero-Downtime Patterns
- Dual-credential grace window — both old and new valid during a window; consumers roll forward.
- Atomic cutover with coordination — used when grace windows are unavailable; requires a downtime slot.
- Auto-refresh — OAuth handles token rotation automatically; only the refresh-token-grant path needs care.
Rotation Cadence
