microsoft.ad.service_account 模块 – 管理 Active Directory 服务帐户对象

注意

此模块是 microsoft.ad 集合（版本 1.7.1）的一部分。

如果您使用的是 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install microsoft.ad。您需要进一步的要求才能使用此模块，有关详细信息，请参阅要求。

要在 playbook 中使用它，请指定：microsoft.ad.service_account。

microsoft.ad 1.7.0 中的新增功能

概要 

管理 Active Directory 服务帐户对象及其属性。
当前，此模块仅支持组托管服务帐户 (gMSA)。
在创建 gMSA 之前，AD 环境必须创建 KDS 根密钥。有关详细信息，请参阅 KDS 密钥。为了使密钥立即生效，请将生效时间设置为 10 小时前，并且不要使用 -EffectiveImmediately 参数。有关详细信息，请参阅示例。

要求 

在执行此模块的主机上需要以下要求。

ActiveDirectory PowerShell 模块

参数 

参数	注释
allowed_to_retrieve_password 字典	允许检索服务帐户密码以进行添加、删除或设置的主体。每个子键值都是以 `distinguishedName`、`objectGUID`、`objectSid`、c(sAMAccountName) 或 `userPrincipalName` 字符串形式的值列表，或者具有 name 和可选 server 键的字典。此值由 ActiveDirectory cmdlet 构建到安全描述符中，并在 `msDS-GroupMSAMembership` LDAP 属性上设置。这对应于 AD cmdlet 上的 `-PrincipalsAllowedToRetrieveManagedPassword` 参数。要清除所有主体，请使用带有空列表的 set。有关 DN 查找如何工作的更多信息，请参阅 DN 查找属性。有关如何添加/删除/设置列表选项的更多信息，请参阅设置列表选项值。
add list / elements=any	将指定的主体添加为允许检索服务帐户密码的主体。除非由 remove 指定或不在 set 中，否则 add 未指定的任何现有主体将保持不变。
lookup_failure_action 字符串	控制查找无法找到 DN 时要执行的操作。 `fail` 将导致任务失败。 `ignore` 将忽略该值并继续。 `warn` 将忽略该值并显示警告。选择 `"fail"` ←（默认） `"ignore"` `"warn"`
remove list / elements=any	删除指定为允许检索服务帐户密码的主体。除非定义了 set，否则 remove 未指定的任何现有主体将保持不变。
set list / elements=any	将指定的主体设置为允许检索服务帐户密码的主体。如果此列表中未指定任何现有主体，则将删除它们。指定一个空列表以删除所有允许委派的主体。
attributes 字典	要添加到 AD 对象、从 AD 对象中删除或在 AD 对象上设置的属性。每个属性选项的值都应是一个字典，其中键是 LDAP 属性，例如 `firstName`、`comment`，值是要为该属性设置的值或值列表。属性值可以是原始字符串、整数或布尔值，以便在所讨论的属性上添加、删除或设置。该值也可以是一个字典，其中 type 键设置为 `bytes`、`date_time`、`security_descriptor` 或 `raw`，并且此条目的值位于 value 键下。 `bytes` 类型的值是要设置的原始字节的 base64 编码字符串。 `date_time` 类型的值是要设置的 DateTime 的 ISO 8601 DateTime 字符串。DateTime 将设置为 Microsoft FILETIME 整数值，该值是自 UTC 时间 1601-01-01 以来 100 纳秒的数量。 `security_descriptor` 类型的值是用于 `nTSecurityDescriptor` 属性的安全描述符 SDDL 字符串。 `raw` 类型是要设置的 int、string 或 boolean 值。字符串属性值使用对正在管理的 AD 对象进行区分大小写的匹配来比较。有关更多信息，请参阅 LDAP 属性帮助。默认值： `{}`
add 字典	一个字典，包含要添加到被管理的 AD 对象的所有属性及其值（如果这些属性尚不存在）。这用于可以包含多个值的属性。如果属性只允许单个值，请改用 set。默认值： `{}`
remove 字典	一个字典，包含要从被管理的 AD 对象中删除的所有属性及其值（如果这些属性存在）。这用于可以包含多个值的属性。如果属性只允许单个值，请改用 set。默认值： `{}`
set 字典	一个字典，包含要在被管理的 AD 对象上设置的所有属性及其值。如果现有值与请求的值不匹配，这将替换任何现有值。不会检查属性值的顺序，只会检查请求的值是否是对象属性上的唯一值。将此项设置为 null 或空列表可清除属性的任何值。默认值： `{}`
delegates 别名: principals_allowed_to_delegate 字典	当前 AD 对象可以信任进行委派的主体对象，以便添加、删除或设置。这也称为基于资源的约束委派。每个子键值都是一个值列表，其形式为 `distinguishedName`、`objectGUID`、`objectSid`、`sAMAccountName` 或 `userPrincipalName` 字符串，或者是一个包含 name 和可选 server 键的字典。这是在 `msDS-AllowedToActOnBehalfOfOtherIdentity` LDAP 属性上设置的值。这是一个高度敏感的属性，因为它允许指定的主体在以该托管帐户运行的服务进行身份验证时模拟任何帐户。要清除所有主体，请使用带有空列表的 set。有关 DN 查找如何工作的更多信息，请参阅 DN 查找属性。有关如何添加/删除/设置列表选项的更多信息，请参阅设置列表选项值。
add list / elements=any	将指定的主体添加为允许委派的主体。除非由 remove 指定或不在 set 中，否则 add 未指定的任何现有主体将保持不变。
lookup_failure_action 字符串	控制查找无法找到 DN 时要执行的操作。 `fail` 将导致任务失败。 `ignore` 将忽略该值并继续。 `warn` 将忽略该值并显示警告。选择 `"fail"` ←（默认） `"ignore"` `"warn"`
remove list / elements=any	删除指定为允许委派的主体的主体。除非定义了 set，否则 remove 未指定的任何现有主体将保持不变。
set list / elements=any	将指定的主体设置为允许委派的主体。如果此列表中未指定任何现有主体，则将删除它们。指定一个空列表以删除所有允许委派的主体。
description 字符串	要设置的 AD 对象的描述。这是在 `description` LDAP 属性上设置的值。
display_name 字符串	要设置的 AD 对象的显示名称。这是 `displayName` LDAP 属性的值。
dns_hostname 字符串	指定服务帐户的 DNS 名称。这是在 `dNSHostName` LDAP 属性上设置的值。当 `outbound_auth_only=True` 时，不能设置此项，否则必须定义。
do_not_append_dollar_to_sam 布尔值	不要自动将 `$` 附加到 sam_account_name 值。这仅在显式设置 sam_account_name 时适用，并且可用于创建不带 `$` 后缀的服务帐户。选择 `false` ← (默认) `true`
domain_credentials list / elements=dictionary	指定在使用 name 指定的服务器时应使用的凭据。要为默认域服务器指定凭据，请使用不带 name 键的条目，或者使用 domain_username 和 domain_password 选项。这可以在剧本的模块默认值的 `group/microsoft.ad.domain` 组下进行设置。有关更多信息，请参见模块中的 AD 身份验证。默认: `[]`
name 字符串	这些凭据适用的服务器的名称。此值应与指定要使用的自定义服务器的其他选项中使用的值相对应，例如，引用位于不同 AD 服务器上的 AD 标识的选项。可以在一个条目中省略此键，以指定在未指定服务器时要使用的默认凭据，而不是使用 domain_username 和 domain_password。
password string / 必需	连接到 name 指定的服务器时要使用的密码。
username string / 必需	连接到 name 指定的服务器时要使用的用户名。
domain_password 字符串	domain_username 的密码。不带 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。这可以在剧本的模块默认值的 `group/microsoft.ad.domain` 组下进行设置。
domain_server 字符串	指定要连接的 Active Directory 域服务实例。可以是 FQDN 或 NetBIOS 名称的形式。如果未指定，则该值基于运行 PowerShell 的计算机的默认域。可以在不带 name 键的 domain_credentials 条目下或通过 domain_username 和 domain_password 指定自定义凭据。这可以在剧本的模块默认值的 `group/microsoft.ad.domain` 组下进行设置。
domain_username 字符串	与 AD 交互时要使用的用户名。如果未设置此项，则用于身份验证的用户将是连接用户。除非身份验证是使用凭据委派或 CredSSP 的 Kerberos，或者在任务上使用了 become，否则 Ansible 将无法使用连接用户。不带 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。这可以在剧本的模块默认值的 `group/microsoft.ad.domain` 组下进行设置。
enabled 布尔值	`yes` 将启用服务帐户。 `no` 将禁用服务帐户。选择 `false` `true`
identity 字符串	用于查找要管理的 AD 对象的 AD 对象的标识。如果未设置 name，尝试使用新的 name 重命名对象，或者尝试将对象移动到不同的 path 中，则必须指定此项。标识可以是表示 `objectGUID` 值的 GUID、`userPrincipalName`、`sAMAccountName`、`objectSid` 或 `distinguishedName` 的形式。如果省略，则使用 `distinguishedName` 采用 `CN={{ name }},{{ path }}` 的格式选择要管理的 AD 对象。如果未定义 path，则改用 `defaultNamingContext`。当使用 microsoft.ad.computer 模块时，如果提供的值未产生匹配结果，并且末尾没有 `$`，则标识将自动将 `$` 附加到 `sAMAccountName` 的末尾。
kerberos_encryption_types 字典	指定 AD 服务帐户支持的 Kerberos 加密类型。这是在 `msDS-SupportedEncryptionTypes` LDAP 属性上设置的值。避免使用 `rc4` 或 `des`，因为它们是较旧且不安全的加密协议。要清除所有加密类型，请使用带有空列表的 set。有关如何添加/删除/设置列表选项的更多信息，请参阅设置列表选项值。
add list / elements=string	要添加到现有集合的加密类型。除非由 remove 指定或不在 set 中，否则 add 未指定的任何现有加密类型都将保持不变。选择 `"aes128"` `"aes256"` `"des"` `"rc4"`
remove list / elements=string	要从现有集合中删除的加密类型。除非定义了 set，否则 remove 未指定的任何现有加密类型都将保持不变。选择 `"aes128"` `"aes256"` `"des"` `"rc4"`
set list / elements=string	设置为 AD 服务帐户允许的唯一加密类型。如果未在此列表中指定，这将删除任何现有的加密类型。指定一个空列表以删除所有加密类型。选择 `"aes128"` `"aes256"` `"des"` `"rc4"`
name 字符串	要管理的 AD 对象的 `name`，这不是对象的 `sAMAccountName`，而是指定路径中对象的 LDAP `cn` 或 `name` 条目。使用 identity 通过其 `sAMAccountName` 选择要管理的对象。如果指定了 identity，并且通过该标识找到的对象名称与此值不匹配，则该对象将被重命名。如果未设置 identity，则必须指定此项。
outbound_auth_only 布尔值	将服务帐户标记为仅用于客户端出站身份验证。设置后，该服务帐户只能用于客户端角色。例如，它只能用于出站身份验证尝试，不能用作目标身份验证服务主体。如果设置，则无法设置 dns_hostname。选择 `false` ← (默认) `true`
path 字符串	新对象应存在的 OU 或容器的路径。如果创建新对象，则将在指定路径处创建新对象。如果未指定路径，则域的 `defaultNamingContext` 将用作大多数对象类型的路径。如果管理通过 identity 找到的现有对象，则找到的对象的路径将移动到此选项指定的路径。如果未指定路径，则不会移动该对象。模块 microsoft.ad.computer、microsoft.ad.user 和 microsoft.ad.group 具有它们自己的默认路径，该路径在 Active Directory 域控制器上配置。可以将其设置为字面值 `microsoft.ad.default_path`，该值将等于创建新对象时使用的默认值。
protect_from_deletion 布尔值	将对象标记为受保护，免遭意外删除。这会应用一个拒绝访问权限，使其无法正常删除对象，并且在可以通过 GUI 或 Ansible 之外的任何其他工具删除对象之前，需要删除此保护。使用 state=absent 仍然会删除 AD 对象，即使该对象被标记为防止删除保护。选择 `false` `true`
sam_account_name 字符串	为服务帐户设置的 `sAMAccountName` 值。最大长度为 256 个字符，为了与旧操作系统兼容，建议使用 15 个字符。如果省略，则在创建服务帐户时，该值与 `name$` 相同。请注意，服务帐户的 `sAMAccountName` 值通常以 `$` 结尾。默认情况下，如果省略 `$` 后缀，则会在末尾添加。如果 do_not_append_dollar_to_sam=True，则将按原样使用提供的值，而不会在末尾添加 `$`。
spn 别名: spns 字典	指定要添加、删除或设置的帐户的服务主体名称 (SPN)。这是在 `servicePrincipalName` LDAP 属性上设置的值。要清除所有服务主体名称，请使用 set 和一个空列表。有关如何添加/删除/设置列表选项的更多信息，请参阅设置列表选项值。
add list / elements=string	要添加到 `servicePrincipalName` 的 SPN。
remove list / elements=string	要从 `servicePrincipalName` 中删除的 SPN。
set list / elements=string	要设置为 `servicePrincipalName` 中唯一值的 SPN。如果指定的列表中没有现有 SPN，则会清除它们。设置为一个空列表以清除 AD 对象上的所有 SPN。
state 字符串	设置为 `present` 以确保 AD 对象存在。设置为 `absent` 以删除存在的 AD 对象。当 state=present 时，必须设置 name 选项。使用 `absent` 将递归删除 AD 对象及其任何子对象（如果它是容器）。即使该对象被标记为防止意外删除，也会删除该 AD 对象。选择 `"absent"` `"present"` ← (默认)
trusted_for_delegation 布尔值	指定是否信任某个帐户进行 Kerberos 委派。这也称为非约束 Kerberos 委派。这会在 `userAccountControl` LDAP 属性中设置 `ADS_UF_TRUSTED_FOR_DELEGATION` 标志。选择 `false` `true`
upn 字符串	配置帐户的用户主体名称 (UPN)。格式为 `<username>@<domain>`。这是在 `userPrincipalName` LDAP 属性上设置的值。

