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 字典	如果要添加的属性及其值(s)的字典，如果它们尚未存在于被管理的 AD 对象中。这用于可以包含多个值的属性，如果该属性仅允许单个值，请改用 set。默认值： `{}`
remove 字典	如果要从被管理的 AD 对象中删除的属性及其值(s)的字典，如果它们存在。这用于可以包含多个值的属性，如果该属性仅允许单个值，请改用 set。默认值： `{}`
set 字典	要在被管理的 AD 对象上设置的所有属性及其值(s)的字典。如果现有值与请求的值不匹配，这将替换任何现有值。不检查属性值的顺序，仅检查请求的值是否是对象属性上的唯一值。将此设置为 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 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 属性的值。
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 / 必需	连接到 name 指定的服务器时要使用的密码。
username string / 必需	连接到 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 交互时要使用的用户名。如果未设置，则用于身份验证的用户将是连接用户。除非使用 Kerberos 与凭据委派或 CredSSP 进行身份验证，或者在任务中使用 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 list / elements=any	要将用户添加到的组。
lookup_failure_action 别名：missing_behaviour 字符串	控制当 `groups` 指定的组是无效的组名称时发生的情况。 `fail` 是默认值，如果任何组不存在，将返回错误。 `ignore` 将忽略任何不存在的组。 `warn` 将为任何不存在的组显示警告，但将继续而不失败。选项 `"fail"` ← (默认) `"ignore"` `"warn"`
remove list / elements=any	要从中删除用户的组。
set list / elements=any	用户是其成员的唯一组。如果不在指定列表中，则这将清除所有现有组。设置为一个空列表以清除该用户的所有组成员身份。
identity 字符串	用于查找要管理的 AD 对象的 AD 对象的标识。如果未设置 name，当尝试使用新的 name 重命名对象，或者当尝试将对象移动到不同的 path 时，则必须指定此项。标识可以是表示 `objectGUID` 值的 GUID、`userPrincipalName`、`sAMAccountName`、`objectSid` 或 `distinguishedName` 的形式。如果省略，则要管理的 AD 对象将使用 `distinguishedName`，并使用 `CN={{ name }},{{ path }}` 格式进行选择。如果未定义 path，则改用 `defaultNamingContext`。当使用 microsoft.ad.computer 模块时，如果提供的 `sAMAccountName` 值未找到匹配项，并且末尾没有 `$`，则标识将自动在 `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。设置为一个空列表，以清除 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`。如果在检查模式下创建新对象，则将返回 0 的 GUID。返回: 总是示例: `"d84a141f-2b99-4f08-9da0-ed2d26864ba1"`
sid 字符串	被管理的帐户的安全标识符 (SID)。如果在检查模式下创建新用户，则 SID 将为 `S-1-5-0000`。返回: 总是示例: `"S-1-5-21-4151808797-3430561092-2843464588-1104"`

作者

Jordan Borean (@jborean93)

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

作者

集合链接