microsoft.ad.fs_claim_rule module – Manage AD FS claim rules on a Relying Party Trust

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

New in microsoft.ad 1.11.0

Synopsis

  • Set, append, or clear Issuance Transform Rules and Issuance Authorization Rules on an existing AD FS Relying Party Trust.

  • The Relying Party Trust must already exist; use microsoft.ad.fs_trust to create it.

Parameters

Parameter

Comments

authorization_rules

dictionary

Issuance Authorization Rules to apply to the trust.

These rules define who is authorized to receive a token for the relying party.

update

string

How to apply the rules.

set replaces all existing authorization rules with the provided value.

append adds the provided rules after any existing authorization rules.

Choices:

  • "set" ← (default)

  • "append"

value

list / elements=string / required

List of claim rule strings in the AD FS claim rule language.

Each item is one rule block. Multiple items are joined with newlines before being applied.

name

string / required

The display name of the Relying Party Trust to manage rules on.

state

string

When present, the specified rules are set or appended.

When absent, all issuance transform and authorization rules are cleared from the trust.

Choices:

  • "present" ← (default)

  • "absent"

transform_rules

dictionary

Issuance Transform Rules to apply to the trust.

These rules define how incoming identity claims are mapped or transformed before being sent to the relying party.

update

string

How to apply the rules.

set replaces all existing transform rules with the provided value.

append adds the provided rules after any existing transform rules.

Choices:

  • "set" ← (default)

  • "append"

value

list / elements=string / required

List of claim rule strings in the AD FS claim rule language.

Each item is one rule block. Multiple items are joined with newlines before being applied.

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 host with the AD FS role installed.

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

  • The Relying Party Trust must already exist.

  • AD FS validates claim rule syntax strictly. Syntax errors from the server are surfaced in the module failure message.

See Also

See also

microsoft.ad.fs_trust

Manage AD FS Relying Party Trusts.

Set-AdfsRelyingPartyTrust

Microsoft documentation for the underlying cmdlet.

Examples

- name: Set issuance transform rules (overwrites existing)
  microsoft.ad.fs_claim_rule:
    name: MyApp
    transform_rules:
      value:
        - |
          @RuleName = "Send Email as NameID"
          c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
             Issuer == "AD AUTHORITY"]
          => issue(store = "Active Directory",
                   types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"),
                   query = ";mail;{0}", param = c.Value);

- name: Set multiple transform rules at once
  microsoft.ad.fs_claim_rule:
    name: MyApp
    transform_rules:
      value:
        - |
          @RuleName = "Pass Through UPN"
          c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
          => issue(claim = c);
        - |
          @RuleName = "Pass Through Email"
          c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
          => issue(claim = c);

- name: Append a rule to existing transform rules
  microsoft.ad.fs_claim_rule:
    name: MyApp
    transform_rules:
      update: append
      value:
        - |
          @RuleName = "Send Group Membership"
          c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",
             Value =~ "^S-1-5-21-"]
          => issue(claim = c);

- name: Set authorization rules
  microsoft.ad.fs_claim_rule:
    name: MyApp
    authorization_rules:
      value:
        - |
          @RuleTemplate = "AllowAllAuthzRule"
          => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit",
                   Value = "true");

- name: Set both transform and authorization rules
  microsoft.ad.fs_claim_rule:
    name: MyApp
    transform_rules:
      value:
        - |
          @RuleName = "Pass Through UPN"
          c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
          => issue(claim = c);
    authorization_rules:
      value:
        - |
          @RuleTemplate = "AllowAllAuthzRule"
          => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit",
                   Value = "true");

- name: Clear all claim rules from a trust
  microsoft.ad.fs_claim_rule:
    name: MyApp
    state: absent

Return Values

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

Key

Description

authorization_rules

string

The issuance authorization rules on the trust after the module runs.

Returned: always

Sample: "@RuleTemplate = \"AllowAllAuthzRule\" ..."

transform_rules

string

The issuance transform rules on the trust after the module runs.

Returned: always

Sample: "@RuleName = \"Send Email\" ..."

Authors

  • Ron Gershburg (@rgershbu)