Managing the Keyring

The TrueNAS Connect keyring provides secure, encrypted storage for your TrueNAS system keys, enabling automatic authentication when accessing your systems through TrueNAS Connect.

This tutorial walks you through creating a keyring, adding systems to it, and managing your keyring.

Understanding the Keyring

TrueNAS Connect automatically creates a key when you register your system in TrueNAS Connect. The keyring encrypts and stores keys client-side using a passphrase you create. This allows TrueNAS Connect to automatically authenticate with your systems without storing your TrueNAS user credentials.

Key benefits of using a keyring:

• Automatic authentication: No need to manually enter credentials for each system
• Client-side encryption: Your keys are encrypted locally using your passphrase
• Secure storage: TrueNAS user credentials are never stored by TrueNAS Connect
• Quick access: Unlock all connected systems at once with a single passphrase

Creating Your First Keyring

When you first access TrueNAS Connect, you need to create a keyring to enable automatic authentication.

When no keyring exists, the top toolbar displays a Create Keyring button. Click this button to open the Create Keyring Passphrase dialog and begin creating your keyring.

Setting Up Your Keyring Passphrase

On the Create Keyring Passphrase dialog:

1. Enter an identifier for your keyring in Name (e.g., MyTrueNAS-Keyring).

2. Enter a strong passphrase for encrypting your keys in Passphrase. Choose a unique passphrase distinct from your TrueNAS system passwords and your OAuth account password, that is something memorable but secure.

3. Re-enter your passphrase in Confirm.

4. Click Ok to create the keyring.

The Ok button remains disabled until all fields are completed and the entered passphrases match.

Adding Systems to Your Keyring

After creating your keyring, you can add your other TrueNAS systems to enable automatic authentication.

Adding During System Authentication

You can add a system to your keyring during the authentication process.

From the Dashboard, locate the system card you want to add. Enter the system authentication credentials, and then select the Add to Keyring option.

Complete the authentication process. A system key is automatically created, encrypted, and stored in your keyring.

Viewing Keyring

To see which systems are stored in your keyring:

Go to the Keyring screen. The TrueNAS Systems table, shows the system name in the TrueNAS column, Key shows Stored when an key is saved, or is blank if ones is not stored. Connected shows true for successful connections, or false for failed connections.

You can go to the TrueNAS UI My API Keys to see the TrueNAS Connect API key.

Unlocking Your Keyring

After setting up a keyring, each time you sign into TrueNAS Connect the Unlock Keyring dialog automatically opens, and prompts you to enter your passphrase to unlock the keyring.

1. Enter your keyring passphrase.
2. Click Ok to unlock all systems in the keyring. All systems with stored keys are automatically authenticated, and the system information cards on the dashboard populate with system data.

If you click Cancel, you need to authenticate each system individually using TrueNAS system credentials.

Managing Your Keyring

Resetting the Keyring

If you need to remove all stored keys and start over:

1. Go to the Keyring screen.
2. Click the Reset button in the header.
3. Review the confirmation dialog warnings.
4. Click Ok to proceed with the reset, or Cancel to keep your existing keyring

After a Keyring Reset

After resetting a keyring, system included in the keyring require manual authentication the next time you sign into TrueNAS Connect. You need to re-enter system credentials for each system individually.

If you want to rebuild your keyring, create a new keyring using the Create Keyring button on the top toolbar. Remember to check Add to Keyring when re-authenticating.

Best Practices

The TrueNAS Connect keyring streamlines access to your TrueNAS systems by:

• Providing secure, encrypted storage for keys
• Enabling automatic authentication across all your systems included in the keyring
• Eliminating the need to enter individual system credentials each time you sign into TrueNAS Connect
• Maintaining security through client-side encryption

With your keyring properly configured, you can focus on managing your TrueNAS systems rather than repeatedly entering authentication credentials.

Passphrase Security

When choosing a passphrase for the keyring:

• Create a unique passphrase distinct from your TrueNAS system passwords and your OAuth account password.
• Choose a passphrase that is memorable but secure.
• Consider using a passphrase manager for complex passphrases.

Troubleshooting Authentication

If a system shows false in the Connected column, check:

• The TrueNAS system is online and accessible
• The stored key hasn’t expired or been revoked
• The network connectivity between TrueNAS Connect and your system is stable

Re-authenticate the system if needed and add it back to the keyring.