Skip to content

Move the tenant's keys to another backend

Change what protects your tenant's keys once the tenant holds keys: bring your own KMS, change it, leave it for the ENTERPRISE tier managed by ANKATech, or accept a move a plan change requires. The keys move in a key custody move, in a window you schedule.

Who can do it

A tenant administrator or a tenant key manager, or a platform super admin working inside the tenant. The move controls appear only to a person who holds the permission to manage the tenant's key custody; everyone who can read the custody sees the move and its progress.

Before you start

  • The tenant already has a key-encryption key. A tenant without one declares its first backend instead: see Bring your own KMS (BYOK).
  • To move to your own KMS, your plan includes it, and a key exists in your own Cloud KMS account with a credential that can use it. Keep your current key usable until the move completes.
  • The tenant has no other custody move open, and it is not suspended or closed.
  • A move in a maintenance window pauses your applications' key operations: they receive a temporary 503 with a retry hint until the keys are live on the destination. Plan the window accordingly.
  • On a customer-operated deployment, the platform operator has delegated key protection to your tenant.

Steps

  1. Open Settings in your tenant's navigation, then the Integrations tab.
  2. On the Key protection row, select its action. The key-protection panel opens over the page; the move is under Key custody.
  3. Start the move, or take up the one that waits for you:
    • To start one, select Bring your own KMS…, Change KMS… or Change custody…, whichever the panel offers.
    • When a plan change gives you the ENTERPRISE tier, the panel shows Custody move pending: choose where the keys go. Select Choose the destination….
    • When a plan change takes you off your own KMS, the panel shows A plan change needs your consent. Go to step 6.
  4. In the dialog, choose the destination:
    • ENTERPRISE tier, managed by ANKATech: nothing to configure.
    • The tenant's own KMS: choose the Key management service and fill in Key and access credential. The key is tested with a round trip before the move is recorded.
    • Back to the deployment backend, on a customer-operated deployment: confirm by typing the tenant's name.
  5. Select Record the move. Nothing moves yet: the panel shows Custody move pending: schedule its window.
  6. Select Schedule the window…, or Accept and schedule… for a move off your own KMS. In the dialog:
    1. Choose the Start of the move: at the default notice, Now, or At a chosen time.
    2. For a start earlier than the default notice, give the Reason for starting earlier than the notice. It is recorded in the audit trail.
    3. For a move off your own KMS, tick the acknowledgement that ANKATech will be able to unwrap your keys after the move.
    4. Select Schedule, or Accept and schedule.
  7. Follow the move under Steps of the move. Before it starts you can still select Change the start…, Change the destination… or Cancel the move. Once it has started, and until the keys are live on the destination, you can select the abort control, which reopens the tenant on its source.

To return to a key-encryption key you left, open Key-encryption keys, select Roll back… on the retained version and select Schedule the roll back. A retained version stays available for 30 days. On an ANKA-hosted deployment the panel offers a roll back only when it concerns your own KMS: back to an own key you left, or from your own key back to the ENTERPRISE tier you left.

What you see when it worked

The console reports The custody move is scheduled. While the window runs the tenant is in maintenance: key lists and key details stay readable, and you can sign in and follow the progress. When the move completes, Protected by names the destination, Key-encryption keys lists the new version as active and the previous one as retired, and Custody history records the move. Every step of the move is written to your audit log, and the tenant administrators are notified when the window is scheduled and again before it starts.

If it fails

What you see Cause What to do
The tenant already has a custody move open Another move is pending, scheduled or running Finish, cancel or abort that move first
No key management service is offered to this tenant right now No own-KMS service is admitted under the plan the move puts in force Choose another destination, or ask your platform operator
The own-key round trip fails, shown on the field it concerns The key cannot be reached or used with the credential Correct the key or the credential and record the move again
The platform cannot move the tenant's keys to that destination The ENTERPRISE tier's HSM module does not serve its token right now; nothing was placed Ask your platform operator, then record the move again
A window starting earlier than the platform's default notice needs a reason The start is earlier than the notice and no reason was given Give the reason, or start at the default notice
The keys are already live on the destination, so the move can only complete You tried to abort after the swap Let the move complete, then roll back if needed
That key-encryption key is no longer retained Its 30-day retention ended, or it was retired by a re-key after a compromise No roll back to that version is possible
A suspended or closed tenant's custody does not move The tenant is not active Have the tenant reactivated first
The move is no longer in a state this operation applies to The move advanced since the panel was read Refresh and read where it stands

Without the console

Surface How
Key management CLI No command
Admin SDK Not available
API POST /api/v3/admin/tenants/{tenantId}/key-custody/moves (operation createTenantKeyCustodyMove); PUT …/key-custody/moves/{moveId}/destination (operation replaceTenantKeyCustodyMoveDestination); PUT …/key-custody/moves/{moveId}/schedule (operation replaceTenantKeyCustodyMoveSchedule); POST …/key-custody/moves/{moveId}/cancel (operation cancelTenantKeyCustodyMove); POST …/key-custody/moves/{moveId}/abort (operation abortTenantKeyCustodyMove); POST …/key-custody/rollback (operation rollbackTenantKeyCustody)