linux-system-roles.ad_integration

Direct AD Integration Role

This Ansible role helps configure direct integration with Active Directory.

Supported Distributions

RHEL7+, CentOS7+
Fedora

Requirements

To join the domain, you'll need an Active Directory user with permission to do so. It's best not to use the Administrator account due to security reasons.

For detailed permissions needed, check Delegated Permissions.

Make sure your system time is synchronized with the Active Directory servers. If you set ad_integration_manage_timesync to true and provide a value for ad_integration_timesync_source, the role will handle time syncing for you.

Note: RHEL8 and newer versions do not support RC4 encryption by default. If you can't enable AES in Active Directory, you must enable the AD-SUPPORT crypto policy. This role can manage crypto policies if you set the parameters ad_integration_manage_crypto_policies and ad_integration_allow_rc4_crypto to true.

Your Linux system also needs to be able to resolve default AD DNS SRV records.

The following firewall ports must be open on the AD server, accessible from the Linux client:

Source Port	Destination	Protocol	Service
1024:65535	53	TCP and UDP	DNS
1024:65535	389	TCP and UDP	LDAP
1024:65535	636	TCP	LDAPS
1024:65535	88	TCP and UDP	Kerberos
1024:65535	464	TCP and UDP	Kerberos password
1024:65535	3268	TCP	LDAP Global Catalog
1024:65535	3269	TCP	LDAP Global Catalog SSL
1024:65535	123	UDP	NTP/Chrony (optional)
1024:65535	323	UDP	NTP/Chrony (optional)

Collection Requirements

You'll need additional modules from external collections. Install them using:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Role Variables

Required Variables

ad_integration_realm

The Active Directory realm or domain name to join.

ad_integration_password

The password for the user joining the machine to the realm. Always use Ansible Vault to encrypt this value.

Optional Variables

ad_integration_user

The username for authentication when joining the machine. Default is Administrator.

ad_integration_join_to_dc

Specify the hostname of an Active Directory domain controller (not IP address) to join through that controller.

Default: Not set

ad_integration_force_rejoin

Leave the existing domain before joining again, useful if the keytab cannot authenticate with the machine account.

Default: false

ad_integration_auto_id_mapping

Automatically map UID/GID for users and groups. Set to false to rely on existing POSIX attributes in Active Directory.

Default: true

ad_integration_client_software

Specify client software to use when joining realms, choices are sssd or winbind. Not all are supported for every realm.

Default: Automatic selection

ad_integration_membership_software

Software to utilize when joining the realm; options include samba or adcli. Not all work for every realm.

Default: Automatic selection

ad_integration_computer_ou

Organizational unit where the computer account will be created, can be a relative or full LDAP DN.

Default: Default AD computer container

ad_integration_manage_timesync

If true, will use timesync management. Requires ad_integration_timesync_source for the time source.

Default: false

ad_integration_timesync_source

Hostname or IP for synchronizing the system clock. Setting this will automatically make ad_integration_manage_timesync true.

ad_integration_manage_crypto_policies

If true, will manage crypto policies as needed.

Default: false

ad_integration_allow_rc4_crypto

If true, will allow RC4 encryption. Automatically sets ad_integration_manage_crypto_policies to true.

Default: false

ad_integration_manage_dns

If true, will manage DNS settings. Requires additional variables set for DNS configuration.

ad_integration_dns_server

The IP of the DNS server to add during management.

ad_integration_dns_connection_name

Specify which network connection profile to configure for DNS.

ad_integration_dns_connection_type

Type of the existing network connection to configure (like ethernet or bridge).

ad_dyndns_update

If true, will automatically update the AD DNS server with the client’s IP address.

Default: false

ad_dyndns_ttl

Optional. Time-to-Live in seconds for the client’s DNS record when updating. Overrides server settings.

Default: 3600

ad_dyndns_iface

Optional. Which interface's IPs to use for updates. Use "*" for all interfaces.

Default: Uses the IP of the interface for the AD LDAP connection.

ad_dyndns_refresh_interval

Optional. How often to perform periodic DNS updates.

Default: 86400

ad_dyndns_update_ptr

If true, will also update the PTR record.

Default: true

ad_dyndns_force_tcp

If true, uses TCP for communicating with the DNS server during updates.

Default: false

ad_dyndns_auth

If true, uses GSS-TSIG for secure updates with the DNS server.

Default: true

ad_dyndns_server

Optional. The DNS server to use for updates when auto-detection fails.

Default: None

ad_integration_join_parameters

Additional parameters to use directly with the realm join command.

ad_integration_sssd_settings

Settings to include in the [sssd] section of the sssd.conf file.

ad_integration_sssd_custom_settings

Custom settings for the [domain/$REALM] section of the sssd.conf file.

ad_integration_preserve_authselect_profile

Boolean to avoid overwriting PAM/nsswitch changes. Default is false.

Example Playbook

This example joins the AD domain domain.example.com as Administrator with a vault-stored password, also setting the crypto policy for AD SUPPORT with RC4 encryption allowed.

- hosts: all
  vars:
    ad_integration_realm: "domain.example.com"
    ad_integration_password: !vault | …vault encrypted password…
    ad_integration_manage_crypto_policies: true
    ad_integration_allow_rc4_crypto: true
  roles:
    - linux-system-roles.ad_integration