Expand further on credential management

[mkerstner]

Problem statement

Based on the OpenHomeFoundation/goals#17 and recent efforts on #69 and #70 we want to further expand on this feature.

This first iteration was focused around aligning the technical foundation focusing on Matter and Z-Wave locks to streamline how to interact with credentials for these protocols for everyone to build upon.

Following the initial scoping for credential management outlines in this document https://docs.google.com/document/d/1kHqgRYzKV_FWDjPqZkr_D4B4jG2tf6nGhHUH0W7nBM4/edit?tab=t.0#heading=h.iup5wfolvtoy we not want to further expand based on first feedback and potentially missing scope.

Community signals

• Feedback after the initial release of the Matter lock credentials management in Home Assistant release 2026.3

Scope & Boundaries

In scope

• Gather feedback on existing solution on Matter and Z-Wave side
• What are we missing from an initial scoping perspective and what can be improved further?
• Are we happy with the current placement on device level or do we want to have a discussion from a UI perspective to move it closer to the user?
• Keep focus on locks for now - but think about how to expand to e.g. alarm panels as well to aim for a coherent solution independent of the device type

Not in scope

Foreseen solution

wip

Risks & open questions

wip

Appetite

No response

Execution issues

No response

Decision log

Date	Decision	Outcome

[Hedda]

For reference, direct links to still relevant community signals as directly related to extending scope for locks credential management:

• [FEATURE REQUEST] Lock user code manager (users and PIN-codes credential management) cross-platform/protocols with unified UI and centalized tracking/history which users locked/unlocked your locks

and

• Native lock code functionality home-assistant/architecture#1000

Zigbee support via ZHA is also asked for to expand this coherent approach for credential management across protocols and devices:

• [REQUEST] Add full Zigbee lock management with ability to manage users for locks and their PIN codes via ZHA to replicate the new Matter lock manager in Home Assistant? zigpy/zha#729

FYI, another "main" protocol for HA that has lock component support but have less common in real-world use-cases is ESPHome:

• https://esphome.io/components/lock/
  • https://esphome.io/components/lock/template/
    • https://esphome.io/components/lock/output/

Tip is that "Lock Code Manager" HACS custom component integration from @raman325 feature several additional basic functions:

• https://github.com/raman325/lock_code_manager

  Lock Code Manager is a Home Assistant integration that allows you to more easily manage your usercodes on your locks. Once you have configured it, the integration will set and clear codes on your locks as needed depending on how you decide to configure them.

  Features:

  • Synchronize multiple locks with a single set of codes
  • Optionally use a condition entity to control when a code is active. Supported entity types:
    • calendar - code is active when an event is in progress
    • binary_sensor - code is active when the sensor is on
    • switch - code is active when the switch is on
    • schedule - code is active when the schedule is on
    • input_boolean - code is active when the input boolean is on
  • Optionally define a maximum number of uses for a code before the code is disabled

Lock Code Manager currently support Z-Wave + virtual locks via the Virtual custom integration component (also available via HACS):

• https://github.com/twrecked/hass-virtual

  • https://github.com/raman325/lock_code_manager/wiki/Virtual-integration

    "The Virtual integration allows users to set up "virtual" entities of different types. One of those entity types is locks.

    The reason support for this integration was added is because it can be used to test Lock Code Manager functionality without affecting your main locks. Because Virtual locks don't have support for setting and clearing user codes, the way this works is that user codes are persisted to disk as you set them. If you remove a Virtual lock from your configuration, the file will be removed to keep your file system clean.

    If you are curious about Lock Code Manager and don't want to impact any existing locks functionality, I would encourage you to try setting up Lock Code Manager with Virtual locks first!

    The way Virtual locks integrate with LCM is not set in stone. If you have ideas on how to make support for these locks better, please open an issue."

PS: Lock Code Manager integration has in turn taken a lot of inspiration from the keymaster interation but taken it to the next level.

[AlCalzone]

For some context, here is an overview of the credential related functionality that exists in Z-Wave (and for the most part Matter too), but which is not included in this first iteration of the credential management in HA:

• Additional credential types:
  • RFID
  • NFC
  • UWB
  • several biometrics (eye, face, finger, ...)
  • MIFARE DESFIRE
  • Aliro (not in Z-Wave yet)
• Additional user types (in addition to the default/general user type and one-time users):
  • Programming / Admin user: Has one PIN that can be used to unlock an on-device configuration menu
  • Duress user: Can open the lock, but doing so sends an alarm to the central controller which is meant to alert emergency services
  • Expiring user: Users that are only active for a certain amount of time, and are disabled afterwards
  • Remote-only: Cannot use the keypad, only unlocks via RF commands
• Additional functionality:
  • Enabling/disabling users
  • Learning credentials on the device (e.g. fingerprints, key cards, etc.). This can take multiple steps (e.g. pressing the finger on the reader 5 times).
  • Re-assigning credentials to different users (mostly used for fingerprints that were learned with a temporary user, or re-assigning key cards).
  • Credential rules (Single/Dual/Triple): Can be used to require a user to provide multiple different credentials before a lock opens
  • Scheduling (not supported by zwave-js yet): Define certain days/timespans/etc. where specific users and all their credentials are active/inactive.
  • Making use of access control related notification events (invalid credentials used, etc...)
  • Allowing more than 1 credential per user. The foundation supports this, but we've limited the frontend functionality to 1 user = 1 PIN/password for this first iteration.

[Hedda]

I believe largest gap now for ZHA integration and Zigbee devices compared to other protocols might be locks and credential management?

• [REQUEST] Add full Zigbee lock management with ability to manage users for locks and their PIN codes via ZHA to replicate the new Matter lock manager in Home Assistant? zigpy/zha#729

  "Credential management for Zigbee locks via the ZHA integration"

@mkerstner could those be new additional seperate opportunities to lay foundation for unifying experience across all supported protocols?

• Further shape Zigbee support by implementing missing features in ZHA while retaining choice #93

  • Pre-work for enabling further shaping of Zigbee support #192

Initial support for both Matter and Z-Wave lock/credentials management has been implemented so think next opportunity would be Zigbee?

• Leverage a more consistent credential management approach goals#17

• Further shape our coherent device and protocol support goals#15

• Unify setup experience across all supported protocols goals#14

And after that it would be wonderful if you would consider broadening the scope to include unified lock/credentials management UI in HA?

• https://github.com/orgs/home-assistant/discussions/2555

  • Native lock code functionality home-assistant/architecture#1000

• https://community.home-assistant.io/t/lock-user-codes-management-unified-inc-users-pin-codes-for-code-locks-centalized-tracking-which-users-locked-unlocked-a-lock-and-when-how-was-locking-done-manual-from-inside-outside-keypad-integration-service-or-home-assistant-companion-etc/771302

[Hedda]

Links to additional related community signals new feature requests and more comments coming in on existing feature request discussions:

• https://github.com/orgs/home-assistant/discussions/4684

• https://github.com/orgs/home-assistant/discussions/551

• https://github.com/orgs/home-assistant/discussions/3964

• https://github.com/orgs/home-assistant/discussions/3701

• https://github.com/orgs/home-assistant/discussions/3742

• https://github.com/orgs/home-assistant/discussions/3515