Directory Services
14 minute read.
Last Modified 2022-04-07 16:08 EDTThe 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 running Samba version 4.
To configure a connection, you will need to know the Active Directory domain controller’s domain and that system’s 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’s 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 creates an alert 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:
- Go to System Settings > General and click Settings in the Localization window to ensure the Timezone matches the AD Domain Controller.
- Set either localtime 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 has an Open LDAP client for accessing the information on an LDAP server. An LDAP server provides directory services for finding network resources such as users and their associated permissions.
To integrate an LDAP server with TrueNAS, go to Credentials > Directory Services and click Settings in the LDAP window.
Field | Description |
---|---|
Hostname | LDAP server hostnames/IP addresses. Separate entries with Space. You can enter multiple hostnames/IP addresses to create an LDAP failover priority list. If a host does not respond, TrueNAS will try the next host until it establishes a connection. |
Base DN | Top level of the LDAP directory tree to be used when searching for resources. Example: dc=test,dc=org. |
Bind DN | Administrative account name on the LDAP server. Example: cn=Manager,dc=test,dc=org. |
Bind Password | Password for the Bind DN. |
Enable | Activates the configuration. Unset to disable the configuration without deleting it. You can re-enable it later without reconfiguring it. |
If the 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.
Field | Description |
---|---|
Idmap Backend | Provides a plugin interface for Winbind to use varying backends to store SID/uid/gid mapping tables. The correct setting depends on the environment you deployed the NAS in. |
Name | Enter the pre-Windows 2000 domain name. |
DNS Domain Name | DNS name of the domain. |
Range Low | Range Low and Range High set the range of UID/GID numbers the IDMap backend translates. If an external credential like a Windows SID maps to a UID or GID number outside this range, TrueNAS will ignore it. |
Range High | Range Low and Range High set the range of UID/GID numbers the IDMap backend translates. If an external credential like a Windows SID maps to a UID or GID number outside this range, TrueNAS will ignore it. |
SSSD Compat | Generate Idmap low range based on the same algorithm that SSSD uses by default. |
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.
Field | Description |
---|---|
Appdefaults Auxiliary Parameters | Additional Kerberos application settings. See [appdefaults] in krb.conf(5) for settings and usage syntax. |
Libdefaults Auxiliary Parameters | Additional Kerberos library settings. See [libdefaults] in krb.conf(5) for settings and usage syntax. |
Users can configure Kerberos realms by navigating to Directory Services and clicking Add in the Kerberos Realms window.
Field | Description |
---|---|
Realm | Enter the name of the realm. |
KDC | Enter the name of the Key Distribution Center. Separate multiple values by pressing Enter. |
Admin Server | Define the server that performs all database changes. Separate multiple values by pressing Enter. |
Password Server | Define the server that performs all password changes. Separate multiple values by pressing Enter. |
Kerberos keytabs let you join an Active Directory or LDAP server without a password.
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 the 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 formathost/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 theuser
’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.