Rehearse an AWS KMS workload token

Use disposable keys to verify a short-lived workload token, rehearse a planned signing-key rotation and check what happens when you revoke a workload.

Before you start

KeySigner source checkout, Node.js 26.6.0, Python 3, Rust 1.98.1 and wasm-pack 0.13.1

  • The example supplies a local test key service and two disposable keys. For live AWS permissions and key policies, use the separate AWS key access guide.

Data and access

Shared or checked
KeySigner sends the token’s signing input to the key service and publishes public keys a receiving service can use to verify tokens.
Check separately
Revoking a workload binding blocks new token requests for that binding. An already-issued token can still verify until it expires. Check any session it opened, which real IAM role can sign and which audiences and actions each receiving service allows.

Who does what

KeySigner
Issues short-lived tokens, publishes both public keys during rotation and can revoke one workload’s ability to get new tokens.
Local key service
Holds two disposable signing keys. It stands in for AWS KMS during the rehearsal.
Token verifier
Checks the signature with an independent public key and checks the token’s audience, subject and expiration.
  1. Prepare the developer checkout

    Set KEYSIGNER_SOURCE to the absolute path of your KeySigner source checkout. From that checkout, install the test dependencies and build the local components if you haven’t already.

    cd "$KEYSIGNER_SOURCE"
    python3 tools/dev.py install
    python3 tools/dev.py build-protocol
    python3 tools/dev.py build-authority

    Check. The local builds finish successfully in the same checkout.

  2. Save the local rehearsal

    Download the example to a scratch directory as verify-workload-token.mjs. It starts a temporary signing service on your computer with two disposable keys.

    Download verify-workload-token.mjs

    Check. The example uses loopback and generates two disposable public and private key pairs.

  3. Run the test through rotation

    Run the example from the scratch directory. It checks signature verification and signing refusal, then publishes the replacement key before sending it any signing requests. Note which key verifies each token before and after the change.

    node verify-workload-token.mjs

    Check. Expect the original token to verify, the edited audience and refused signing to fail, and tokens issued on either side of the change to verify with their respective keys.

  4. Check what emergency revocation stops

    The same run revokes one workload’s binding, the record that lets it request a token. Confirm the denied request, then compare it with an unexpired token and the other workload. If a token already opened a session with another service, use that service to check the session’s lifetime and revoke it there if needed.

    Check. Expect the revoked binding’s request to return binding_revoked and the separate workload to receive a valid token. The token issued before revocation still verifies before its expiration. The retiring public key disappears after the overlap.

Check your result

For planned rotation, verify the replacement public key appears before it signs, and verify the retiring key stays published through its last token’s lifetime plus the overlap. For emergency revocation, verify a new request is denied for that workload. Check already-issued tokens and downstream sessions separately.

What we tested

Tested on . We ran the downloadable example with Node.js 26.6.0 against KeySigner source revision 0dbc45819. Node verified both signing keys using the local key service’s public keys. The test checked both sides of the change, retirement after overlap, and the effects of revoking a single workload binding. It uses a simulated key service and creates no AWS sessions.

How to verify your setup

If you get stuck

The rehearsal stops before it issues a token

Check that KEYSIGNER_SOURCE points to the checkout where you installed the test dependencies and built both components. The example uses its own loopback signing service and runs with short test lifetimes. In a real rollout, check the receiving service’s key cache and session lifetime before scheduling a change.

Report a problem with this guide

Explore all setup guides →