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).

You might already have this collection installed if you are using the ansible package. 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