microsoft.ad.domain_trust module – Manage Active Directory domain trusts

Note

This module is part of the microsoft.ad collection (version 1.11.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install microsoft.ad.

To use it in a playbook, specify: microsoft.ad.domain_trust.

New in microsoft.ad 1.11.0

Synopsis

• Create or remove Active Directory domain trust relationships between forests or domains.

• Supports Forest and External trust types with configurable direction and selective authentication.

• Before creating a trust the module verifies that the target domain name resolves via DNS. This catches missing conditional forwarders early and avoids cryptic trust-creation errors.

Parameters

Parameter	Comments
direction string	The direction of the trust relationship. inbound allows users in the target domain to authenticate in the local domain. outbound allows users in the local domain to authenticate in the target domain. bidirectional allows authentication in both directions. Required when state=present and the trust does not yet exist. Cannot be changed on an existing trust; remove and recreate the trust to change direction. Choices: "inbound" "outbound" "bidirectional"
domain_server string	The FQDN of the domain controller to target for all AD operations. When not specified the module uses default domain controller discovery.
name string / required	The fully qualified domain name (FQDN) of the target domain to trust (e.g. example.com). This is the primary key used to identify the trust.
selective_authentication boolean	Whether selective authentication is enabled on the trust. When true, users in the trusted domain are not automatically authenticated. Permissions must be granted explicitly on each resource. This is the only property that can be updated on an existing trust without removing it first. Choices: false true
state string	Whether the trust should be present or absent. Choices: "present" ← (default) "absent"
trust_password string	The shared secret used to establish the trust. Both sides of the trust must use the same password. Required when state=present and the trust does not yet exist.
type string	The type of trust relationship to create. forest creates a transitive trust between two AD forests. external creates a non-transitive trust between two domains that may be in different forests. Required when state=present and the trust does not yet exist. Cannot be changed on an existing trust; remove and recreate the trust to change type. Choices: "external" "forest"

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: windows	Target OS/families that can be operated against

Notes

Note

• This module must be run on a Windows domain controller.

• The ActiveDirectory PowerShell module must be available on the target (present on domain controllers by default).

• Domain Administrator or Enterprise Administrator permissions are typically required to create or remove trusts.

• DNS conditional forwarders for the target domain must be configured before creating a trust. The module will verify DNS resolution and fail early if the target domain cannot be resolved.

• Trust creation and removal use the System.DirectoryServices.ActiveDirectory .NET classes. The current trust state is read via Get-ADTrust.

• The module creates only the local side of the trust using a shared password. Run the module on both domain controllers with the same trust_password to establish a working trust.

• The direction and type of an existing trust cannot be changed in-place. The module will fail with a descriptive message if the requested values differ from the current trust. Remove the trust first and recreate it with the desired settings.

See Also

See also

microsoft.ad.domain

Ensures the existence of a Windows domain.

microsoft.ad.domain_child

Manage domain children in an existing Active Directory forest.

Forest.CreateLocalSideOfTrustRelationship

.NET API used to create the local side of forest trusts.

Examples

- name: Create a bidirectional forest trust
  microsoft.ad.domain_trust:
    name: example.com
    direction: bidirectional
    type: forest
    trust_password: S3cretTru5t!
    state: present

- name: Create a one-way outbound external trust
  microsoft.ad.domain_trust:
    name: partner.example.com
    direction: outbound
    type: external
    trust_password: Tr0stP@ss
    state: present

- name: Create a forest trust with selective authentication
  microsoft.ad.domain_trust:
    name: example.com
    direction: bidirectional
    type: forest
    trust_password: S3cretTru5t!
    selective_authentication: true
    state: present

- name: Enable selective authentication on an existing trust
  microsoft.ad.domain_trust:
    name: example.com
    direction: bidirectional
    type: forest
    trust_password: S3cretTru5t!
    selective_authentication: true
    state: present

- name: Remove a domain trust
  microsoft.ad.domain_trust:
    name: example.com
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
distinguished_name string	The distinguished name of the trusted domain object in AD. Returned: success and trust exists Sample: "CN=example.com,CN=System,DC=contoso,DC=com"

Authors

• Ron Gershburg (@rgershbu)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication