Discovering a Domain
The library supports discovering LDAP and Kerberos servers within a domain using special DNS entries defined for Active Directory.
Smart Defaults
By default, it will use the system DNS configuration, find LDAP servers that support TLS, and sort LDAP and Kerberos servers by the RTT to communicate with them.
Here’s an example of creating a simple configuration and working with server discovery.
from ms_active_directory import ADDomain
example_domain_dns_name = 'example.com'
domain = ADDomain(example_domain_dns_name)
ldap_servers = domain.get_ldap_uris()
kerberos_servers = domain.get_kerberos_uris()
# re-discover servers in dns and sort them by RTT again at a later time to pick up changes
domain.refresh_ldap_server_discovery()
domain.refresh_kerberos_server_discovery()
Site Awareness and Flexible DNS
The library also supports site awareness, which will result in only discovering servers within a specified Active Directory Site. You can also specify alternative DNS nameservers to use instead of the system ones.
Here’s an example of specifying an AD site and alternative DNS server.
from ms_active_directory import ADDomain
example_domain_dns_name = 'example.com'
site_name = 'us-eastern-datacenter'
domain = ADDomain(example_domain_dns_name, site=site_name,
dns_nameservers=['eastern-private-dns-01.local'])
Network Multi-Tenancy and Security Support
You can also specify exactly which LDAP or Kerberos servers should be used, and skip discovery. Additional configurations are available such as configuring the CA file path to use for trust, and the source IP to use for outbound traffic to the domain, which is helpful when there are firewall rules in place, or when a machine has both private and public IP addresses.
Here’s an example of specifying which servers to communicate with, and CA certs to secure that communication.
from ms_active_directory import ADDomain
example_domain_dns_name = 'example.com'
local_machine_ip = '10.251.12.1'
local_ldap_ip = '10.251.12.30'
public_machine_ip = '194.32.21.30'
# the servers that live on the public internet use well-known public
# CAs for trust, but we have a local CA for the private network servers
private_securing_cas = '/etc/internal-ca.cert'
# set up an object for the local domain in the same network as this machine,
# but also have an instance that can be used to make instances to reach out
# to the rest of the domain outside of the local private network
local_domain = ADDomain(example_domain_dns_name, ldap_servers_or_uris=[local_ldap_ip],
source_ip=local_ldap_ip, ca_certificates_file_path=private_securing_cas)
global_domain = ADDomain(example_domain_dns_name, source_ip=public_machine_ip)
Local System Configuration
By default, you’ll need to configure your local system files to enable kerberos authentication to work properly. However, you can also automatically set up the krb5 configuration when creating a domain object.
from ms_active_directory import ADDomain
example_domain_dns_name = 'example.com'
# set up the local system krb5 config based on discovered kerberos uris
domain = ADDomain(example_domain_dns_name,
auto_configure_kerberos_client=True)
The file configured will be /etc/krb5.conf
on posix systems (e.g. macOS, Ubuntu), and on windows both
/winnt/krb5.ini
and /windows/krb5.ini
will be configured for backwards compatibility.
By default, a new kerberos realm configuration will be merged into these files if they exist, or new files
will be created if none exists.
If you want to update a different configuration file, or if you want to overwrite the file instead of updating it, or if you want to set things like a default realm, you can also directly call the function for configuring the local system.
from ms_active_directory.environment.kerberos.kerberos_client_configurer import update_system_kerberos_configuration_for_domains
from ms_active_directory import ADDomain
example_domain_dns_name = 'example.com'
domain = ADDomain(example_domain_dns_name)
# overwrite the existing file instead of updating it
update_system_kerberos_configuration_for_domains([domain], merge_with_existing_file=False)
# update a file in a different location
update_system_kerberos_configuration_for_domains([domain], krb5_location='/etc/user_100/krb5.conf')
# set a default authentication realm
update_system_kerberos_configuration_for_domains([domain], default_domain=domain)
Note: if multiple ADDomain
objects all attempt to configure the local system kerberos file, only one will “win”.
This means that if they have different sites specified, or used different source addresses on a network where
kdc reachability is reliant on that source address, having a single ADDomain
object automatically configure
the krb5 configuration file can be risky.
In these scenarios, it’s recommended that you manually write the krb5 configuration or that you set up an ADDomain
object with kerberos uris for the entire domain and use that to initiate the auto-configuration.