microsoft.ad.user 模块 – 管理 Active Directory 用户

注意

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

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

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

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

概要 

管理 Active Directory 用户及其属性。

要求 

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

ActiveDirectory PowerShell 模块

参数 

参数	注释
account_locked 布尔值	`no` 将解锁已锁定的用户帐户。请注意，没有办法以管理员身份锁定帐户。帐户因用户操作而被锁定；作为管理员，您只能解锁锁定的帐户。如果您希望以管理方式禁用帐户，请将enabled设置为 `no`。选择 `false` `true`
attributes 字典	要在 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、字符串或布尔值。字符串属性值使用对所管理的 AD 对象进行区分大小写的匹配进行比较。有关更多信息，请参见LDAP 属性帮助。默认值：`{}`
add 字典	如果 AD 对象尚不存在，则将所有属性及其值添加到要管理的 AD 对象的字典。这用于可以包含多个值的属性，如果该属性只允许一个值，则改用 set。默认值：`{}`
remove 字典	如果要管理的 AD 对象中存在，则删除其中所有属性及其值的字典。这用于可以包含多个值的属性，如果该属性只允许一个值，则改用 set。默认值：`{}`
set 字典	要在所管理的 AD 对象上设置的所有属性及其值的字典。如果现有值与所请求的值不匹配，则这将替换任何现有值。不检查属性值的顺序，仅检查所请求的值是否是对象属性上的唯一值。将此设置为 null 或空列表以清除该属性的所有值。默认值：`{}`
city 字符串	配置用户的城市。这是在 `l` LDAP 属性上设置的值。
company 字符串	配置用户的公司名称。这是在 `company` LDAP 属性上设置的值。
country 字符串	配置用户的国家代码。请注意，这是一个双字符 ISO 3166 代码。这是在 `c` LDAP 属性上设置的值。
delegates 别名：principals_allowed_to_delegate 字典	当前 AD 对象可以信任委托添加、删除或设置的主体对象。每个子键值都是 `distinguishedName`、`objectGUID`、`objectSid`、`sAMAccountName` 或 `userPrincipalName` 字符串形式的值列表，或带有 name 和可选的 server 键的字典。这是在 `msDS-AllowedToActOnBehalfOfOtherIdentity` LDAP 属性上设置的值。这是一个高度敏感的属性，因为它允许指定的主体在与正在管理的 AD 计算机对象进行身份验证时模拟任何帐户。要清除所有主体，请使用带有空列表的 set。有关 DN 查找的工作原理的更多信息，请参见DN 查找属性。有关如何添加/删除/设置列表选项的更多信息，请参见设置列表选项值。
add 列表 / 元素=any	将指定的主体添加为允许委托的主体。除非由 remove 指定或不在 set 中，否则 add 未指定的任何现有主体将保持不变。
lookup_failure_action 字符串	控制当查找失败时，找不到 DN 时采取的操作。 `fail` 将导致任务失败。 `ignore` 将忽略该值并继续。 `warn` 将忽略该值并显示警告。选择 `"fail"` ← (默认) `"ignore"` `"warn"`
remove 列表 / 元素=any	删除指定为允许委派的主体。除非定义了 set，否则任何未由 remove 指定的现有主体都将保持不变。
set 列表 / 元素=any	将指定的主体设置为允许委派的主体。如果未在此列表中指定，则这将删除任何现有主体。指定一个空列表以删除所有允许委派的主体。
description 字符串	要设置的 AD 对象的描述。这是在 `description` LDAP 属性上设置的值。
display_name 字符串	要设置的 AD 对象的显示名称。这是 `displayName` LDAP 属性的值。
domain_credentials list / elements=dictionary	指定在使用 name 指定的服务器时应使用的凭据。要为默认域服务器指定凭据，请使用不带 name 键的条目或使用 domain_username 和 domain_password 选项。可以在 play 的模块默认值下的 `group/microsoft.ad.domain` 组下设置此项。有关详细信息，请参阅模块中的 AD 身份验证。默认值： `[]`
name 字符串	这些凭据所针对的服务器名称。此值应与在其他指定要使用的自定义服务器的选项中使用的值相对应，例如，引用位于不同 AD 服务器上的 AD 标识的选项。可以省略一个条目中的此键，以指定在未指定服务器时要使用的默认凭据，而不是使用 domain_username 和 domain_password。
password string / required	连接到由 name 指定的服务器时要使用的密码。
username string / required	连接到由 name 指定的服务器时要使用的用户名。
domain_password 字符串	domain_username 的密码。不带 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。可以在 play 的模块默认值下的 `group/microsoft.ad.domain` 组下设置此项。
domain_server 字符串	指定要连接的 Active Directory 域服务实例。可以采用 FQDN 或 NetBIOS 名称的形式。如果未指定，则该值基于运行 PowerShell 的计算机的默认域。可以在不带 name 键的 domain_credentials 条目下或通过 domain_username 和 domain_password 指定自定义凭据。可以在 play 的模块默认值下的 `group/microsoft.ad.domain` 组下设置此项。
domain_username 字符串	与 AD 交互时要使用的用户名。如果未设置此项，则用于身份验证的用户将是连接用户。除非身份验证是具有凭据委派或 CredSSP 的 Kerberos，或者在任务上使用了 become，否则 Ansible 将无法使用连接用户。不带 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。可以在 play 的模块默认值下的 `group/microsoft.ad.domain` 组下设置此项。
email 字符串	配置用户的电子邮件地址。这是 AD 中的记录，不会执行任何操作来配置任何电子邮件服务器或系统。这是在 `mail` LDAP 属性上设置的值。
enabled 布尔值	`yes` 将启用用户帐户。 `no` 将禁用帐户。如果指定了 password，则创建新用户的默认值为 `yes`。如果未指定 password，则不会启用该用户。选择 `false` `true`
firstname 字符串	配置用户的名字（给定名称）。这是在 `givenName` LDAP 属性上设置的值。
groups 字典	指定用户被添加、删除或设置为的组成员身份。要清除所有组成员身份，请将 set 与空列表一起使用。请注意，无法将用户从其主要组（例如，“域用户”）中删除。尝试执行此操作将显示警告。从组中添加和删除用户是在组 AD 对象上完成的。如果该组是另一个域中的对象，则可能需要显式的 server 和 domain_credentials 才能使其工作。每个子键分别设置为要添加、删除或设置为此 AD 用户的成员身份的组对象列表。组可以采用 `distinguishedName`、`objectGUID`、`objectSid` 或 `sAMAccountName` 的形式。每个子键值都是组对象列表，形式为 `distinguishedName`、`objectGUID`、`objectSid`、`sAMAccountName` 或 `userPrincipalName` 字符串或具有 name 和可选的 server 键的字典。有关 DN 查找的工作原理的更多信息，请参见DN 查找属性。有关如何添加/删除/设置列表选项的更多信息，请参见设置列表选项值。
add 列表 / 元素=any	要将用户添加到的组。
lookup_failure_action 别名：missing_behaviour 字符串	控制当由 `groups` 指定的组是无效的组名称时发生的情况。 `fail` 是默认值，如果任何组不存在，则返回错误。 `ignore` 将忽略任何不存在的组。 `warn` 将为任何不存在的组显示警告，但会继续而不失败。选择 `"fail"` ← (默认) `"ignore"` `"warn"`
remove 列表 / 元素=any	要从中删除用户的组。
set 列表 / 元素=any	用户是其成员的唯一组。如果未在指定列表中，这将清除任何现有组。设置为一个空列表以清除用户的所有组成员身份。
identity 字符串	用于查找要管理的 AD 对象的 AD 对象的标识。必须在以下情况下指定此项：未设置 name；尝试使用新的 name 重命名对象时；或尝试将对象移动到不同的 path 时。标识可以采用表示 `objectGUID` 值的 GUID、`userPrincipalName`、`sAMAccountName`、`objectSid` 或 `distinguishedName` 的形式。如果省略，则要管理的 AD 对象将通过使用格式 `CN={{ name }},{{ path }}` 的 `distinguishedName` 来选择。如果未定义 path，则将改用 `defaultNamingContext`。当使用 microsoft.ad.computer 模块时，如果提供的值未导致匹配，并且末尾没有 `$`，则标识将自动将 `$` 附加到 `sAMAccountName` 的末尾。
name 字符串	要管理的 AD 对象的 `name`，这不是对象的 `sAMAccountName`，而是路径中对象的 LDAP `cn` 或 `name` 条目。使用 identity 按其 `sAMAccountName` 选择要管理的对象。如果指定了 identity，并且通过该标识找到的对象名称与此值不匹配，则将重命名该对象。如果未设置 identity，则必须指定此项。
password 字符串	（可选）将用户的密码设置为此（纯文本）值。要启用帐户 - enabled - 必须已在该帐户上配置密码，或者您必须在此处提供密码。使用 update_password 选项来控制如何检查密码的幂等性。
password_expired 布尔值	`yes` 将要求用户在下次登录时更改密码。 `no` 将清除已过期的密码标志。这与password_never_expires互斥。选择 `false` `true`
password_never_expires 布尔值	`yes` 将设置密码永不过期。 `no` 将允许密码过期。这与password_expired互斥。选择 `false` `true`
path 字符串	新对象应该存在的 OU 或容器的路径。如果创建新对象，则新对象将在指定的路径下创建。如果未指定路径，则大多数对象类型将使用域的 `defaultNamingContext` 作为路径。如果管理通过identity找到的现有对象，则找到的对象的路径将移动到此选项指定的路径。如果未指定路径，则不会移动该对象。模块 microsoft.ad.computer、microsoft.ad.user 和 microsoft.ad.group 都有其自己的默认路径，该路径在 Active Directory 域控制器上配置。可以将其设置为字面值 `microsoft.ad.default_path`，它将等于创建新对象时使用的默认值。
postal_code 字符串	配置用户的邮政编码/邮编。这是在 `postalcode` LDAP 属性上设置的值。
protect_from_deletion 布尔值	将对象标记为防止意外删除。这会应用拒绝访问权限，使其无法正常删除对象，并且需要在可以通过 GUI 或 Ansible 之外的任何其他工具删除对象之前删除保护。即使 AD 对象被标记为防止删除，使用 state=absent 仍将删除它。选择 `false` `true`
sam_account_name 字符串	为用户设置的 `sAMAccountName` 值。如果省略，则在创建新用户时使用 name 值。
spn 别名：spns 字典	指定要添加、删除或设置的帐户的服务主体名称。这是在 `servicePrincipalName` LDAP 属性上设置的值。要清除所有服务主体名称，请使用带有空列表的 set。有关如何添加/删除/设置列表选项的更多信息，请参见设置列表选项值。
add list / elements=string	要添加到 `servicePrincipalName` 的 SPN。
remove list / elements=string	要从 `servicePrincipalName` 中删除的 SPN。
set list / elements=string	要设置为 `servicePrincipalName` 中唯一值的 SPN。如果指定的列表中没有现有 SPN，这将清除任何现有 SPN。设置为一个空列表以清除 AD 对象上的所有 SPN。
state 字符串	设置为 `present` 以确保 AD 对象存在。设置为 `absent` 以删除存在的 AD 对象。当 state=present 时，必须设置选项 name。使用 `absent` 将递归删除 AD 对象及其任何子对象（如果它是容器）。即使对象被标记为防止意外删除，它也会删除 AD 对象。选择 `"absent"` `"present"` ← (默认)
state_province 字符串	配置用户的州/省。这是在 `state` LDAP 属性上设置的值。
street 字符串	配置用户的街道地址。这是在 `streetaddress` LDAP 属性上设置的值。
surname 别名：lastname 字符串	配置用户的姓氏。这是在 `sn` LDAP 属性上设置的值。
update_password 字符串	`always` 将始终更新密码。 `on_create` 仅为新创建的用户设置密码。 `when_changed` 仅在密码更改时设置密码。如果帐户未启用或已过期，使用 `when_changed` 将不起作用。选择 `"always"` ← (默认) `"on_create"` `"when_changed"`
upn 字符串	配置帐户的用户主体名称 (UPN)。这不是必需的，但最好为现代版本的 Active Directory 配置。格式为 `<username>@<domain>`。这是在 `userPrincipalName` LDAP 属性上设置的值。
user_cannot_change_password 布尔值	`yes` 将阻止用户更改其密码。 `no` 将允许用户更改其密码。选择 `false` `true`