属性 

属性	支持	描述
check_mode	支持: 完全	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标，如果不支持，则会跳过该操作。
diff_mode	支持: 完全	当处于 diff 模式时，将返回有关已更改（或可能需要在 check_mode 中更改）的内容的详细信息。
platform	平台: windows	可以对其进行操作的目标操作系统/系列

注释 

注意

此模块必须在安装了 ActiveDirectory 模块的 Windows 目标主机上运行。
当使用 sAMAccountName 值按 identity 进行匹配时，该值应以 $ 结尾。如果提供的值不以 $ 结尾，则该模块仍会尝试查找具有提供值的服务帐户，然后再尝试回退查找并在末尾附加 $。
某些 LDAP 属性只能设置一个值，而另一些属性可以有多个值。某些属性也是只读的，无法更改。建议查看属性的架构元数据，其中 System-Only 是只读值，而 Is-Single-Value 是只有 1 个值的属性。
尝试将多个值设置为 Is-Single-Value 属性会导致未定义的行为。
如果在不是域控制器的服务器上运行，则必须使用通过 CredSSP 或 Kerberos 进行的凭据委派（需委派），或者必须设置 domain_username、domain_password。

参见 

另请参阅

microsoft.ad.object_info: 收集 Active Directory 对象的信息。
microsoft.ad.object: 管理 Active Directory 对象。

