Joining TrueNAS to Active Directory: SMB Shares with AD Permissions

TrueNAS has established itself as a reliable ZFS-based storage platform in the SMB segment. But as soon as Windows clients need access to central file shares, there is no way around clean integration with the existing Active Directory. Only then can permissions be maintained via familiar AD groups, Single Sign-On used, and audit requirements met.

In this article, we show step by step how to join a TrueNAS SCALE 24.10 (or TrueNAS Enterprise 25.04) to a Windows Server AD, assign SMB shares with AD permissions, and avoid the most common pitfalls around DNS, Kerberos and Samba 4.x ID mapping.

Prerequisites: DNS, time and name resolution

Before triggering the join, three fundamentals must be in place — otherwise the integration will fail with cryptic Kerberos or LDAP errors.

1. Configure DNS correctly. TrueNAS must be able to resolve the AD domain and its domain controllers via DNS. Under Network — Global Configuration, enter exclusively your internal DCs as name servers. External resolvers like 8.8.8.8 or your router do not belong in this list — they don’t know your _ldap._tcp.dc._msdcs.company.local records.

2. Hostname and FQDN. Set the hostname short (e.g. truenas01) and enter the AD domain as Domain. The full FQDN should be truenas01.company.local.

3. Time synchronisation. Kerberos tolerates a maximum drift of 5 minutes. Under System Settings — General — NTP Servers, configure exactly the domain controllers as NTP source. External pools often cause drift in isolated networks.

Component	Recommended source	Common mistake
DNS	Internal DCs	External resolvers
NTP	Internal DCs	pool.ntp.org on isolated networks
Hostname	Short, no dot	FQDN in hostname field
Domain	company.local	NetBIOS name COMPANY

Domain join: service account or standard join

TrueNAS supports two paths for the domain join. Both result in a computer object in AD, but differ in the permission model.

Standard join with domain admin account: You enter the credentials of an account with the right to create computer objects — once. TrueNAS creates the machine account, generates the computer password, and then discards the admin credentials. The easiest path for small environments.

Pre-created computer object (recommended for enterprise): An AD administrator creates the computer object in advance in the desired OU and delegates only the right to join to a dedicated service account. This keeps the TrueNAS system cleanly isolated even in restrictive Tier-0 environments.

The actual join is found under Credentials — Directory Services — Active Directory:

Domain Name:           company.local
Domain Account Name:   svc-truenas-join
Domain Account Pwd:    ********
Computer Account OU:   OU=Fileserver,OU=Server,DC=company,DC=local
Enable:                [x]

After saving, TrueNAS automatically activates the Winbind service, obtains a Kerberos Ticket-Granting Ticket and sets up the idmap configuration. The status should jump to HEALTHY within 30 seconds.

Assigning AD permissions to SMB shares

After a successful join, you can use AD users and groups directly in share ACLs. Important: TrueNAS has two permission layers — the Share ACL (who is allowed to mount the share at all) and the Filesystem ACL (NTFS-equivalent permissions at file and folder level).

For a typical department share, proceed as follows:

1. Create dataset: Datasets — Add Dataset, Share Type SMB, ACL type NFSv4.
2. Create SMB share: Shares — Windows Shares (SMB) — Add. Select path, Purpose Default share parameters.
3. Set share ACL: Leave the default Everyone -- Full Control — real control happens via the filesystem ACL.
4. Edit filesystem ACL: Edit Filesystem ACL. Here you enter AD groups like COMPANY\GG-Marketing-RW with the appropriate rights.

ACL inheritance behaves like under Windows. A folder with Modify for the group GG-Accounting-RW and Read & Execute for GG-Management-RO can be modelled exactly as you know it from the Windows file server. More about our storage projects on the TrueNAS page.

Troubleshooting: Kerberos errors and idmap ranges

In practice, three error patterns appear particularly often. Here are the typical causes and remedies:

Error: KRB5KDC_ERR_PREAUTH_FAILED Cause: Wrong service account password or time drift > 5 minutes. Check date on TrueNAS and w32tm /query /status on the DC. Do the time zones match?

Error: Failed to join domain: failed to find DC Cause: DNS SRV records cannot be resolved. Test from the TrueNAS shell:

host -t SRV _ldap._tcp.dc._msdcs.company.local
nslookup -type=SRV _kerberos._tcp.company.local

If no answer comes back, check the DNS server entries under Network — Global Configuration.

Error: AD users are mapped to SMB shares with UID nobody (65534) Cause: The idmap range does not cover the RIDs of the AD users. Samba 4.x uses the default range 100000-200000. In large domains with many objects or migrated SIDs, this is not enough. Under Active Directory — Advanced Options, extend the range, e.g. to 100000-999999. Caution: A later change can render existing ACLs useless — plan this step before going productive.

RID range	Example use
< 1000	Built-in accounts (Administrator, Guest)
1000-9999	Initially installed AD objects
10000-50000	Typical SMB environment
> 50000	Migrated or large forests

Common pitfalls with Samba 4.x ID mapping

Beyond range size, there are further cliffs that cause pain in production environments:

• Multiple domains / trusts: With trust relationships, separate idmap backends must be configured per domain. Otherwise the UID ranges collide and users from the trust domain end up at nobody again.
• RFC2307 attributes: If POSIX attributes (uidNumber, gidNumber) are already maintained in AD, you should switch the idmap backend from rid to ad. Otherwise Samba ignores the existing UIDs and assigns its own — inconsistent with Linux clients.
• Snapshots before range changes: Take a ZFS snapshot of the affected dataset before any change to the idmap range. If UIDs no longer match after the restart, you can help yourself with a zfs rollback.
• winbind use default domain = yes: Saves the COMPANY\ prefix at login, but can lead to name collisions with multiple trusted domains.

For more complex setups — such as multi-site with read-only DCs or forest trusts — we recommend close coordination with the AD team. Our Linux consulting covers exactly these hybrid environments.

Conclusion: Cleanly planned, robust in operation

Joining a TrueNAS system to Active Directory is technically no rocket science — provided that DNS, time and idmap configuration are right from the start. Invest 30 minutes in preparation and you’ll save yourself hours of troubleshooting later with Kerberos timeouts or lost permissions. In particular, plan the idmap range generously, as later corrections can devalue existing ACLs.

DATAZONE supports you in planning, migration and operation of your TrueNAS file servers — from the initial domain join to integration into complex multi-site forests. Get in touch: Contact us.