Secrets manager migration playbook: move platforms without copying old risk

Moving from one secrets manager to another is the moment an organisation handles every one of its secrets at once, and a migration done as a bulk copy carries every long-lived, over-shared and already-leaked secret into the new platform while leaving the old one quietly running. Platform migrations happen for consolidation after mergers, a move between clouds, a self-hosted cluster reaching end of support, or a change of operating model. This playbook covers moving from one secrets management platform to another: what actually has to move besides secret values, choosing between copying and re-issuing, translating policies and machine authentication, the privileged migration identity, cutover and rollback, and decommissioning the source so it cannot be used again. It is vendor-neutral and based on the OWASP Secrets Management Cheat Sheet and NIST guidance. Building and onboarding a new platform from scratch is covered in the Secrets manager rollout playbook; choosing one is covered in the Secrets Management Buyer's Guide.

Key takeaways

• Re-issue where you can, copy only where you must. Every secret that can be rotated should arrive in the new platform as a fresh value, so the migration also retires whatever leaked from the old one.
• Secrets are the easy part. Policies, machine authentication methods, dynamic secret backends, certificate authorities, metadata and audit history all need a plan, and translating policies is where access quietly widens.
• The migration identity is the most privileged NHI you will create this year. It can read everything in the source and write everything in the target; make it short-lived, tightly scoped and logged.
• Freeze, watch, then switch off. Put the source into read-only mode after cutover and alert on every read, so stragglers surface before you decommission.
• Decommissioning is a security task. Keep audit logs for their retention period, destroy backups and unseal material, and revoke the old platform's own credentials in every connected system.

What has to move

OWASP's cheat sheet (section 2.11) advises storing metadata with every secret precisely so that it can be moved later, and warns that without it vendor lock-in becomes more likely. In practice, a secrets platform holds much more than key and value pairs. Build the migration inventory by object type.

Copy or re-issue: choosing the transfer method

Most migrations mix three methods. The decision is per secret, based on whether you control the issuer and whether the consumer can tolerate a new value.

Our recommendation: aim for at least 80% of migrated secrets to be rotated or replaced with dynamic credentials, and record a dated rotation plan for every copied one. Copying everything is faster but means the old platform's exposure, including any secret already sitting in a repository or log, moves with you. The Internet Archive breach shows the cost of tokens left valid after the source code holding them was stolen: Zendesk API tokens found in that code were used in a second breach weeks later.

Rules for a secure copy

• Machine to machine only: the job reads from the source API and writes to the target API in memory. No export file, spreadsheet or laptop in between.
• If a file is unavoidable: encrypt it to a key held in the target environment, keep it on restricted storage for hours, not days, and log its destruction.
• Preserve attribution: tag each copied secret with "migrated, not rotated" and its source path, so later reports can find it.
• Verify by hash, not by eye: compare a keyed hash of source and target values in the job; never print values to logs or the console.

The migration identity

The job that reads the source and writes the target is a non-human identity with read access to everything you hold. It should be the most closely watched credential in the programme.

• Scope by wave: grant read on only the paths in the current wave in the source, and write on only the matching paths in the target.
• Time-bound: issue it for the migration window and revoke it at the end of each wave. Use workload identity or federation to authenticate the job rather than a static token.
• Run from a controlled place: a dedicated pipeline or job runner with no human interactive shell, not an engineer's workstation.
• Alert on its use outside the window: any read by the migration identity outside an approved run is an incident.
• Two people for the bulk run: require a second approver to start a wave that includes production or privileged paths (NIST SP 800-53 AC-5, separation of duties).

Translating policies and authentication

Different platforms express access in different ways: path-based rules, resource policies, role bindings, vault-level or project-level boundaries. A literal translation rarely exists, and the tempting shortcut is a broader rule that "makes it work".

1. Translate intent: for each source policy, write down which identity needs which action on which secrets, then express that in the target model. Start from least privilege (AC-6), not from the old rule text.
2. Keep the boundaries: OWASP advises separating production and development secrets; keep that separation as hard boundaries in the target (separate instances, accounts, vaults or projects), not just naming.
3. Replace static machine authentication: if the source relied on long-lived tokens or static identifier and secret pairs for applications, use the migration to move to workload identity or OIDC federation in the target.
4. Test with real identities: for each translated policy, prove that the intended identity can read its secrets and that a neighbouring identity cannot. Automate these as tests that run on every policy change.
5. Diff effective access: before cutover, compare who can read what in source and target. Any identity that gains access is a finding to explain.

The phased playbook

