User Management and Security.

Before setting up users and security.

Prerequisites and framing.

Understand who will use the system. User management starts with knowing the roles. The owner, production staff, part-time workers, outside consultants, visiting growers — each interacts with the system differently. Before creating accounts, think through who needs what access.

A clear view of what users can affect. An administrator account can change automations, modify integrations, and effectively control everything. A limited user can only see what has been exposed and only take the actions that role allows. The power differences matter; matching the role to the responsibility matters more.

Baseline security in place. Strong passwords, two-factor for the owner account at minimum, updates applied, the network configured sensibly. Advanced security patterns build on this baseline; they do not substitute for it.

Realistic operational view. Every security measure has an operational cost — users have to remember passwords, tap two-factor codes, go through authentication. Security that makes the operation unworkable gets bypassed. Balance matters; the goal is security that fits into how the operation actually works.

Home Assistant user roles.

What Home Assistant provides out of the box.

Owner. The first user created. Has full access to everything — configuration, integrations, user management, system settings. Cannot be demoted to a regular user (but an admin can be promoted to owner under certain conditions). Operations should have exactly one owner; the account with primary responsibility for the installation.

Administrator. Users with admin rights have nearly full access — the same as the owner for most practical purposes. Admins can install integrations, modify automations, create other users, and access system settings. Limit admin accounts to trusted users who need the broad access.

Regular user (non-admin). Users without admin rights cannot access configuration settings, install integrations, or modify automations through the UI. They can interact with the system — view dashboards, issue commands on exposed entities, receive notifications. The default for most staff accounts.

Voice-only users. A specific non-admin user type for voice-pipeline access where the user identity is associated with voice commands but does not have a general account. Used when voice pipelines identify users for per-user context.

Local users vs. guest access. Home Assistant does not have a "guest" user type in the conventional sense. A guest-like account is a regular user with limited entity exposure and no destructive capabilities. For operations that host visitors regularly, a "visitor" user account with a read-only dashboard is the practical equivalent.

Permission patterns.

How users get differentiated access.

Entity exposure per user. Home Assistant can expose specific entities to specific users — or, more accurately, to the voice assistant a user interacts with. A production staff user's voice interactions only see the entities their role needs; they cannot voice-command things outside that scope.

Dashboard access per user. Each dashboard has access controls. The owner's admin dashboard is visible only to the owner; the staff dashboard is visible to staff; the visitor dashboard is visible to visitors. Per-dashboard visibility is the primary mechanism for role-based view differences.

Admin-only automation changes. Non-admin users cannot modify automations or scripts. They can trigger those scripts (if the scripts are exposed to them) but cannot change them. This is the single most important distinction for staff access — staff can operate the system, not reconfigure it.

Integration access. Only admins can add or modify integrations. Non-admin users see the integrations as configured but cannot change them.

Developer tools access. The developer tools (states, services, templates, events) are admin-only. This prevents non-admin users from making service calls that bypass the UI's normal restrictions.

System settings access. The Settings area is primarily admin-only. Some user-specific settings (own profile, own theme preference) are accessible to every user; installation-wide settings are admin-only.

Practical implication. For most operations, two account types cover most needs: admin (the owner and possibly a backup admin) and regular user (everyone else). Additional differentiation happens through dashboard visibility and entity exposure rather than through a deeper permission hierarchy.

Creating user accounts.

The process.

From the admin UI. Settings → People or Settings → Users (the exact navigation varies by Home Assistant version). Add a new user; set name, username, and password; choose admin or non-admin. The new account is active immediately.

Account information to collect. Name (for display), username (for login), password (strong, unique), role (admin or user), default dashboard (what the user sees on first opening the app), theme (per-user preference), and whether MFA is required.

Password requirements. Home Assistant does not enforce password complexity by default, but the owner can set expectations operationally. A password manager is the practical way to manage strong unique passwords across users; every staff member having their own strong password is the baseline.

First-time login experience. A new user logs in with the admin-provided password, ideally changing it on first login. Two-factor authentication should be enabled at this point if the operation requires it.

