microsoft.ad.fs_trust module – Manage AD FS Relying Party 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.fs_trust.

New in microsoft.ad 1.11.0

Synopsis

• Create, update, or remove AD FS Relying Party Trusts on a Windows server running the AD FS role.

• Trusts can be created from a federation metadata URL, a local metadata XML file, or by specifying identifiers and endpoints manually.

Parameters

Parameter	Comments
access_control_policy_name string	Name of the access control policy to assign.
auto_update_enabled boolean	Whether changes in the federation metadata are automatically applied to the trust configuration. Choices: false true
enabled boolean	Whether the relying party trust is enabled. Choices: false true
encrypt_claims boolean	Whether claims sent to the relying party should be encrypted. Choices: false true
identifier list / elements=string	List of unique identifiers (URIs) for the relying party trust. Used for manual trust setup without a metadata document. Mutually exclusive with metadata_url and metadata_file.
metadata_file string	Local file path to a federation metadata XML document. Mutually exclusive with metadata_url and identifier.
metadata_url string	URL pointing to the federation metadata document for the relying party. The module tests connectivity to this URL before creating the trust. Mutually exclusive with metadata_file and identifier.
monitoring_enabled boolean	Whether periodic monitoring of the relying party federation metadata is enabled. Requires that the trust was created with metadata_url. Choices: false true
name string / required	The display name of the relying party trust. This is the primary key used to identify the trust.
notes string	Freeform notes for the relying party trust.
saml_endpoint list / elements=string	List of SAML Assertion Consumer Service endpoint URLs. Only used when creating a trust with identifier for manual setup. Each URL is registered as a SAML POST binding endpoint.
signature_algorithm string	Signature algorithm used for signing and verification. rsa_sha1 uses RSA-SHA1 (http://www.w3.org/2000/09/xmldsig#rsa-sha1). rsa_sha256 uses RSA-SHA256 (http://www.w3.org/2001/04/xmldsig-more#rsa-sha256). Choices: "rsa_sha1" "rsa_sha256"
state string	Whether the relying party trust should be present or absent. Choices: "present" ← (default) "absent"
token_lifetime integer	Token validity duration in minutes.
wsfed_endpoint string	WS-Federation passive endpoint URL for the relying party. Only used when creating a trust with identifier for manual setup.

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: none	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 server with the AD FS role installed.

• The AD FS PowerShell module (ADFS) must be available on the target.

• Requires AD FS administrator permissions.

• Supports AD FS on Windows Server 2019 and later.

See Also

See also

Add-AdfsRelyingPartyTrust

Microsoft documentation for the underlying cmdlet.

Examples

- name: Create a relying party trust from a metadata URL
  microsoft.ad.fs_trust:
    name: MyApp
    metadata_url: https://app.example.com/federationmetadata/2007-06/federationmetadata.xml
    monitoring_enabled: true
    auto_update_enabled: true

- name: Create a relying party trust from a local metadata file
  microsoft.ad.fs_trust:
    name: InternalApp
    metadata_file: C:\metadata\internal_app.xml
    enabled: true

- name: Create a trust with manual identifiers and SAML endpoint
  microsoft.ad.fs_trust:
    name: CustomSaaS
    identifier:
      - https://app.example.com/saml
    saml_endpoint:
      - https://app.example.com/saml/acs
    enabled: true
    token_lifetime: 60

- name: Create a trust with a WS-Federation endpoint
  microsoft.ad.fs_trust:
    name: WsFedApp
    identifier:
      - https://wsfed.example.com/
    wsfed_endpoint: https://wsfed.example.com/auth
    access_control_policy_name: Permit everyone

- name: Update monitoring on an existing trust
  microsoft.ad.fs_trust:
    name: MyApp
    metadata_url: https://app.example.com/federationmetadata/2007-06/federationmetadata.xml
    monitoring_enabled: true

- name: Remove a relying party trust
  microsoft.ad.fs_trust:
    name: MyApp
    state: absent

Return Values

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

Key	Description
enabled boolean	Whether the trust is enabled. Returned: success and state is present Sample: true
identifier list / elements=string	The list of identifiers for the relying party trust. Returned: success and state is present Sample: ["https://app.example.com"]
monitoring_enabled boolean	Whether metadata monitoring is enabled. Returned: success and state is present Sample: true

Authors

• Ron Gershburg (@rgershbu)

Collection links

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