1. Phase 0, inventory and map: export the object inventory above, consumers per secret (from audit logs of the last 90 days), owners and rotation capability. Resolve ownerless secrets, and delete secrets with no reads in the period after owner confirmation.
2. Phase 1, target ready: build and harden the target, with audit logging on before the first secret (OWASP 2.6) and backup and restore tested (OWASP 2.9). Follow the rollout playbook for platform design.
3. Phase 2, pilot: migrate one low-risk application end to end, including a rotation into the target and a rehearsed rollback.
4. Phase 3, waves: migrate by consumer pattern (runtime API, sidecar or agent, file injection, pipeline), lowest risk first, production and privileged credentials last. For each application: create the target secret, switch the consumer, verify, rotate, then remove the source entry or mark it deprecated.
5. Phase 4, freeze the source: make the source read-only and alert on every successful read. Each read is a missed consumer to fix.
6. Phase 5, decommission: see the section below.

Per-application cutover and rollback

• Dual-read only as a bridge: letting an application fall back to the source if the target fails reduces risk during cutover, but set an end date, because a permanent fallback means the old platform never retires.
• Rotate after the switch, not before: once the consumer reads from the target, rotate the credential at the issuer and update the target only. A rollback after this point points the consumer back with the new value written to the source temporarily.
• Rollback trigger: define it in advance, for example authentication failures above the normal baseline for 15 minutes after cutover (our recommendation), and who decides.
• Disaster recovery sites: repoint standby environments in the same wave, or they will fail on the day you need them.

Decommissioning the source

• Archive audit logs: export the source's audit history to your log store for its full retention period (NIST SP 800-53 AU-11) before shutting anything down.
• Revoke the platform's own credentials: the old secrets manager held credentials in other systems, such as database root accounts for dynamic secrets, cloud roles, identity provider clients and KMS keys used for its seal. Revoke or delete each one, or it remains a usable identity.
• Revoke outstanding leases and tokens: let dynamic leases expire or revoke them, and revoke every token and authentication method the source issued.
• Destroy backups and recovery material: snapshots, backups, unseal or recovery shares and replicas all contain the full secret set. Sanitise storage following NIST SP 800-88 Rev. 2 and record it (MP-6).
• Remove network paths and DNS: so a forgotten script fails loudly rather than reaching a restored copy.
• Close with a scan: search code, pipelines and configuration for references to the old endpoint and for any secret values that were copied, not rotated. See the Secret Sprawl Measurement Guide.

Small versus large organisations

A small team with a few hundred secrets can often run a single wave over a few days: rotate everything that can be rotated, copy the rest with a scripted job, freeze the source for two weeks, then decommission. A large estate with thousands of consumers needs the wave model, a migration team with platform and application owners, translated policy tests in CI, and a longer freeze period, because rarely run jobs (month-end, annual renewals, disaster recovery tests) only show up over time. Our recommendation for large estates is a freeze of at least one full business cycle, typically 30 to 45 days.

Detection and measurement

OWASP section 2.6 lists the events a secrets platform should audit, including who requested secrets, approvals, usage, expiration and administrative actions; during a migration watch both platforms.

Common failure patterns

• Bulk export to a file: a plaintext export left in a bucket, ticket attachment or download folder becomes the largest single leak the organisation has ever had.
• Copy everything, rotate nothing: the platform changes, the exposure does not.
• Wildcard policies to hit the deadline: temporary broad rules that are never narrowed.
• Old platform never switched off: left running "for safety", unpatched and unwatched, still holding every secret.
• Seal and root credentials forgotten: the old platform's database roots, cloud roles and seal keys remain active after shutdown.
• Audit history lost: the source cluster is destroyed with its logs, so an investigation into an earlier access cannot be completed.

Framework mapping

Practitioner checklist

• Inventory every object type in the source, not only secret values, with owners and consumers.
• Decide per secret: rotate into the target, replace with dynamic credentials, or secure copy with a dated rotation plan.
• Ban export files; run transfers machine to machine and verify by keyed hash.
• Make the migration identity scoped per wave, time-bound, federated and alerted.
• Translate policies by intent and test effective access for real identities in both platforms.
• Turn on target audit logging and test backup and restore before the first secret.
• Migrate in waves by consumer pattern, with defined rollback triggers.
• Freeze the source read-only and alert on every read until it stays at zero.
• Archive source audit logs, revoke its own credentials, destroy backups and recovery material.
• Scan code and configuration for the old endpoint and copied values after decommissioning.

Standards and references

• OWASP: Secrets Management Cheat Sheet
• OWASP: Application Security Verification Standard 5.0
• NIST: SP 800-57 Part 1 Rev. 5, Recommendation for Key Management
• NIST: SP 800-88 Rev. 2, Guidelines for Media Sanitization
• NIST: SP 800-53 Rev 5, Security and Privacy Controls
• NIST: Cybersecurity Framework 2.0

Related NHI Mgmt Group resources: Secrets manager rollout playbook · Secrets Management Guide · Secrets Management Buyer's Guide · Secrets Rotation Runbook Template