Configure connection and authentication

Authentication

This document explains how the Home Assistant VS Code extension securely manages your authentication credentials, including your Home Assistant Long-Lived Access Token and your Home Assistant instance URL.

The extension offers the following core functionalities for managing and verifying your authentication:

• Set Authentication: Allows you to enter a new token and your Home Assistant instance URL, which will replace any existing credentials.
• Clear Authentication: Enables you to remove the currently stored token and Home Assistant instance URL.
• View Authentication Details (Obscured): Lets you see your configured Home Assistant instance URL and a partially hidden version of your token, along with any available validity information.
• Test Connection: Provides a way to directly test if the extension can connect to your Home Assistant instance using the stored credentials.
• Debug Authentication: Provides detailed information about your authentication configuration, including the source of the token and Home Assistant instance URL, token validity, and connection test results.

Troubleshooting Connection Issues

If you encounter authentication issues:

1. Use the "Debug Home Assistant Authentication" command to identify which token and Home Assistant instance URL source is being used
2. Check if your token has expired (JWT tokens have an expiration date)
3. Verify that the correct Home Assistant instance URL is configured
4. For TLS certificate issues, try enabling the "Ignore Certificates" option in settings

Enhanced Security with SecretStorage

Starting with v1.44.0, the Home Assistant Config Helper extension now uses VS Code's SecretStorage API to securely store your Home Assistant long-lived access token and Home Assistant instance URL. This provides enhanced security by:

1. Storing your credentials in your operating system's credential manager (Keychain on macOS, Windows Credential Manager, or Secret Service API/libsecret on Linux).
2. Keeping your credentials out of your settings.json file, which prevents accidental exposure when sharing settings or synchronizing them across devices.

Credential Sources (Priority Order)

The extension checks for tokens and URLs in the following order:

1. VS Code SecretStorage (most secure): Credentials stored in the system's secure credential store
2. Environment Variables: HASS_TOKEN, SUPERVISOR_TOKEN, and HASS_SERVER (for the Home Assistant instance URL)
3. settings.json: Legacy storage method (least secure, will be automatically migrated)

Environment Variables Support

You can use the following environment variables:

• HASS_TOKEN: Your Home Assistant long-lived access token
• SUPERVISOR_TOKEN: For Home Assistant OS/Supervised installations
• HASS_SERVER: Your Home Assistant instance URL

When running in the Home Assistant OS/Supervised environment, the extension will automatically use the Supervisor API if SUPERVISOR_TOKEN is set.

How Authentication Migration Works

When you upgrade to version 1.44.0 or later:

1. The extension will automatically migrate any existing token and Home Assistant instance URL from your settings.json to secure storage.
2. You'll receive a notification confirming that the authentication details have been securely migrated.
3. The authentication entries in settings.json will be cleared to prevent duplication.

Managing Your Authentication

You can manage your Home Assistant authentication details directly within VS Code using the Command Palette.

Accessing Authentication Commands

1. Open the Command Palette: Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS).

2. Search for Authentication Commands: Type Home Assistant: Manage Home Assistant Authentication and select it from the list.

3. Choose an Action: You will be presented with several options:

   • Set Authentication:

     1. Select this option to provide a new Home Assistant Long-Lived Access Token and your Home Assistant instance URL.
     2. You will be prompted to enter your Home Assistant instance URL first (e.g., http://homeassistant.local:8123 or https://your_domain.duckdns.org).
     3. Next, you will be prompted to paste your Long-Lived Access Token.
     4. These details will be securely stored and will replace any existing credentials.

   • Clear Authentication:

     1. Select this option to remove any currently stored Home Assistant token and Home Assistant instance URL from VS Code's secure storage.
     2. You will be asked for confirmation before the credentials are deleted.

   • View Authentication Details (Obscured):

     1. Select this option to display your currently stored Home Assistant instance URL and a partially obscured version of your access token.
     2. This helps you verify which credentials the extension is using without fully exposing your sensitive token.
     3. Information about token validity (if applicable and decodable from the token) may also be shown.

Testing Your Connection

After setting or if you suspect issues, you can test the connection:

1. Open the Command Palette: Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS).
2. Search for the Test Command: Type Home Assistant: Test Home Assistant Connection and select it.
3. View Results: The extension will attempt to connect to your Home Assistant instance using the stored credentials.
   • You'll receive a notification indicating whether the connection was successful or if an error occurred.

Advanced Authentication Management

For more detailed troubleshooting, the extension offers these commands, also accessible via the Command Palette (Ctrl+Shift+P or Cmd+Shift+P):

1. Home Assistant: Debug Home Assistant Authentication:

   • How to run: Open the Command Palette, type Home Assistant: Debug Home Assistant Authentication, and select it.
   • What it does: This command provides a detailed report in the Output panel. The report includes:
     • The source of the currently active token and Home Assistant instance URL (e.g., SecretStorage, environment variables).
     • Details about the token itself (e.g., if it's a JWT, its expiration).
     • Results of a connection test to your Home Assistant instance.
   • Use this to: Understand exactly what credentials the extension is attempting to use and diagnose connection problems.

2. Home Assistant: Repair Home Assistant Authentication Configuration:

   • How to run: Open the Command Palette, type Home Assistant: Repair Home Assistant Authentication Configuration, and select it.
   • What it does: This command attempts to automatically resolve common issues, such as:
     • Ensuring credentials are correctly stored in SecretStorage.
     • Assisting with the migration process if it didn't complete correctly.
   • Use this if: You suspect your authentication details are not stored correctly or if you've had issues after an update.

Security Considerations

• The authentication details are only stored locally on your device in the system's secure credential storage.
• No authentication details are transmitted to any third parties.
• If you're using VS Code's Settings Sync feature, your authentication details will NOT be synced between devices.