Using user and group on Windows

Use the built-in user and group resource types to manage user and group accounts on Windows.

Managing local user and group resources

Puppet uses 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.

Managing group membership with Puppet

Windows manages group membership by specifying the groups to which a user belongs, or by specifying the members of a group. Puppet supports both of these methods.

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

When Puppet is managing a local 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 a group account.

When managing a user, Puppet makes sure that 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 does not remove the user from the group.

If you want to ensure that a user belongs to only the groups listed in the manifest, and no others, 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 makes sure all of the members listed in the manifest are added to the group. Existing members of the group who are not listed in the manifest are ignored.

To ensure that a group contains only the members listed in the manifest, and no others, specify the auth_membership attribute for the group. When this attribute is present and set to true, Puppet removes any members of the group not listed in the manifest.

Allowed user attributes on Windows

When managing Windows user accounts, you can use the following user resource type attributes:
Attribute Usage notes
name
ensure
comment
groups You cannot use the gid attribute with Windows.
home
managehome
membership
password Passwords must be specified in cleartext, because Windows does not have an API for setting the password hash.
auth_membership
uid Read-only. Available for inspecting a user by running puppet resource user <NAME>. The uid value will be the user’s SID (see below).

Allowed group attributes on Windows

When managing Windows group accounts, you can use the following group resource type attributes:
Attribute Usage notes
name
ensure
members
auth_membership
gid Read-only. Available for inspecting a group by running puppet resource group <NAME>. The gid 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 S-1-5-32-544 name form is called a security identifier (SID). Puppet treats all these forms equally: when comparing two account names, it transforms account names into their canonical SID form and compares the SIDs.

When you refer to a user or group in multiple places in a manifest (such as when creating relationships between resources), be consistent with how you capitalize 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 (such as User[BUILTIN\Administrators]) in addition to SIDs (such as 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: When listed for reporting or by puppet resource, groups always return the fully qualified form when describing a user, such as BUILTIN\Administrators. These fully qualified names might not look the same as in the names specified in the manifest.