Skip to main content

Rotate Keys

Tagnet encrypts sensitive values (device credential passwords, connection profile secrets, and the token used to sign API sessions) with keys that live on the server. "Rotate Keys" is the operation that replaces those keys. This page describes what happens during rotation, when to run it, and what to expect afterward.

The action is performed from the Tagnet Admin Console on your Windows server, under Security → Rotate Keys. It does not run from the Tagnet web UI; rotating keys requires administrator access to the server itself.

When to rotate​

  • After a security advisory that affects Data Protection (the ASP.NET Core component that does the encryption).
  • If a server backup, disk image, or key file has been exposed outside your trust boundary.
  • On a schedule that matches your internal security policy (common pattern: annually, or after any administrator offboarding).
  • After a suspected or confirmed compromise of the server.

Rotation is disruptive: every device that Tagnet communicates with will need its credentials re-entered afterward. Plan the window accordingly.

What happens during rotation​

When an administrator runs Rotate Keys, the admin console performs the following, in order:

  1. Preflight checks: confirms elevation, readable configuration, and that the Tagnet Windows service is installed.
  2. Stops the Tagnet Windows service: all web traffic and device ingestion pauses.
  3. Moves the current key ring aside: the keys\ directory is renamed to keys.bak-<timestamp>. It stays on disk in case you need to roll back.
  4. Moves the JWT signing secret aside: the same pattern, renamed rather than deleted.
  5. Flags every stored device credential for rotation: the database is updated inside a single transaction. Each credential's "rotation required" flag is set, and a security audit event is recorded with your Windows username as the actor.
  6. Starts the Tagnet service: the server regenerates a new key ring and a new JWT secret as it comes up.

A typical run takes well under a minute. The admin console surfaces each step as it runs, and a result panel at the end tells you exactly where the backups went.

What to do afterward​

Re-enter device credentials​

Open the Tagnet web UI and go to Devices. You will see:

  • A warning banner at the top: "N credentials across M devices need rotation."
  • Each affected device row is marked with a key-off icon in warning colors.
  • On each affected device's page, a warning at the top of the Overview and a "Rotation required" chip beside the credential in the Connection section. In Manage credentials the chip's tooltip gives the reason and timestamp.

For each device, open its page, choose Manage credentials from the Actions menu (or from the warning), and either:

  • Edit the credential and re-enter the password you already know, or
  • Regenerate a new password (for inbound data-post credentials, Tagnet can generate one for you).

Saving the credential clears the rotation flag automatically and records an audit event.

You also need to get the new password onto the physical device. For a reader Tagnet manages, the device page's Regenerate ingest password action generates and deploys in one step, and until a deployment succeeds the Overview warns that the reader has undeployed changes. For a cloud reader, a handheld, or any other device, enter the password through its own management path; Tagnet does not update that hardware for you.

Re-enter connection profile secrets​

Connection profile secrets (API keys, Basic auth passwords, bearer tokens, and token-endpoint credentials) are encrypted with the same key ring as device credentials, so they also stop decrypting after rotation. Unlike the device credential flag above, connection profiles are not flagged synchronously during the rotation itself: a profile is flagged the next time Tagnet reads its secrets, which happens whenever a workflow action or token acquisition uses the profile, or when you open the profile to edit it. Once that happens, Tagnet flags the profile automatically rather than letting it fail with a misleading "secret is not set" error:

  • The Connection Profiles list shows a Secrets Need Re-entry chip next to the profile's name.
  • The profile's detail page opens with a warning banner and a Re-enter secrets button.
  • The profile's edit page shows the same warning above the form; secret fields there still display (set), but those stored values are unrecoverable.

Open the Connection Profiles tab of the Integrations page and re-enter secrets on each profile showing the chip. If you are not sure which profiles were touched and want to check proactively rather than waiting for the chip to appear, open each profile's edit page (which reads its secrets and triggers the flag if they are unreadable) or watch the Security Events log for ConnectionProfileSecretsDecryptFailed events, recorded once per profile at Critical severity on the transition into the flagged state. The flag clears automatically as soon as you re-enter a profile's secrets and save. See Secrets Need Re-entry for the full behavior.

Users sign back in​

Because the JWT signing secret was rotated, all previously issued Tagnet login sessions are invalid. The next request from an existing session is rejected and the user is prompted to sign in again. This is expected.

Audit trail​

Rotation and follow-up credential changes are recorded in Tagnet's internal security event log for audit purposes. The log captures who ran the rotation, when it happened, and each credential that was re-entered afterward. If you need this information for a compliance review, contact Stratum Global support.

What the admin console does not do​

  • It does not push new passwords to device hardware. You must do that separately.
  • It does not update any credentials stored outside Tagnet. Rotation only affects values in the Tagnet database and the Tagnet server's local secrets.
  • It does not delete the backed-up key material. The keys.bak-<timestamp> directory and the .bak-<timestamp> JWT secret file stay on the server so you can roll back if necessary. You may delete them manually after you're satisfied the rotation was correct and all credentials have been re-entered.

Prerequisites​

  • You must be running the admin console as administrator. The console will offer a "Restart as administrator" button if not. The data directory and the Tagnet Windows service both require elevation.
  • The Tagnet Windows service must be installed on the machine. Development environments without the service cannot rotate keys via the admin console.
  • Your Tagnet installation must be at version 0.40 or later. Earlier versions don't have the rotation infrastructure.

Safety​

The admin console refuses to rotate keys until you type ROTATE into a confirmation field. This is deliberate: the action invalidates every stored device credential, and a stray click would force an organization-wide re-entry.

If any step after "service stopped" fails, the admin console leaves the backup files in place and reports the exact failure. The result panel shows the backup paths so you can recover manually by restoring them. Contact Stratum Global support if you need assistance with a partial failure; the backup directories are your rollback path.

  • Administration: server-side configuration and how Tagnet stores secrets.
  • Users, roles & access scopes: post-rotation, all sessions are invalidated and users sign in again; this article covers the auth model.