Rotate SideroLink Join Token

This guide shows you how to rotate SideroLink join tokens.

Join tokens are the secret used to authenticate Talos machines’ gRPC requests when they first establish a WireGuard tunnel connection to Omni.

If the token is compromised it can be revoked and replaced with the new one.

Conditions that Make Token Rotation Possible

When a machine connects to Omni for the first time, it uses a join token specific to the Omni account that is shared by all new hosts that are registering with Omni. Omni then creates a unique, ephemeral token for each machine, and when Talos is installed to disk, that token is persisted to disk. If the shared token is revoked, machines that have persisted unique tokens (i.e. those with Talos installed to disk) will stay connected, but machines using only shared tokens will be disconnected.

Talos < 1.6 doesn’t support unique tokens.

If Omni is started with --join-tokens-mode=legacy unique node tokens are not generated for any machines. This makes rotating join tokens not possible.

To Rotate Join Tokens

UI

Create New Join Token

Click the “Join Tokens” section button under “Machine Management” in the sidebar. Next, click the “Create Join Token” button on the right.

Give the new token a name and click the “Create Join Token” button.

Replace the default token

If the token that you are going to revoke is the default, mark the new token as the default.

Revoke the old token. Note the warnings regarding machines that will be affected by the revocation of the old token.

If there are warnings and the token is rotated anyway, the machines in the list will get disconnected after the next restart of Omni or the machine.

If it is safe to rotate the token, Omni will show a green check mark.

Click Revoke.

You can copy now the new token and start using it.