Direct AD Integration role

An ansible role which configures direct Active Directory integration.

Supported Distributions

• RHEL7+, CentOS7+
• Fedora
• SLES 16, openSUSE Leap 16

Requirements

In order to join to the domain, you must use an Active Directory user which has sufficient join permissions. It is not recommended to use the Administrator user as the security footprint of this user is too large.

See Delegated Permissions for the explicit permissions a user must have.

Time must be in sync with Active Directory servers. The ad_integration role will use the timesync system role for this if the user specifies ad_integration_manage_timesync to true and provides a value for ad_integration_timesync_source to use as a timesource.

RHEL8 (and newer) and Fedora no longer support RC4 encryption out of the box, it is recommended to enable AES in Active Directory, if not possible then the AD-SUPPORT crypto policy must be enabled. The integration role will use the crypto_policies system role for this if the user sets the ad_integration_manage_crypto_policies and ad_integration_allow_rc4_crypto parameters to true.

The Linux system must be able to resolve default AD DNS SRV records.

The following firewall ports must be opened on the AD server side, reachable 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 change/set password (kadmin)
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

This role requires additional modules from external collections. Please use the following command to install them:

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

Role Variables

Required variables

ad_integration_realm

Active Directory realm, or domain name to join

NOTE If using this role to manage realm/domain specific settings in SSSD using (ad_dyndns_update or ad_integration_sssd_custom_settings, older versions of the role would make the realm name lower case in the domain section name. For example, if you had specified ad_integration_realm: EXAMPLE.COM, then the sssd.conf section would have been [domain/example.com]. The role now will instead use a case-insensitive match to look for an existing section in sssd.conf, which should already exist.

The result of this is that you may have multiple sections for the domain in your sssd.conf. If you want to consolidate these sections into one, use ad_integration_sssd_merge_duplicate_sections: true. See below for more information about [ad_integration_sssd_merge_duplicate_sections(#ad_integration_sssd_merge_duplicate_sections).

ad_integration_password

The password of the user used to authenticate with when joining the machine to the realm. Do not use cleartext - use Ansible Vault to encrypt the value.

Optional variables

ad_integration_user

The user name to be used to authenticate with when joining the machine to the realm.

Default: Administrator

ad_integration_join_to_dc

an Active Directory domain controller's hostname (do not use IP address) may be specified to join via that domain controller directly.

Default: Not set

ad_integration_force_rejoin

Leave existing domain prior to performing join. This might be needed if the keytab is unable to authenticate with the machine account to the AD domain.

The role leaves only ad_integration_realm, including on hosts configured for more than one realm.

Default: false

ad_integration_state

Set to present to join or configure ad_integration_realm, or absent to leave that realm. An absent realm needs no leave action. With ad_integration_manage_packages: true, the role installs the AD prerequisites and starts realmd before either joining or leaving. Leaving skips join-only network, time, crypto policy, and SSSD configuration tasks. Local leave retains the remote computer account by default.

Default: present

- name: Leave one AD realm locally
  include_role:
    name: linux-system-roles.ad_integration
  vars:
    ad_integration_realm: example.com
    ad_integration_state: absent

ad_integration_leave_remove_computer

When ad_integration_state: absent, set this to true to ask realm leave to remove or disable the selected realm's computer account in Active Directory. A configured realm requires ad_integration_user and ad_integration_password; provide the password through Ansible Vault. The role passes it on standard input and suppresses task output when ad_integration_secure_logging is enabled. The role does not attempt remote removal when the host is already unjoined.

Default: false

- name: Leave a realm and remove its AD computer account
  include_role:
    name: linux-system-roles.ad_integration
  vars:
    ad_integration_realm: example.com
    ad_integration_state: absent
    ad_integration_leave_remove_computer: true
    ad_integration_user: Administrator
    ad_integration_password: "{{ vaulted_ad_password }}"

ad_integration_leave_reset_computer

When ad_integration_state: absent, set this to true to run adcli reset-computer before local unconfiguration. This keeps the AD account but resets its password. Provide ad_integration_user and ad_integration_password; the role passes the password on standard input. This cannot be combined with ad_integration_leave_remove_computer. adcli must already be installed on the host.

Default: false

- name: Reset the AD computer account, then leave the realm
  include_role:
    name: linux-system-roles.ad_integration
  vars:
    ad_integration_realm: example.com
    ad_integration_state: absent
    ad_integration_leave_reset_computer: true
    ad_integration_leave_computer_name: client.example.com
    ad_integration_user: Administrator
    ad_integration_password: "{{ vaulted_ad_password }}"

ad_integration_leave_computer_name

The computer name passed to adcli reset-computer. By default, the role uses the host's FQDN. Set this when the AD computer account uses a different name.

Default: null

ad_integration_leave_sssd_cache_delete

When ad_integration_state: absent, set this to true to delete the selected realm's cache_<realm>.ldb and timestamps_<realm>.ldb SSSD files. The role briefly stops SSSD if it is running and restores its prior running state. Other realms' cache files, shared SSSD databases, and /etc/krb5.keytab are left alone. Cache deletion is skipped for the winbind client. In check mode, the role reports pending deletion without removing files.

Default: false

- name: Leave a realm and delete its SSSD cache files
  include_role:
    name: linux-system-roles.ad_integration
  vars:
    ad_integration_realm: example.com
    ad_integration_state: absent
    ad_integration_leave_sssd_cache_delete: true

ad_integration_auto_id_mapping

perform automatic UID/GID mapping for users and groups, set to false to rely on POSIX attributes already present in Active Directory.

Default: true

ad_integration_client_software

Only join realms for which we can use the given client software. Possible values include sssd or winbind. Not all values are supported for all realms.

Default: Automatic selection

ad_integration_membership_software

The software to use when joining to the realm. Possible values include samba or adcli. Not all values are supported for all realms.

Default: Automatic selection

ad_integration_computer_ou

The distinguished name of an organizational unit to create the computer account. It can be relative to the Root DSE, or a complete LDAP DN.

Default: Default AD computer container

ad_integration_manage_timesync

If true, the ad_integration role will use fedora.linux_system_roles.timesync. Requires providing a value for ad_integration_timesync_source to use as a time source.

Default: false

ad_integration_timesync_source

Hostname or IP address of time source to synchronize the system clock with. Providing this variable automatically sets ad_integration_manage_timesync to true.

ad_integration_manage_crypto_policies

If true, the ad_integration role will use fedora.linux_system_roles.crypto_policies as needed. This applies only to Fedora and RHEL8 (and newer), including CentOS, AlmaLinux and Rocky Linux; on other distributions the variable is ignored.

Default: false

ad_integration_allow_rc4_crypto

If true, the ad_integration role will set the crypto policy allowing RC4 encryption. Providing this variable automatically sets ad_integration_manage_crypto_policies to true. Like that variable, it applies only to Fedora and RHEL8 (and newer), including CentOS, AlmaLinux and Rocky Linux, and is ignored elsewhere.

Default: false

NOTE: This may reboot the machine in order to apply the crypto policy, which is needed for the subsequent realm join.

ad_integration_manage_dns

If true, the ad_integration role will use fedora.linux_system_roles.network to add the provided dns server (see below) with manual DNS configuration to an existing connection. If true then the following variables are required:

• ad_integration_dns_server - DNS server to add
• ad_integration_dns_connection_name - Existing network connection name to configure
• ad_integration_dns_connection_type - Existing network connection type to configure

ad_integration_dns_server

IP address of DNS server to add to existing networking configuration. Only applicable if ad_integration_manage_dns is true

ad_integration_dns_connection_name

The name option identifies the connection profile to be configured by the network role. It is not the name of the networking interface for which the profile applies. Only applicable if ad_integration_manage_dns is true

ad_integration_dns_connection_type

Network connection type such as ethernet, bridge, bond...etc, the network role contains a list of possible values. Only applicable if ad_integration_manage_dns is true

ad_dyndns_update

If true, SSSD is configured to automatically update the AD DNS server with the IP address of the client.

NOTE: See the ad_integration_realm, and ad_integration_sssd_merge_duplicate_sections for information about how the role writes these settings to the sssd.conf file.

Default: false

ad_dyndns_ttl

Optional. The TTL, in seconds, to apply to the client's DNS record when updating it. Only applicable if ad_dyndns_update is true

Note: This will override the TTL set by an administrator on the server.

Default: 3600

ad_dyndns_iface

Optional. Interface or a list of interfaces whose IP addresses should be used for dynamic DNS updates. Special value "*" implies all IPs from all interfaces should be used. Only applicable if ad_dyndns_update is true

Default: Use the IP addresses of the interface which is used for AD LDAP connection

ad_dyndns_refresh_interval

Optional. How often should, in seconds, periodic DNS updates be performed in addition to when the back end goes online. Only applicable if ad_dyndns_update is true

Note: lowest possible value is 60 seconds. If value less than 60 is specified sssd will assume lowest value only.

Default: 86400

ad_dyndns_update_ptr

Optional. If true, the PTR record should also be explicitly updated. Only applicable if ad_dyndns_update is true

Default: true

ad_dyndns_force_tcp

Optional. If true, the nsupdate utility should default to using TCP for communicating with the DNS server. Only applicable if ad_dyndns_update is true

Default: false

ad_dyndns_auth

Optional. If true, GSS-TSIG authentication will be used for secure updates with the DNS server when updating A and AAAA records. Only applicable if ad_dyndns_update is true

Default: true

ad_dyndns_server

Optional. DNS server to use when performing a DNS update when autodetection settings fail. Only applicable if ad_dyndns_update is true

Default: None (let nsupdate choose the server)

ad_integration_join_parameters

Additional parameters (as a string) supplied directly to the realm join command. Useful if some specific configuration like --user-principal=host/name@REALM or --use-ldaps is needed. See man realm for details. Example: ad_integration_join_parameters: "--user-principal host/client007@EXAMPLE.COM"

ad_integration_sssd_settings

A list of setting to be included into the [sssd] section of the sssd.conf file. See sssd.conf man pages for details. Example:

ad_integration_sssd_settings:
  - key: "configuration_name"
    value: "configuration_value"

ad_integration_sssd_custom_settings

A list of custom setting to be included into the [domain/$REALM] section of the sssd.conf file. See sssd.conf man pages for details. Example:

ad_integration_sssd_custom_settings:
  - key: "configuration_name"
    value: "configuration_value"

NOTE: See the ad_integration_realm and ad_integration_sssd_merge_duplicate_sections for information about how the role writes these settings to the sssd.conf file.

ad_integration_sssd_section_settings

Manage options in any sssd.conf section, including [nss] and [pam]. Each list item needs section and key. Set value to a string or integer when adding an option. Set state: absent to remove an option; value is then optional. Sections and options not named in the list are preserved. The list is applied in order after ad_integration_sssd_settings, dynamic DNS settings, and ad_integration_sssd_custom_settings, so its last entry wins if multiple entries target the same option. Use domain/{{ ad_integration_realm }} for the joined domain; the role follows the same case matching rules as ad_integration_sssd_custom_settings, but prefers an exact existing section name when more than one capitalization is present.

ad_integration_sssd_section_settings:
  - section: nss
    key: filter_users
    value: root
  - section: pam
    key: offline_credentials_expiration
    value: 3
  - section: pam
    key: pam_verbosity
    state: absent

Values for timeouts, caching, and identity behavior depend on the deployment; the role does not set new defaults for these sections.

ad_integration_validate_sssd_config

This is a boolean, default is true. If true and ad_integration_client_software is sssd, run sssctl config-check after configuration changes and immediately before any role-triggered SSSD restart. An invalid configuration fails the role and prevents that restart, including when forced handlers are enabled. Validation does not roll back configuration changes and does not report a change itself. It also runs when no settings changed, but is skipped in Ansible check mode.

The role installs sssd-tools when validation is enabled and ad_integration_manage_packages is true. Otherwise, install sssd-tools before running the role. Validation fails if sssctl is unavailable.

To disable validation when invoking the role:

- name: Join AD without SSSD configuration validation
  include_role:
    name: linux-system-roles.ad_integration
  vars:
    ad_integration_validate_sssd_config: false

ad_integration_preserve_authselect_profile

This is a boolean, default is false. If true, configure realmd.conf to remove the authselect command from sssd-enable-logins to avoid overwriting previous PAM/nsswitch changes, until RHEL-5101 is addressed.

ad_integration_manage_packages

By default, the role installs OS‐level packages needed for Active Directory integration, including when leaving a realm. It also starts realmd before leaving. If false, the role assumes the prerequisites are already available and skips package installation; the leave path does not start realmd.

Default: true

ad_integration_sssd_merge_duplicate_sections

NOTE WELL: This will do a force rejoin as this is the only way to clean up sssd.conf and ensure all of the settings are applied correctly after merging.

This is a boolean, default is false. Because the domain/realm section in sssd.conf is case insensitive, and you have previously used the role to manage domain/realm settings in sssd.conf, there may be multiple sections matching the domain/realm. If you want to consolidate these sections into one, use ad_integration_sssd_merge_duplicate_sections: true. For example, if you have a sssd.conf with both [domain/example.com] and [domain/EXAMPLE.COM], and you want to use only the latter, then use:

ad_integration_realm: EXAMPLE.COM
ad_integration_sssd_merge_duplicate_sections: true
ad_integration_sssd_custom_settings: somesettings

All of the settings from [domain/example.com] will be moved to [domain/EXAMPLE.COM], and the section [domain/example.com] will be removed from sssd.conf.

ad_integration_secure_logging

If true, suppress potentially sensitive output from tasks that handle credentials, secrets, and other sensitive data by setting no_log: true on those tasks. This prevents passwords, API tokens, private keys, and similar sensitive information from appearing in Ansible logs and console output.

If you need to debug issues with credential handling or secret management, you can temporarily set ad_integration_secure_logging: false to see the full output from these tasks. However, be aware that this may expose sensitive information in logs, so it should only be used in development or troubleshooting scenarios.

Default: true

ad_integration_transactional_update_reboot_ok

This variable is used to handle reboots required by transactional updates. If a transactional update requires a reboot, the role will proceed with the reboot if ad_integration_transactional_update_reboot_ok is set to true. If set to false, the role will notify the user that a reboot is required, allowing for custom handling of the reboot requirement. If this variable is not set, the role will fail to ensure the reboot requirement is not overlooked. For non-transactional update systems, this variable is ignored.

Default: null

Example Playbook

The following is an example playbook to setup direct Active Directory integration with AD domain domain.example.com, the join will be performed with user Administrator using the vault stored password. Prior to the join, the crypto policy for AD SUPPORT with RC4 encryption allowed will be set.

- 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

rpm-ostree

See README-ostree.md

License

MIT.

Author Information

Justin Stephenson (jstephen@redhat.com)