Tenant Secret
A Tenant Secret in Salesforce Shield Platform Encryption is an org-specific cryptographic secret that the customer controls, used together with the Salesforce-managed master secret to derive the data encryption keys that protect sensitive fields, files, and search index entries in the org.
Definition
A Tenant Secret in Salesforce Shield Platform Encryption is an org-specific cryptographic secret that the customer controls, used together with the Salesforce-managed master secret to derive the data encryption keys that protect sensitive fields, files, and search index entries in the org. The two-secret design (Salesforce master plus customer Tenant Secret) means neither side can decrypt the org data alone; the encryption keys exist only at runtime when both secrets combine. Customers rotate the Tenant Secret on a schedule they control, which forces key rotation across the org without re-encrypting data in place.
Tenant Secrets are the centerpiece of the customer-managed encryption story for Salesforce Shield. The platform generates the initial Tenant Secret automatically when Shield Encryption is enabled; customers can rotate to a new Tenant Secret through Setup, Platform Encryption, Key Management. Each Tenant Secret has a status (Active, Archived, Destroyed) and a use case (Data, Search Index, Analytics, etc.). Archived secrets can still decrypt data they previously encrypted; Destroyed secrets cannot. Mature security operations rotate Tenant Secrets quarterly and audit the rotation history annually.
Tenant Secrets in Shield Encryption: lifecycle, rotation, and BYOK
Tenant Secret in the broader Shield Encryption model
Shield Platform Encryption protects sensitive Salesforce data at rest with customer-managed encryption keys. The model uses three layers of secrets: the Salesforce-managed master secret (held by Salesforce in their key management infrastructure), the customer-controlled Tenant Secret (held in the customer org, viewable only by users with the Manage Encryption Keys permission), and the runtime-derived data encryption keys (computed by combining the master secret and Tenant Secret at runtime, never persisted). The runtime derivation means that compromising either secret alone does not yield the data encryption keys; an attacker needs both. This architecture lets Salesforce host the customer data without being able to decrypt it on its own, which is the security promise Shield exists to make.
Tenant Secret lifecycle: Active, Archived, Destroyed
Each Tenant Secret moves through a defined lifecycle. Active is the current secret used to derive encryption keys for new writes; only one secret per use case is Active at a time. Archived is the state after rotation; the secret can still decrypt records that were encrypted while it was Active, but new writes use the new Active secret. Destroyed is the final state; once destroyed, the secret cannot decrypt anything. Destroying a Tenant Secret is irreversible and destroys access to every record encrypted with it; this is a last-resort capability for data deletion that goes beyond simple record delete (it makes the data cryptographically unrecoverable even from backups). Use Destroy only with explicit business and legal sign-off.
Rotation and the operational rhythm
Tenant Secret rotation is the standard way to refresh the encryption keys protecting the org data. From Setup, Platform Encryption, Key Management, a user with the Manage Encryption Keys permission clicks Generate Tenant Secret. The platform creates a new secret and marks it Active; the prior secret transitions to Archived. New writes use the new secret to derive keys; old writes can still be decrypted because the Archived secret remains valid. Rotation does not re-encrypt existing data in place; it just changes which secret is used for future writes. For full re-encryption (so all data uses the new secret), the customer requests a Background Encryption Service through Salesforce Customer Support, which schedules an org-wide re-encryption job. Mature security operations rotate quarterly and run BES re-encryption annually.
Per-use-case Tenant Secrets and key isolation
Shield Encryption supports multiple Tenant Secrets in the same org, segregated by use case. Each Encrypted Field type, Encrypted File type, Encrypted Search Index, and Einstein Analytics dataset can use its own Tenant Secret. This isolation matters for compliance regimes that require separate key management for separate data classifications. For example, an org might keep one Tenant Secret for general PII (rotated quarterly), one for financial transaction data (rotated monthly), and one for clinical research data (rotated annually with explicit chain-of-custody documentation). The platform stores each Tenant Secret with its Use Case attribute and applies the right secret to each encryption operation based on the data classification. Mature security designs use the multi-secret model deliberately.
Bring Your Own Key (BYOK) and the customer-supplied secret pattern
Beyond the platform-generated Tenant Secret, Shield Encryption supports Bring Your Own Key (BYOK), where the customer generates the Tenant Secret externally (in their own HSM or key management system) and uploads it to Salesforce. The BYOK model gives the customer additional control: the secret never originates on the Salesforce platform, and the customer can revoke it externally if needed. BYOK requires more operational discipline (the customer manages the external key storage, rotation, and audit) but provides the strongest compliance posture for regulated industries. Some customers also use Cache-Only Keys, where the encryption key lives only in customer-controlled infrastructure and Salesforce fetches it just-in-time for each operation; this is the highest-security pattern but adds significant operational complexity and latency.
Audit, backup, and the operational responsibilities
Tenant Secrets are high-value cryptographic material; treat them with appropriate operational discipline. Audit access to the Manage Encryption Keys permission quarterly; the permission grants the ability to view and rotate Tenant Secrets, so the user list should be small and explicit. Back up each Active Tenant Secret to an external secure storage (a vault, an HSM) so the org can be restored if the platform-stored secret is lost in a catastrophic event. Document the rotation history with explicit timestamps and the user who performed each rotation. For regulated industries, retain the audit log for the period the regulation requires (HIPAA: 6 years, SOX: 7 years). Never destroy a Tenant Secret without explicit business and legal sign-off; the destruction is irreversible and makes the affected data cryptographically unrecoverable.
Operating Tenant Secrets in Shield Platform Encryption
Operating Tenant Secrets is a security discipline more than a configuration task. The four-step routine covers: enable Shield Platform Encryption with the right Use Cases, configure the initial Tenant Secrets, set up the rotation schedule, and operationalize backup and audit. Each piece is a security control; together they form the customer-managed key story that compliance teams expect. Skip the audit and backup steps at your peril; the operational cost is small but the compliance and recovery value is large.
- Enable Shield Platform Encryption with the right Use Cases
Shield Platform Encryption is a separate license; confirm the entitlement before starting. From Setup, search Platform Encryption, and enable the feature. Configure the Use Cases your org needs: Data (encrypted fields), Search Index (encrypted index), Analytics (encrypted datasets), Files, Chatter, etc. Each Use Case will have its own Tenant Secret. Activate only the Use Cases the org genuinely needs; activating extra ones increases the operational burden without security benefit. Document the activated Use Cases in the security runbook.
- Configure the initial Tenant Secrets
For each activated Use Case, generate the initial Tenant Secret. From Setup, Platform Encryption, Key Management, select the Use Case and click Generate Tenant Secret. The platform creates the secret and marks it Active. For BYOK customers, generate the secret in your external HSM and upload it through the same Key Management page. Confirm the secret status shows as Active. For multiple Use Cases, repeat the process for each. Document the initial generation with the user identity and timestamp.
- Set up the rotation schedule
Decide the rotation cadence per Use Case based on the regulatory and security requirements (quarterly for most general data, monthly for high-sensitivity, annually for stable archival data). Configure a calendar reminder or an automated workflow to trigger the rotation on schedule. On the rotation date, the security admin clicks Generate Tenant Secret again; the platform marks the new secret Active and the prior secret Archived. Document each rotation in the security audit log. For full re-encryption with the new secret, request the Background Encryption Service through Salesforce Customer Support.
- Operationalize backup and audit
Configure an external secure storage (HashiCorp Vault, AWS KMS, Azure Key Vault, on-premises HSM) for backing up Tenant Secrets. After each rotation, export the new Active secret to the backup store. Schedule a quarterly review of the Manage Encryption Keys permission assignment; remove any user no longer in the security role. Build a dashboard tracking Tenant Secret lifecycle events: generations, rotations, destructions. Retain the audit log for the regulatory retention period. Run an annual key management audit with the security and compliance teams to verify the operational discipline.
- Destroying a Tenant Secret is irreversible. The affected data becomes cryptographically unrecoverable, even from backups. Use only with explicit business and legal sign-off.
- Rotation does not re-encrypt existing data. New writes use the new Active secret; old data continues to use the Archived secret. For full re-encryption, request Background Encryption Service through Salesforce Customer Support.
- Shield Platform Encryption is a separate license. Confirm the entitlement before scoping any project that depends on customer-managed keys.
- The Manage Encryption Keys permission is a high-privilege grant. Audit the user list quarterly; over-broad grants expand the blast radius if a security user account is compromised.
- BYOK customers manage their own external key storage. The operational discipline (rotation, audit, backup) is heavier than the platform-generated Tenant Secret model but provides stronger compliance posture for regulated industries.
Trust & references
Straight from the source - Salesforce's reference material on Tenant Secret.
- Shield Platform Encryption OverviewSalesforce Help
- Tenant Secret ManagementSalesforce Help
- Bring Your Own KeySalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Tenant Secret?
Q2. Why dual secrets?
Q3. What should you do periodically?
Discussion
Loading discussion…