属性 

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

备注 

注意

有关从 community.windows.win_domain_user 迁移到此模块的帮助，请参阅 win_domain_user 迁移。
此模块必须在安装了 ActiveDirectory 模块的 Windows 目标主机上运行。
一些 LDAP 属性只能设置一个值，而其他属性可以有多个值。一些属性也是只读的，无法更改。建议查看属性的架构元数据，其中 System-Only 是只读值，Is-Single-Value 是只有 1 个值的属性。
尝试将多个值设置为 Is-Single-Value 属性会导致未定义的行为。
如果在不是域控制器的服务器上运行，则必须使用通过 CredSSP 或 Kerberos 进行的凭据委派，或者必须设置 domain_username、domain_password。

另请参阅 

另请参阅

microsoft.ad.domain: 确保 Windows 域的存在。
microsoft.ad.domain_controller: 管理 Windows 主机的域控制器/成员服务器状态。
microsoft.ad.group: 管理 Active Directory 组对象。
microsoft.ad.object: 管理 Active Directory 对象。
microsoft.ad.object_info: 收集 Active Directory 对象的信息。
microsoft.ad.computer: 管理 Active Directory 计算机对象。
迁移指南: 此模块替换 community.windows.win_domain_user。有关详细信息，请参阅迁移指南。
community.windows.win_domain_user: 管理 Windows Active Directory 用户帐户。

