Docs / Admin

Auth keys

Pre-authentication keys (“auth keys” for short) let you register new nodes without needing to sign in via a web browser. This is most useful when spinning up containers, IoT devices, or using infrastructure-as-code systems like Terraform.

About auth keys

Types of auth keys

There are three types of auth keys:

  • One-off Keys for one-time use. They can be used to connect a device or server, only once. This is meant for situations where you can’t authenticate on the device yourself, so using a key is more practical. For example, a cloud server might use a one-off key to connect.
  • Reusable Keys for multiple uses. They can be used to connect multiple nodes. For example, multiple instances of on-prem database might use a reusable key to connect.
  • Ephemeral Keys for authenticating ephemeral nodes for short-lived workloads. Since node keys are not persisted when a workload restarts, these will reconnect as a different node. Nodes which are no longer active will be automatically removed. For example, containers or Lambda functions should use an ephemeral key to connect.
Be very careful with reusable keys! These can be very dangerous if stolen. They’re best kept in a key vault product specially designed for the purpose.

Authentication

Auth keys authenticate a machine as the user who generated the key. That is, if Alice generates an auth key, and uses it to add a server to her tailnet, then that machine is authenticated with Alice’s identity. Think of it as logging into a machine.

In an upcoming release, each issued auth key will be able to be restricted to only certain ACL tags. For now, an auth key inherits all the network rights of the user who generated it. Be careful!

Generating a key

Step 1: Generate an auth key

As a network admin, visit the auth key page. You can choose what kind of key you’d like to generate.

This page also gives you the ability to revoke existing keys.

Step 2: Register a node with the auth key

When you register a node, use the --authkey option to supply the key and bypass interactive login:

sudo tailscale up --authkey tskey-abcdef1432341818

Optional: Revoking a key / node

To revoke a key, visit the same auth key page, locate the key in the table at the bottom, and press “revoke.”

Any nodes authorized with the key will stay authorized, even after the key is revoked. To de-authorize the node, delete it from the machines admin page.

Last updated

WireGuard is a registered
trademark of Jason A. Donenfeld.

© 2022 Tailscale Inc.

Privacy & Terms