Account deactivation. Users who leave the operation need their accounts deactivated promptly. A former employee with active Home Assistant access is a loose end that matters. Document a process for account deactivation — the day someone leaves is not the day to figure out how to revoke access.

Two-factor authentication.

An extra layer for accounts that matter.

What two-factor does. In addition to the password, the user provides a time-based code from an authenticator app. Even if the password is compromised, the attacker cannot log in without the code, which requires physical access to the user's phone or hardware key.

Authenticator apps. Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, and others. All work with Home Assistant's TOTP (time-based one-time password) implementation. The user scans a QR code during setup; the app then generates codes that match Home Assistant's expectation.

Hardware keys. Home Assistant supports WebAuthn (FIDO2) hardware keys — YubiKey, SoloKey, and similar. More secure than authenticator apps (resistant to phishing) and sometimes more convenient (tap to authenticate). For accounts with serious security requirements, hardware keys are the strongest option.

When to require two-factor.

- Always for owner and admin accounts. Admin access is the keys to everything; it should always have the strongest protection available. - For remote-access users. Users who log in from outside the local network benefit from two-factor. Local access is less exposed; remote access is more. - Optional for limited staff accounts on-site only. Production staff who only use the system inside the operation, with no admin access, can be configured without two-factor if operational friction matters. Not ideal; acceptable.

Setup in Home Assistant. Settings → [user profile] → Two-Factor Authentication. Enable TOTP or WebAuthn. Save backup codes — these recover access if the primary device is lost.

Backup codes. TOTP setup generates backup codes for recovery scenarios (lost phone, dead hardware key). Save these securely — written down and stored safely, or in a password manager. Losing both the authenticator and the backup codes can lock the user out.

Recovery scenarios. Plan for lost devices. If the owner loses their phone and backup codes, regaining access requires physical server access and some recovery procedures. For operations where this scenario could happen, the recovery process should be documented and practiced.

Session management.

How long users stay logged in.

Session duration. Home Assistant sessions last a long time by default — users stay logged in for extended periods once authenticated. This is usually fine for trusted devices on the local network.

Token management. Long-lived access tokens (used by integrations, mobile apps, and some services) should be reviewed periodically. Old tokens from services no longer used should be revoked. Settings → Security → Long-lived access tokens shows what exists and lets admins revoke.

Logout on shared devices. Devices used by multiple people should log out between users. The Home Assistant mobile app and web UI support this. For shared tablets or terminals, the operation's discipline matters.

Idle timeout. Home Assistant does not aggressively time out idle sessions. For operations where this matters (public-facing terminals, shared computers), the operation can configure browser-side timeouts or procedural requirements.

Network architecture.

Where Home Assistant sits on the network matters.

VLANs and network segmentation. Separating IoT devices (sensors, switches, cameras) from the main network protects both. If a compromised IoT device is on a segregated network, it cannot reach the rest of the operation's systems; if an attacker breaches the main network, the IoT devices are one layer harder to reach.

Typical segmentation pattern.

- Main network. Laptops, phones, workstations. Internet access; full access to the local network (including Home Assistant through appropriate routing). - IoT network. Home Assistant host, ESP devices, smart plugs, sensors, cameras, and similar. Limited internet access (only what is needed — cloud integrations, software updates). Limited or no access to the main network. - Guest network. Visitor devices. Isolated from both main and IoT networks. Internet access only. - Optional: a "management" network. The router, switches, and network infrastructure management interfaces. Further segregated; only accessible from specific devices.

Firewall rules between segments. The router or firewall enforces the segmentation. Specific rules allow required traffic (the main network's devices reach Home Assistant's UI; Home Assistant reaches cloud integrations and update servers); everything else is blocked.

The Home Assistant host's network. The Home Assistant host typically sits on the IoT network. Its integrations reach out to devices on the IoT network; its UI is accessible from the main network through a firewall rule allowing that specific traffic.

Operations that do not segment. Many small operations have a single network — no VLANs, all devices together. This is a common starting point. Segmentation is an upgrade when security matters more and when the operation has the technical capacity to configure it. Operations without segmentation should still follow other security practices; segmentation is one layer, not the only one.