示例 

- name: Ensure user bob is present with address information
  microsoft.ad.user:
    identity: bob
    firstname: Bob
    surname: Smith
    company: BobCo
    password: B0bP4ssw0rd
    state: present
    groups:
      set:
        - Domain Admins
    street: 123 4th St.
    city: Sometown
    state_province: IN
    postal_code: 12345
    country: US
    attributes:
      set:
        telephoneNumber: 555-123456

- name: Ensure user bob is created and use custom credentials to create the user
  microsoft.ad.user:
    identity: bob
    firstname: Bob
    surname: Smith
    password: B0bP4ssw0rd
    state: present
    domain_username: DOMAIN\admin-account
    domain_password: SomePas2w0rd
    domain_server: [email protected]

- name: Ensure user bob is present in OU ou=test,dc=domain,dc=local
  microsoft.ad.user:
    identity: bob
    password: B0bP4ssw0rd
    state: present
    path: ou=test,dc=domain,dc=local
    groups:
      set:
        - Domain Admins
        - Domain Users

- name: Ensure user bob is absent
  microsoft.ad.user:
    identity: bob
    state: absent

- name: Ensure user has only these spn's defined
  microsoft.ad.user:
    identity: liz.kenyon
    spn:
      set:
        - MSSQLSvc/us99db-svr95:1433
        - MSSQLSvc/us99db-svr95.vmware.com:1433

