Setting Up Directory Services

The SCALE Directory Services section contains options to edit directory domain and account settings, set up Idmapping, and configure authentication and authorization services in TrueNAS SCALE.

When setting up directory services in TrueNAS, you can connect TrueNAS to either an Active Directory or an LDAP server.

The Active Directory (AD) service shares resources in a Windows network. AD provides authentication and authorization services for the users in a network, eliminating the need to recreate the user accounts on TrueNAS.

Once joined to an AD domain, you can use domain users and groups in local ACLs on files and directories. You can also set up shares to act as a file server.

Joining an AD domain also configures the Privileged Access Manager (PAM) to let domain users log on via SSH or authenticate to local services.

Users can configure AD services on Windows or Unix-like operating systems using Samba version 4.

To configure an AD connection, you must know the AD controller domain and the AD system account credentials.

Users can take a few steps before configuring Active Directory to ensure the connection process goes smoothly.

To confirm that name resolution is functioning, go to System Settings > Shell and use ping to check the connection to the AD domain controller.

When TrueNAS sends and receives packets without loss, the connection is verified. Press Ctrl + C to cancel the ping.

Another option is to use host -t srv _ldap._tcp.domainname.com to check the network SRV records and verify DNS resolution.

Active Directory relies on the time-sensitive Kerberos protocol. TrueNAS adds the AD domain controller with the PDC Emulator FSMO Role as the preferred NTP server during the domain join process. If your environment requires something different, go to System Settings > General and add or edit a server in the NTP Servers window.

The local system time cannot be out of sync by more than five (5) minutes with the AD domain controller time in a default AD environment. Use an external time source when configuring a virtualized domain controller. TrueNAS generates alerts if the system time gets out-of-sync with the AD domain controller time.

TrueNAS has a few options to ensure both systems are synchronized:

1. Go to System Settings > General and click Settings in the Localization window to ensure the Timezone matches the AD Domain Controller.

2. Set either local time or universal time in the system BIOS.

To connect to Active Directory, click Settings in the Active Directory window and enter the AD Domain Name and account credentials. Set Enable to attempt to join the AD domain immediately after saving the configuration.

TrueNAS offers advanced options for fine-tuning the AD configuration, but the preconfigured defaults are generally suitable.

When the import is complete, AD users and groups become available while configuring basic dataset permissions or an ACL with TrueNAS cache enabled (enabled by default).

Joining AD also adds default Kerberos realms and generates a default AD_MACHINE_ACCOUNT keytab. TrueNAS automatically begins using this default keytab and removes any administrator credentials stored in the TrueNAS configuration file.

truenas# midclt call activedirectory.domain_info | jq
{
  "LDAP server": "192.168.1.125",
  "LDAP server name": "DC01.HOMEDOM.FUN",
  "Realm": "HOMEDOM.FUN",
  "Bind Path": "dc=HOMEDOM,dc=FUN",
  "LDAP port": 389,
  "Server time": 1593026080,
  "KDC server": "192.168.1.125",
  "Server time offset": 5,
  "Last machine account password change": 1592423446
}

TrueNAS has an Open LDAP client for accessing the information on an LDAP server. An LDAP server provides directory services for finding network resources like users and their associated permissions.

Go to Credentials > Directory Services and click Configure LDAP.

Enter your LDAP server hostname, then enter your LDAP server Base and Bind domain names and the bind password. Check the Enable box to activate the server, then click Save.

To further modify the LDAP configuration, click Advanced Options. See the LDAP UI Reference article for details about advanced settings.

If the AD or LDAP cache becomes out of sync or fewer users than expected are available in the permissions editors, resync the cache using the Rebuild Directory Service Cache.

To view Idmap and Kerberos Services, click Show next to Advanced Settings.

The Idmap directory service lets users configure and select a backend to map Windows security identifiers (SIDs) to UNIX UIDs and GIDs. Users must enable the Active Directory service to configure and use Identity Mapping (Idmap).

Users can click Add in the Idmap window to configure backends or click on an already existing Idmap to edit it.

TrueNAS automatically generates an Idmap after you configure AD or LDAP.

Kerberos is a web authentication protocol that uses strong cryptography to prove the identity of both client and server over an insecure network connection.

Kerberos uses “realms” and “keytabs” to authenticate clients and servers. A Kerberos realm is an authorized domain that a Kerberos server can use to authenticate a client. By default, TrueNAS creates a Kerberos realm for the local system. A keytab (“key table”) is a file that stores encryption keys for authentication.

TrueNAS SCALE allows users to configure general Kerberos settings, as well as realms and keytabs.

Users can configure Kerberos settings by navigating to Directory Services and clicking Settings in the Kerberos Settings window.

Users can configure Kerberos realms by navigating to Directory Services and clicking Add in the Kerberos Realms window.

Enter the Realm and Key Distribution (KDC) names, then define the Admin and Password servers for the Realm.

TrueNAS automatically generates a Realm after you configure AD or LDAP.

Kerberos keytabs let you join an Active Directory or LDAP server without a password.

TrueNAS automatically generates a Keytab after you configure AD or LDAP.

Since TrueNAS does not save the Active Directory or LDAP administrator account password in the system database, keytabs can be a security risk in some environments.

When using a keytab, create and use a less-privileged account to perform queries. TrueNAS will store that account’s password in the system database.

To create a keytab on a Windows system, use the ktpass command:

ktpass.exe /out file.keytab /princ http/user@EXAMPLE.COM /mapuser user /ptype KRB5_NT_PRINCIPAL /crypto ALL /pass userpass

• file.keytab is the file to upload to the TrueNAS server.
• user is the user account name for the TrueNAS server generated in Active Directory Users and Computers.
• http/user@EXAMPLE.COM is the principal name written in the format host/user.account@KERBEROS.REALM. The Kerberos realm is usually in all caps, but be sure to match the Kerberos Realm case with the realm name. See this note about using /princ for more details.
• userpass is the user’s password.
• /crypto is the cryptographic type.

Setting /crypto to ALL allows using all supported cryptographic types. You can use specific keys instead of using ALL:

• DES-CBC-CRC is backward compatible.
• DES-CBC-MD5 adheres more closely to the MIT implementation and is backward compatible.
• RC4-HMAC-NT uses 128-bit encryption.
• AES256-SHA1 uses AES256-CTS-HMAC-SHA1-96 encryption.
• AES128-SHA1 uses AES128-CTS-HMAC-SHA1-96 encryption.

After generating the keytab, go back to Directory Services in TrueNAS and click Add in the Kerberos Keytab window to add it to TrueNAS.

To make AD use the keytab, click Settings in the Active Directory window and select it using the Kerberos Principal drop-down.

When using a keytab with AD, ensure the keytab username and userpass match the Domain Account Name and Domain Account Password.

To make LDAP use a keytab principal, click Settings in the LDAP window and select the keytab using the Kerberos Principal drop-down.