Resource tips and examples: User and group on Windows

Puppet’s built-in user and [group][group] resource types can manage user and group accounts on Windows.

This page describes what you’ll want to know before using them.

What Puppet can manage

Local user/group resources

Puppet can use the user and group resource types to manage local accounts.

You can’t write a Puppet resource that describes a domain user or group. However, a local group resource can manage which domain accounts belong to the local group. See the next section for details.

Group membership

Windows can manage group membership by specifying the groups to which a user belongs, or specifying the members of a group. Puppet supports both cases.

If Puppet is managing a local user, you can list the groups that the user belongs to. Each group can be a local group account, such as Administrators, or a domain group account.

If Puppet is managing a local [group][group], you can list the members that belong to the group. Each member can be a local account, such as Administrator, or a domain account, where each account can be a user or group account.

When managing a user, Puppet will make sure the user belongs to all of the groups listed in the manifest. If the user belongs to a group not specified in the manifest, Puppet will not remove the user from the group.

If you want to ensure a user belongs to only the groups listed in the manifest, and no more, you can specify the membership attribute for the user. If set to inclusive, Puppet removes the user from any group not listed in the manifest.

Similarly, when managing a group, Puppet will make sure all of the members listed in the manifest are added to the group. Existing members of the group not listed in the manifest will be ignored. If you want to ensure a group contains only the members listed in the manifest, and no more, you can specify the auth_membership attribute for the group. If set to true, Puppet will remove existing members of the group that are not listed in the manifest.

Allowed attributes

When managing Windows user accounts, you can use the following attributes:

• name
• ensure
• comment
• groups — note that you can’t use the gid attribute.
• home
• managehome
• password — note that passwords can only be specified in cleartext, since Windows has no API for setting the password hash.
• [auth_membership][auth_membership_user]

Additionally, the uid attribute is available as a read-only property when inspecting a user with puppet resource user <NAME>. Its value will be the user’s SID (see below).

When managing Windows [group][group] accounts, you can use the following attributes:

• name
• ensure
• members
• auth_membership

Additionally, the gid attribute is available as a read-only property when inspecting a group with puppet resource group <NAME>. Its value will be the group’s SID (see below).

Names and security identifiers (SIDs)

On Windows, user and group account names can take multiple forms, such as Administrators, <host>\Administrators, BUILTIN\Administrators, S-1-5-32-544 — the last is called a security identifier (SID). Puppet treats all these forms as equivalent: when comparing two account names, it first transforms account names into their canonical SID form and compares the SIDs instead.

If you need to refer to a user or group in multiple places in a manifest (such as when creating relationships between resources), be consistent with the case of the name. Names are case-sensitive in Puppet manifests, but case-insensitive on Windows. It’s important that the cases match, however, because autorequire will attempt to match users with fully qualified names (User[BUILTIN\Administrators]) in addition to SIDs (User[S-1-5-32-544]). It might not match in cases where domain accounts and local accounts have the same name, such as Domain\Bob versus LOCAL\Bob.

Note: For reporting and for puppet resource, groups always come back in fully qualified form when describing a user, so it looks like BUILTIN\Administrators. In other words, it doesn’t always look the same as in the manifest.

Errata

Known issues prior to Puppet 4

• Before 4.0, Puppet would, by default, remove members of a group that were not specified in the manifest.

Known issues prior to Puppet 3.4 / PE 3.2

Before Puppet 3.4 / Puppet Enterprise 3.2, Puppet could not:

• Add/remove domain users to a local group
• Add/remove groups to a local group