Active Directory LDAP auth for Home Assistant

README.md

Active Directory LDAP auth for Home Assistant

This script allows users to log in to Home Assistant using their sAMAccountName or userPrincipalName identifiers without any special requirements for the ldapsearch or curl utilities. Instead, it requires the ldap3 Python module, but there are ways to install that locally so it can even be used in supervised / Home Assistant OS installs.

Editing for use in your installation

Obviously most of the configuration values in the script need to be edited to work in your environment.

• SERVER - the DNS name of your AD domain, or the name or IP of a specific domain controller.
• HELPERDN - the DN (distinguishedName attribute) of the service account you're using to search LDAP for the desired user.
• HELPERPASS - the password for that service account.
• TIMEOUT - LDAP search timeout in seconds.
• FILTER - LDAP search filter to find the desired user. To match by SAM name or UPN and a group membership, just edit the memberOf line to include the DN of the group you want to use to control access.
• BASEDN - the DN of the top-most container to search. To search the entire domain, use just the "DC" sections at the end of your domain's DNs, e.g. DC=ad,DC=example,DC=com. As written, the script searches recursively.

Authentication configuration

In a Home Assistant Core installation, you can install the Python module using pip or your package manager, then put the script in any directory where Home Assistant can reach it. Then add a section to configuration.yaml:

homeassistant:
    auth_providers:
        - type: command_line
          command: /usr/local/bin/ldap-auth-ad.py
          meta: true
        - type: homeassistant

Note that homeassistant must be explicitly specified as an authentication method, or you won't have access to locally-created users.

Installing in a Docker-based installation

Because Python modules can be installed in and loaded from the current path, it's possible to make this work in Docker containers as well, by hiding it in the /config directory.

First, make a directory to contain everything, and copy the configured script into the host directory that's mounted as /config:

me@host:~ $ sudo mkdir /usr/share/hassio/homeassistant/ldap-auth
me@host:~ $ sudo cp ldap-auth-ad.py /usr/share/hassio/homeassistant/ldap-auth

Next, open a shell in the Home Assistant core container, and change to the directory we just created:

me@host:~ $ sudo docker exec -it homeassistant bash
bash-5.0# cd /config/ldap-auth

Install the module:

bash-5.0# pip install -t . ldap3

And insert the configuration section (note the modified path):

homeassistant:
    auth_providers:
        - type: command_line
          command: /config/ldap-auth/ldap-auth-ad.py
          meta: true
        - type: homeassistant

Finally, restart the entire application (Configuration > Server Controls > Server Management > Restart) to reload the config. (It may be possible to reload without doing this, but I'm not entirely clear on when configuration.yaml is read.)

You should now be able to log in as any user that's a member of the group you picked above. Home Assistant will create a new user in the local database the first time a user logs in.

Credits

This whole thing is hacked out of a more generic LDAP script by Rechner Fox. I mostly tweaked the filters and added the username search.

ldap-auth-ad.py

#!/usr/bin/env python
# ldap-auth-ad.py - authenticate Home Assistant against AD via LDAP
# Based on Rechner Fox's ldap-auth.py
# Original found at https://gist.github.com/rechner/57c123d243b8adb83ccb1dc94c80847f

import os
import sys
from ldap3 import Server, Connection, ALL
from ldap3.utils.conv import escape_bytes, escape_filter_chars

# Quick and dirty print to stderr
def eprint(*args, **kwargs):
    print(*args, file=sys.stderr, **kwargs)

# XXX: Update these with settings apropriate to your environment:
# (mine below are based on Active Directory and a security group)
SERVER = "ad.example.com"

# We need to search by SAM/UPN to find the DN, so we use a helper account
# This account should be unprivileged and blocked from interactive logon
HELPERDN = "CN=LDAP Helper,OU=Service Accounts,OU=Accounts,DC=ad,DC=example,DC=com"
HELPERPASS = "sEcUrEpAsSwOrD"

TIMEOUT = 3
BASEDN = "DC=ad,DC=example,DC=com"
FILTER = """
    (&
        (objectClass=person)
        (|
            (sAMAccountName={})
            (userPrincipalName={})
        )
        (memberOf=CN=Home Assistant,OU=Security Groups,OU=Accounts,DC=ad,DC=example,DC=com)
    )"""
ATTRS = ""

## End config section

if 'username' not in os.environ or 'password' not in os.environ:
    eprint("Need username and password environment variables!")
    exit(1)

safe_username = escape_filter_chars(os.environ['username'])
FILTER = FILTER.format(safe_username, safe_username)

server = Server(SERVER, get_info=ALL)
try:
    conn = Connection(server, HELPERDN, password=HELPERPASS, auto_bind=True, raise_exceptions=True)
except Exception as e:
    eprint("initial bind failed: {}".format(e))
    exit(1)

search = conn.search(BASEDN, FILTER, attributes='displayName')
if len(conn.entries) > 0: # search is True on success regardless of result size
    eprint("search success: username {}, result {}".format(os.environ['username'], conn.entries))
    user_dn = conn.entries[0].entry_dn
    user_displayName = conn.entries[0].displayName
else:
    eprint("search for username {} yielded empty result".format(os.environ['username']))
    exit(1)

try:
    conn.rebind(user=user_dn, password=os.environ['password'])
except Exception as e:
    eprint("bind as {} failed: {}".format(os.environ['username'], e))
    exit(1)

print("name = {}".format(user_displayName))

eprint("{} authenticated successfully".format(os.environ['username']))
exit(0)

@darootler sorry to jump into this conversation months later but does that work for setting users to users and administrator roles now? How does the custom group for doorlock users work?

Also I was trying to reorganize my AD the other day and my new standard group naming format has a space in it. Maybe not a smart design choice. But when I replace "hassusers" in the ldap.py with "Home Assistant Users" which is the new group it breaks. Is there a way I need to escape the space character or something?

Hi!

Let me explain the py code snippets a bit:

• This part defines all members of the AD groups who are able to login with AD creds. Only those members are allowed:

FILTER = """
    (&
        (objectClass=person)
        (|
            (sAMAccountName={})
            (userPrincipalName={})
        )
        (|(memberOf=CN=homeassistant_admins,OU=myou,DC=mydomain,DC=corp)(memberOf=CN=homeassistant_doorlockusers,OU=myou,DC=mydomain,DC=corp)(memberOf=CN=homeassistant_admins,OU=myou,DC=mydomain,DC=corp))
    )"""
ATTRS = ""

• This part maps the AD groups to the existing HA groups:

if "CN=homeassistant_admins,OU=myou,DC=mydomain,DC=corp" in user_memberof:
    print("name = {}".format(user_displayName),"group = system-admin",sep=os.linesep)

if "CN=homeassistant_doorlockusers,OU=myou,DC=mydomain,DC=corp" in user_memberof:
    print("name = {}".format(user_displayName),"group = custom-doorlock-users",sep=os.linesep)

if "CN=homeassistant_users,OU=myou,DC=mydomain,DC=corp" in user_memberof:
    print("name = {}".format(user_displayName),"group = system-users",sep=os.linesep)

You can view all available HA groups in the file "/homeassistant/.storage/auth". As per default there are two HA groups, "system-admin" and "system-users".

The custom groups aren't really implemented to work with the HA GUI. I created the group by myself using this documentation --> https://developers.home-assistant.io/blog/2019/03/11/user-permissions?_highlight=group#what-about-custom-groups

I hope that helps.

Regards
Richard