IoT devices with poor security. Some IoT devices have security problems that do not get fixed by their manufacturers. Cameras with known vulnerabilities, smart plugs that phone home in unsecured ways, devices that insist on outbound cloud connectivity. Network segmentation limits what these devices can reach; at some point, the worst-offender devices should be replaced.

Secrets management.

API keys, passwords, and tokens.

The secrets.yaml file. Home Assistant's convention for storing sensitive values — API keys, passwords, tokens — separately from regular configuration. Configuration files reference secrets by name; the actual values live in secrets.yaml.

Why secrets.yaml matters. When configuration files are shared (version control, troubleshooting, community help), the sensitive values should not travel with them. secrets.yaml lets the configuration be portable while keeping secrets local.

Example pattern:

```yaml

# configuration.yaml notify: - platform: sms apikey: !secret smsproviderapikey ```

The `!secret` syntax tells Home Assistant to look up the value in secrets.yaml:

```yaml

# secrets.yaml — never committed to version control smsproviderapi_key: abc123-not-a-real-key-xyz ```

secrets.yaml in version control. Never. The file is explicitly excluded from version control (`.gitignore`) for a reason. Committing secrets to a public repository is a classic security failure with real consequences — exposed secrets get found by automated scanners within hours.

Rotation. Credentials should be rotated periodically — cloud API keys, passwords for external services, tokens. The specific rotation cadence depends on the sensitivity; quarterly is reasonable for most agricultural operations, more frequent for highly-sensitive credentials.

When credentials are exposed. If a secret leaks (accidentally committed to public Git, shared in a support forum, exposed through a compromised service), revoke and rotate immediately. The leaked credential is assumed to be compromised; generating a new one and invalidating the old is the fix.

Password managers for operations. A shared password manager for the operation (1Password Teams, Bitwarden, Keeper) gives authorized users access to operational credentials without everyone sharing the same passwords. The operation's policies govern who has access to what within the password manager.

Physical security.

The hardware itself.

Where the Home Assistant host lives. A locked office or closet is better than an open workspace. Physical access to the host means physical access to everything — disk contents, the ability to boot from external media, the opportunity to install hardware keyloggers. For operations with security concerns, physical security of the host matters.

USB access and boot security. Someone with physical access can boot from a USB drive, bypassing the installed OS and reading the disk's contents. Disk encryption (Full Disk Encryption on the host) makes this much harder. BIOS/UEFI passwords prevent changing boot order. These measures together raise the bar significantly.

Display access. A Home Assistant dashboard on a wall-mounted tablet in a public area can be used by anyone who walks up. Screen lock, user authentication on the device, and physical placement that limits casual access all matter.

Network port access. Ethernet ports accessible to anyone in the operation are a risk if someone could plug in an unauthorized device. For high-security operations, port security (only authorized devices can connect) is an option; for most operations, physical access control is the practical approach.

Theft considerations. A stolen laptop or desktop running Home Assistant gives the thief access to everything on it. Disk encryption protects against casual theft; it does not protect against a determined attacker with time. Backups offsite protect the data; the operational impact of loss is bigger than data recovery.

Operational security.

Ongoing practices.

Update discipline. Security updates matter. The longer an installation runs on an unpatched version with known vulnerabilities, the higher the risk. See [Updates and Version Management](/home-assistant/operations/updates) for update practices.

Monitoring. Unauthorized access attempts, unusual behavior, and security-relevant events should produce alerts that reach someone who will act on them. Monitoring that nobody looks at is not monitoring.

Least privilege. Every user has the minimum access they need — no more. New integrations are only admin-accessible until tested and intentionally exposed. Services run with minimum necessary privileges.

Audit logs. Home Assistant logs authentication events, configuration changes, and significant actions. Periodic review of logs reveals patterns — whose accounts are used when, what changes, whether anything unusual has happened.

Security awareness for users. Staff who use the system benefit from basic security awareness — do not share passwords, recognize phishing attempts, report anything that seems off. A trained user is a better first line of defense than any technical control.

