Skip to content

Shares Access via Security Groups

Windows clients get a TrueNAS SMB share auto-mapped based on AD group membership, via a GPO rather than per-machine/per-user manual setup. See On-Prem Active Directory for how the underlying AD group itself is created and managed.

This is a convenience/visibility mechanism, not a storage-layer ACL

Being scoped by the app-smb-admins AD group controls who automatically gets the drive letter mapped — it does not mean TrueNAS itself authenticates or authorizes the SMB connection against AD. TrueNAS is not domain-joined to ad.devhome.cloud; the mapped drive still authenticates with a local TrueNAS credential (see below). Don't reach for this GPO as a security boundary — it's a "who sees the shortcut" mechanism, and the actual share ACL lives on TrueNAS itself.

The Drive Map GPO

truenas_drive_map_gpo.ps1.tftpl (terraform/vsphere/compute/scripts/win/dc/) creates a domain-root-linked GPO using Group Policy Preferences' Drive Maps extension, scoped via item-level targeting to a synced AD security group (app-smb-admins by default — configurable per-GPO via truenas_drive_map_ad_group):

variable "truenas_drive_map_gpo_name"  { default = "TrueNAS Drive Mapping" }
variable "truenas_drive_map_letter"    { default = "T" }
variable "truenas_drive_map_unc_path"  { default = "\\\\truenas-dr.devhome.cloud\\backup" }
variable "truenas_drive_map_label"     { default = "TrueNAS Backup" }
variable "truenas_drive_map_ad_group"  { default = "app-smb-admins" }

Any current or future member of that group gets the drive mapped on any domain-joined machine, with zero per-user configuration — add someone to app-smb-admins (via ad_security_groups in variables.tf, or directly in ADUC) and they get the mapping on their next gpupdate/logon, nothing else to touch.

Why it's hand-authored instead of using the GroupPolicy module

Group Policy Preferences (Drive Maps) — unlike Administrative Templates — have no supported PowerShell cmdlet for authoring them; GPMC's GUI is the only "official" tool. The script replicates exactly what GPMC writes to SYSVOL/AD by hand, which means getting two normally-automatic things right manually:

  1. gPCUserExtensionNames on the GPO's AD object — without this, the client never even looks in \User\Preferences\ regardless of GPT.INI's version. Requires the documented CSE GUID pair for Drive Maps plus the generic GPP-engine CSE.
  2. GPT.INI's User-side version number — if this isn't bumped on every re-apply, clients keep serving their cached Drives.xml and never see edits. Solved by piggybacking on Set-GPRegistryValue (a real supported cmdlet) against a harmless marker key — it goes through the official GPO editing API, which keeps SYSVOL's GPT.INI and the AD object's versionNumber correctly in sync without hand-computing the packed version integer.

The obvious-looking <FilterGroup> schema is wrong and fails silently

Security-group item-level targeting needs a single self-closing <FilterGroup sid="..." .../> element — not a <FilterGroup> wrapping a nested <Filter type="SecurityGroup">. The latter looks plausible and validates, but the Group Policy Preferences client extension reports "completed" with no event log error while simply never mapping the drive. Confirmed the hard way before this script existed — worth knowing if this GPO's XML is ever hand-edited again.

Authentication: still a local TrueNAS credential

The GPO's Drives.xml sets userName="" — it doesn't push a stored credential. The actual SMB authentication behind the mapped drive comes from whatever credential is already cached on the machine, via cmdkey /add + net use run during win11-devhome's first interactive logon (win11.tf's run_once_command_list), using the same vm_admin_password/psharma local TrueNAS account convention used everywhere else in this repo for NAS access — not an AD-integrated login. If share access ever needs to be a real AD-enforced boundary (TrueNAS domain-joined, native ACLs keyed to AD group SIDs), that's a real gap against today's implementation, not something already in place.