yumenohikari/README.md

## README.md

      
    Raw
  

              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)
	#!/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)