Incident response plan. What happens when something seems wrong. Who gets notified; what gets shut down; how to investigate; when to rebuild. Having a plan before an incident is much better than developing one during an incident.

Common failure modes.

Specific security problems from real deployments.

The admin account with a weak password. The owner set a memorable but weak password; an automated attack guessed it; the attacker gained admin access. Fix: strong passwords for all accounts, especially admin; two-factor authentication; password manager.

The staff account that had admin access. A staff member was given admin access "temporarily" during onboarding and never reduced. When they left the operation, the account was deactivated but had caused minor configuration changes during their tenure that were hard to trace. Fix: least-privilege from the start; admin access only for those who actually need it; explicit review of access scopes periodically.

The two-factor authentication that was bypassed by a recovery code the owner shared. The owner shared their backup codes with a partner for "just in case" purposes; the partner saved them insecurely; they leaked. Fix: backup codes are as sensitive as the primary authentication; they should be treated accordingly; avoid sharing.

The former employee whose account stayed active. The employee left; their account was not deactivated; months later, unusual activity traced back to that account from an unexpected IP. Fix: account deactivation is part of the offboarding process; do it the day the person leaves.

The integration with a credential that was shared across users. A specific integration used an account shared by multiple people; when someone left, the shared credential was not changed; the former member retained effective access. Fix: unique credentials per person where possible; when shared credentials must exist, rotate when team composition changes.

The network that let an IoT device reach the management interface. A compromised IoT device (a vulnerable camera) was on the same network as the router's management interface; the attacker used the camera as a pivot to attack the router. Fix: VLANs separating IoT from management; management interfaces not accessible from the IoT network.

The secrets.yaml accidentally committed to public Git. The owner accepted a community member's help and shared the configuration directory; secrets.yaml was not excluded; the commit went to a public repository; the API keys were found by scanners within hours. Fix: .gitignore that explicitly excludes secrets; review commits before pushing; assume leaked secrets are compromised and rotate immediately.

The backup that contained unencrypted secrets and was stored in cloud storage. The operation's cloud backup was not encrypted; the cloud storage service had a vulnerability; the backup was exposed. Fix: backup encryption, especially for backups stored outside the operation's direct control.

The tablet in the greenhouse that anyone could use. A staff dashboard on an unlocked tablet was accessible to anyone in the greenhouse. A visitor tapped "disable automation" out of curiosity. Fix: screen lock, user authentication on the tablet, or limited-scope dashboards that cannot do damage even if tapped by the wrong person.

The delayed security update. A critical Home Assistant security update was available for weeks; the owner delayed applying it "because the operation was busy"; an exploit for the vulnerability appeared during the delay window. Fix: security updates apply promptly; set aside time for routine updates rather than delaying indefinitely.

What not to do.

Patterns to avoid.

Don't share accounts between people. Each person has their own account. Shared accounts make it impossible to know who did what and make offboarding messy.

Don't give admin access by default. Least privilege means regular users get regular access. Admin is for those who actually need it. Adding admin temporarily usually ends up permanently.

Don't skip two-factor on admin accounts. The admin account is the keys to the operation. Two-factor is the difference between "password compromised, attack succeeds" and "password compromised, attack fails."

Don't store credentials in plain text. secrets.yaml is for secrets; configuration for references. Credentials hardcoded in configuration files eventually get shared accidentally.

Don't commit secrets to version control. Especially public repositories. Secret scanners find exposed credentials quickly; exploitation follows.

Don't delay account offboarding. A former staff member with active access is an unnecessary risk. Deactivate accounts the day the person leaves.

Don't ignore security updates. The longer a known-vulnerable installation runs, the higher the risk of exploitation. Updates matter; apply them promptly.

Don't rely on network obscurity for security. A Home Assistant on a non-default port on a "private" network is not secure if the network itself is not secure. Defense in depth matters.

Don't skip backup encryption when backups leave the site. Backups contain sensitive data; offsite backups are outside the operation's direct control; encryption is how the operation retains protection.

Don't treat security as a one-time setup. Security is ongoing. Users change. Software gets updated. Threats evolve. A security posture that was fine last year may have gaps now. Periodic review is how it stays current.