- name: Ensure user has spn added
  microsoft.ad.user:
    identity: liz.kenyon
    spn:
      add:
        - MSSQLSvc/us99db-svr95:2433

- name: Ensure user is created with delegates and spn's defined
  microsoft.ad.user:
    identity: shmemmmy
    password: The3rubberducki33!
    state: present
    groups:
      set:
        - Domain Admins
        - Domain Users
        - Enterprise Admins
    delegates:
      set:
        - CN=shenetworks,CN=Users,DC=ansible,DC=test
        - CN=mk.ai,CN=Users,DC=ansible,DC=test
        - CN=jessiedotjs,CN=Users,DC=ansible,DC=test
    spn:
      set:
        - MSSQLSvc/us99db-svr95:2433

# The name option is the name of the AD object as seen in dsa.msc and not the
# sAMAccountName. For example, this will change the sAMAccountName of the user
# CN=existing_user,CN=Users,DC=domain,DC=com to 'new_sam_name'.
# E.g. This will change
- name: Change the user's sAMAccountName
  microsoft.ad.user:
    name: existing_user
    sam_account_name: new_sam_name
    state: present

# This will rename the AD object that is specified by identity to 'new_name'.
# The identity value can be the object's GUID, SecurityIdentifier, or
# sAMAccountName. It is important to use the identity value when renaming or
# moving a user object to ensure the object is moved/renamed rather than a new
# one being created.
- name: Rename user LDAP name
  microsoft.ad.user:
    name: new_name
    identity: '{{ user_obj.object_guid }}'
    state: present

# Like changing the name example above, the identity option is needed to ensure
# the existing user object specified is moved rather than a new one created at
# the path specified.
- name: Move user object to different OU
  microsoft.ad.user:
    name: user
    path: OU=Admins,DC=domain,DC=com
    identity: '{{ user_obj.sid }}'
    state: present

返回值 

常见返回值记录在此处，以下是此模块特有的字段

键	描述
distinguished_name 字符串	已创建、删除或编辑的 AD 对象的 `distinguishedName`。返回：始终示例： `"CN=TestUser,CN=Users,DC=domain,DC=test"`
object_guid 字符串	已创建、删除或编辑的 AD 对象的 `objectGUID`。如果在 check 模式下创建了新对象，则将返回 0 的 GUID。返回：始终示例： `"d84a141f-2b99-4f08-9da0-ed2d26864ba1"`
sid 字符串	受管帐户的安全标识符 (SID)。如果在 check 模式下创建了新用户，则 SID 将为 `S-1-5-0000`。返回：始终示例： `"S-1-5-21-4151808797-3430561092-2843464588-1104"`

作者

Jordan Borean (@jborean93)

microsoft.ad.user 模块 – 管理 Active Directory 用户

作者

合集链接