示例 

# A gMSA requires a KDS root key to be created. This key must be valid for
# 10 hours before it can be used. This example creates the key and sets the
# time for 10 hours ago to let it be used immediately. If your environment
# uses multiple DCs you will still need to wait 10 hours for replication to
# occur or target the DC you created the key on. Required Domain Admin or
# Enterprise Admin privileges.
- name: Create KDS root key if not present
  ansible.windows.win_powershell:
    error_action: stop
    script: |
      $Ansible.Changed = $false
      if (-not (Get-KdsRootKey)) {
          Add-KdsRootKey -EffectiveTime ((Get-Date).AddHours(-10))
          $Ansible.Changed = $true
      }

- name: Create gMSA that allows Domain Admins to use
  microsoft.ad.service_account:
    identity: MyGMSA
    dns_hostname: MyGMSA.my_org.local
    description: GMSA for Domin Admins
    state: present
    allowed_to_retrieve_password:
      set:
        - Domain Admins

- name: create gMSA that allows the ITFarmHosts computer account to retrieve the pass
  microsoft.ad.service_account:
    identity: ITFarm1
    dns_hostname: ITFarm1.contoso.com
    allowed_to_retrieve_password:
      set:
        - ITFarmHosts$
    kerberos_encryption_types:
      set:
        - aes128
        - aes256
    spn:
      add:
        - http/ITFarm1.contoso.com/contoso.com
        - http/ITFarm1.contoso.com/contoso
        - http/ITFarm1.contoso.com
        - http/ITFarm1.contoso

- name: Remove gMSA by identity
  microsoft.ad.service_account:
    identity: ITFarm1$
    state: absent

- name: Add SPNs to service account
  microsoft.ad.service_account:
    identity: MySA$
    spn:
      add:
        - HOST/MySA
        - HOST/MySA.domain.test
        - HOST/MySA.domain.test:1234

- name: Remove SPNs on the service account
  microsoft.ad.service_account:
    identity: MySA$
    spn:
      remove:
        - HOST/MySA
        - HOST/MySA.domain.test
        - HOST/MySA.domain.test:1234

- name: Add gMSA with sAMAccountName without $ suffix
  microsoft.ad.service_account:
    identity: MySA
    dns_hostname: MySA.contoso.com
    sam_account_name: MySA
    do_not_append_dollar_to_sam: true

作者

Jordan Borean (@jborean93)