Section 10.2. Domain and ADS Security Modes

10.2. Domain and ADS Security Modes

Samba provides two modes of operating within a domain, security = domain and security = ads. Both allow Samba to leverage the central authentication service provided by domain controllers. Both modes support the NTLM and NTLMv2 authentication protocols. The ads mode, however, also provides support for Kerberos authentication, but domain does not. A good rule of thumb is to select the ads method if you are joined to an AD domain, regardless of whether the domain runs in mixed or native mode.

If you plan to configure Samba for security = ads, remember to follow the instructions given in Chapter 2 to verify that your Samba installation does in fact possess support for Kerberos, LDAP, and Active Directory. There are no such external software dependencies for enabling domain security; this mode is always provided.

10.2.1. security = domain

Joining a Samba host using security = domain involves two steps:

Define the domain and member server settings for your environment in smb.conf.
Establish the machine account credentials by joining the domain.

The first parameter to set is the security option. Start by defining domain mode security in the [global] section of smb.conf:

 [global]     security = domain

Supporting password encryption is a requirement for member servers, so you should set it explicitly, even though it is enabled by default:

     encrypt password = yes

Finally, specify the name of the domain to which your server will belong. Samba, like Windows, reuses the workgroup parameter for this setting. Here, we are joining the GLASS Windows NT 4.0 domain:

     workgroup = GLASS

Once smb.conf has been configured, use the net command to establish the server's credentials in the domain. You need a user account that is properly authorized to join your server to the domain.^[*] When in doubt, an account that is a member of the Domain Admins group will always work. Next, run the net join command from a root shell to join the domain, using the -U option to define the connecting user name:

^[*] Domain Administrators can grant rights or privileges to users to join a specific host or a collection of hosts to the domain.

 $ net join -U Administrator Administrator's password: <enter password for Administrator> <...intermediate output deleted...> Joined domain GLASS.

If you are greeted by the "Joined domain ..." message, net was able to successfully establish the machine account credentials and your server is now a part of the domain. If not, there are three common reasons why this process may fail, described next.

First, if you receive the following message, make sure that you entered the correct user name and password:

 Could not connect to server XXX The username or password was not correct.

Second, if you entered the correct credentials but the account does not possess the sufficient rights to join the server to domain, you will receive this error message:

 error setting trust account password: NT_STATUS_ACCESS_DENIED Unable to join domain XXX.

The third common error is the inability to locate a DC for the domain specified in smb.conf. This error is signaled by the following message:

 Unable to find a suitable server

This situation is frequently caused by a mistyped name, so verify your smb.conf settings before proceeding. If your configuration is correct, it could be that this error is caused by a name service failure. We cover how Samba attempts to locate domain controllers shortly.

If you are joining a Samba domain, you may encounter the additional following error:

 Creation of workstation account failed

This error is normally caused by some failure in the add machine script. Or possibly the script succeeded, but smbd is unable to locate the Unix account it created, a situation frequently caused by running the Name Service Cache Daemon (nscd) on the Samba DC. To resolve this problem, ensure that the DC's /etc/nsswitch.conf file is set up correctly, that the add machine script did in fact create the trust account, and that nscd is using up-to-date information.

You can verify your server's trust account at any time by running this command:

 $ net rpc testjoin Join to 'GLASS' is OK

10.2.2. security = ads

From the perspective of an end user, a server configured to use ads security behaves identical to one using domain security. From our perspective as administrators, the additional Kerberos support provided by the ads method is made apparent by the extra configuration steps necessary to join a domain. Instead of the two steps described for security = domain, this time there are four to complete:

Define the domain and member server settings for your environment in smb.conf.
Synchronize the server's clock with the domain controller.
Configure the Kerberos client library and DNS resolver settings.
Establish the machine account credentials by joining the domain.

10.2.2.1. Basic Samba settings

Once again, we start with configuring the server's smb.conf file. Our initial file defines ads security and includes the required encrypted password support:

 [global]     security = ads     encrypt passwords = yes

Next, include the realm of the AD domain. In Active Directory domains, the Kerberos realm is the same as the uppercase version of the domain's DNS name.^[*] So the AD domain blue.plainjoe.org is defined as:

^[*] In pure Kerberos 5 implementations, the realm and DNS domain are not required to match. However, Active Directory consolidates the two into a single name when running dcpromo.exe.

 realm = BLUE.PLAINJOE.ORG

The workgroup parameter specifies the short name of the domain, which is commonly the same as the first portion of the realm name. However, this setup is not guaranteed. If you define the wrong value, the net tool complains when it joins the domain and reminds you to set the correct value. In our example, the short domain name is the first component of the realm name, so we specify the workgroup as follows:

 workgroup = BLUE

10.2.2.2. Time synchronization

Time synchronization is a prerequisite for Kerberos authentication. Therefore, Microsoft chooses to make all AD domain controllers act as time servers. Non-Microsoft clients can synchronize their system clocks with an AD DCs by using version 4 of the Simple Network Time Protocol (SNTP). The ntpdate tool, included in the NTP distribution from http://www.ntp.org, can synchronize the server's local clock with an AD DC. Most systems already have some form of the NTP tools included.

Kerberos Terminology 101

For the purposes of our discussion, understanding some basic terminology can be helpful to map Kerberos concepts onto Active Directory functionality:

Principal: A user or computer in a Kerberos authentication database (e.g., a user or computer object in AD).
Realm: A collection of Kerberos principals. In AD, this is the same as the DNS domain.
Ticket Granting Ticket (TGT): An encrypted blob of data issued to a principal, which can be used to requests tickets to other principals.
Service Ticket: An encrypted blob of data that can be used to access application services such as a mail, web, or file server.
Key Distribution Center (KDC): The Kerberos database server.
Authentication Server (AS): The service responsible for issuing TGTs.
Ticket Granting Service (TGS): The service responsible for issuing service tickets.
Secret Key: The hashed version of a principal's passphrase. This is also referred to as the long-term key, because it does not expire or change based on an individual session.
Session Key: A short-term key valid only for the life of a specific application session or Kerberos ticket. Windows 2000 and later systems use this key to encrypt certain communications between clients and servers.

In most implementations, Microsoft and Unix alike, the KDC, AS, and TGS are all implemented in the same service, although each has a logically separate function. An AD domain controller fulfills all three of these roles. Frequently, the term KDC is used to refer to the KDC+AS+TGS server.

To set your server's clock to match the time on the domain controller named bluedc1.blue.plainjoe.org, run the following command as root:

 $ ntpdate bludc1.blue.plainjoe.org 17 Jun 12:46:46 ntpdate[16773]: step time server 192.168.1.148 offset 8.734885 sec

If you receive the error message, "no server suitable for synchronization found," confirm that the hostname used is valid and reachable. If the name is correct, an administrator of the DC (possibly you) must verify the w32time.exe service. More information about Active Directory and time synchronization can be found by searching http://support.microsoft.com for the keyword "w32time.exe."

The ntpdate command can be run periodically as a cron job to prevent the Samba server's clock from drifting. Another option is to run the ntpd daemon and have it synchronize the local clock on a continuing basis. To use this method, specify the domain controllers using a server line in /etc/ntp.conf and then have the daemon started as part of the system boot process. More on configuring NTP clients can be found in the book Essential System Administration, by Æleen Frisch (O'Reilly).

10.2.2.3. Encryption types

The next item on the list is to configure the server's Kerberos client libraries, which Samba will use to validate user connections. Although this process can vary slightly depending the Krb5 distribution you are using, either Heimdal or MIT, thankfully the configuration files used by the two implementations are extremely compatible with each other. By default, both distributions use the file /etc/krb5.conf to define client-side settings. The options of interest are what encryption types the client supports and how it locates a KDC for a given realm.

Active Directory realms implement three Krb5 encryption types:

RC4-HMAC
DES-CBC-MD5
DES-CBC-CRC

AD domain controllers always prefer the strongest encryption algorithm for which a principal has assigned keys. The most secure encryption type in our list is RC4-HMAC. Remember from Chapter 2 that this new encryption type is supported in open source Kerberos distributions beginning only with MIT krb5 1.3 and with Heimdal 0.6.1. Krb5 authentication still works on systems with older Kerberos libraries such as RedHat Enterprise Linux 3, but only DES keys will be available.

We limit the client libraries to use the same list of encryption types supported by Microsoft. This is important, because by default, Unix Kerberos implementations prefer the Advanced Encryption Standard (AES) or triple-DES (3DES) methods, which are not currently supported by Windows domain controllers. There are several points during Krb5 communications where an encryption type mismatch can cause failure. If the Samba server cannot decrypt a user's ticket, that user cannot be authenticated. To be safe, we use a single list for obtaining TGTs, service tickets, and any session-key-based encryption that may be performed by adding three options (default_tgs_enctypes, default_tkt_enctypes, and preferred_enctypes) to the [libdefaults] section of krb5.conf.

 [libdefaults]     default_tgs_enctypes = RC4-HMAC DES-CBC-MD5 DES-CBC-CRC     default_tkt_enctypes = RC4-HMAC DES-CBC-MD5 DES-CBC-CRC     preferred_enctypes   = RC4-HMAC DES-CBC-MD5 DES-CBC-CRC

10.2.2.4. Realm/domain and KDC lookups

Next, we define the client library's default realm, just as we did in smb.conf. This realm is used whenever the Krb5 libraries are given an unqualified principal name. For example, if asked to retrieve a TGT for the user Administrator, Krb5 uses the principal Administrator@BLUE.PLAINJOE.ORG. The default realm also goes in krb5.conf's [libdefaults] section:

     default_realm = BLUE.PLAINJOE.ORG

Finally, we have to make a choice concerning how the Krb5 libraries will locate a KDC for a realm. The simplest means is to use the same DNS service as the AD domain. The reasoning behind this recommendation is that there is no need to duplicate information that Active Directory already maintains. If you find that KDC DNS lookups are not available on your platform or if you do not wish to use them, you must manually configure the KDC addresses in krb5.conf. We'll show both methods in the following sections.

10.2.2.4.1. Using DNS for KDCs lookups

The goal of this configuration is to enable the Kerberos client libraries to find a KDC by generating a query to the DNS server. If you configure the use of DNS, a request to contact a KDC for a realm results in DNS SRV lookups for _kerberos._udp.<domain> or _kerberos._tcp.<domain>. For example, locating a KDC in the realm BLUE.PLAINJOE.ORG results in a DNS query for the SRV record _kerberos._udp.blue.plainjoe.org. Lookups for the corresponding TCP record result when the Krb5 replies are too large for UDP and must be retried over TCP.

The Heimdal Kerberos client implementation has always supported locating KDC via DNS SRV lookups. The MIT distribution has also possessed support for several releases, but did not enable the feature by default until the 1.4 release. DNS queries for KDCs can be enabled in older version of MIT Kerberos by defining the KRB5_DNS_LOOKUP and KRB5_DNS_LOOKUP_KDC preprocessor macros at compile time.

To configure the Kerberos libraries for DNS lookups, first configure /etc/resolv.conf to point to the DNS servers used by the AD clients and servers. Also be sure to set the DNS search suffix to the name of the AD domain. For our example, the DNS servers for the blue.plainjoe.org domain are at 192.168.1.101 and 192.168.2.101, which gives us the following resolv.conf file:

 search blue.plainjoe.org nameserver 192.168.1.101 nameserver 192.168.2.101

The only other step is to instruct the Krb5 libs to query DNS for the name and address of KDCs by enabling the dns_lookup_kdc option in the [libdefaults] section:

     dns_lookup_kdc = true

10.2.2.4.2. Manually configuring KDCs lookups

Although we recommend the use of AD for lookups whenever possible, as shown in the previous section, you can instead configure KDC addresses manually in krb5.conf. To do so, add a section for each realm that may be contacted in the [realms] section. Assuming that we have no trusted domains, a single entry for BLUE.PLAINJOE.ORG will suffice.

In this example, we have one KDC named bluedc1.blue.plainjoe.org. Multiple KDCs may be specified by including additional kdc lines in the realm's configuration.

 [realms]     BLUE.PLAINJOE.ORG = {         kdc = bluedc1.blue.plainjoe.org     }

10.2.2.5. Final steps

Before moving a client to the final stage of joining the AD domain, it is a good idea to verify that the Kerberos client configuration is functioning properly. The easiest way to do this is to use kinit to obtain a TGT for an existing domain user. Our example uses the built-in Administrator account:

 $ kinit Administrator Password for Administrator@BLUE.PLAINJOE.ORG: <password for Administrator>

The MIT variant of kinit does not provide any feedback unless the TGT request is unsuccessful. Heimdal's kinit indicates success by providing the maximum lifetime of the obtained TGT. Regardless of the Krb5 distribution used, it is possible to view the current ticket cache using the klist command:

 $ klist Default principal: Administrator@BLUE.PLAINJOE.ORG Valid starting     Expires            Service principal 06/18/06 20:49:03  06/19/06 06:49:05  krbtgt/BLUE.PLAINJOE.ORG@BLUE.PLAINJOE.ORG         renew until 06/19/06 20:49:03

The command output proves that we have obtained a TGT for Administrator by listing the ticket for the principal krbtgt/BLUE.PLAINJOE.ORG@BLUE.PLAINJOE.ORG, the standard principal name given to the Kerberos authentication server for our realm.

There are a few errors that can commonly occur at this stage. The most common errors and potential solutions are:

Unable to locate a KDC for the requested realm: The client was unable to determine a KDC for the principal's realm. Verify that the default_realm value in krb5.conf is spelled correctly. If so, verify that either the kdc parameter is specified for the realm in the [realms] section or dns_lookup_dns is enabled in [libdefaults]. When using DNS SRV queries to locate a KDC, use either nslookup or the host utility to confirm that the SRV record for the _kerberos._udp hostname is resolvable in the domain.
KDC has no support for encryption type while getting initial credentials: Verify that the list of supported encryption types in /etc/krb5.conf includes RC4-HMAC. If you are using an older version of Kerberos libraries that do no support this encryption type, it is recommended that you upgrade your Kerberos libraries if possible. However, you may be able to work around the error by changing the Administrator's password once to generate the user's necessary DES Krb5 keys.
Preauthentication failed: Confirm that you are entering the correct password for the user's account.
Clock skew too great: By default, all AD domain controllers require that the clocks on both clients and servers are within five minutes of each other. Go back and resync the system's time to match that of the DC.

Once you have confirmed a working Krb5 client installation, the existing ticket cache should be cleared using the kdestroy command. This command prevents the net command from ignoring the user credentials that are entered on the command line. Both the Heimdal and MIT implementation of this tool return directly to a command prompt upon success with no additional messages.

With all the preliminary steps completed, it is now time to perform the net join. The command-line arguments are identical to the ones used to join using security = domain; once again, this command must be run as root:

 $ net join -U Administrator Administrator's password: <enter password for Administrator> Using short domain name - BLUE Joined 'OAK' to realm 'BLUE.PLAINJOE.ORG'

Any failures during the join process can usually be traced to Kerberos errors or net failures, both of which have been previously discussed. If you have misspelled or omitted the workgroup in smb.conf, the join process may succeed, but will inform you of an error. Make sure to correct this mistake in smb.conf:

 The workgroup in smb.conf does not match the short domain name obtained from the server. Using the name [BLUE] from the server. You should set "workgroup = BLUE" in smb.conf. Using short domain name - BLUE

We can verify our machine account at any time in AD by running the following command:

 $ net ads testjoin Join is OK

10.2.2.6. Integrating Kerberized Unix services

Even before its adoption by Microsoft, Kerberos always supported machine principals. For example, an SSH server may use the principal name host/machine.example.com, and an LDAP directory server may use ldap/machine.example.com. These are different principals even though they are hosted by the same machine. The secret keys for these service principals are stored in a keytab file (usually /etc/krb5.keytab). In AD domains, these secret keys are derived from the machine trust account password.

Samba will manage a server's keytab file if the use kerberos keytab option is enabled in smb.conf:

 [global]     use kerberos keytab = yes

If this parameter is enabled when joining the domain, the net join command creates the keytab file automatically. If you decide to make use of a keytab file after the member server has been configured, you can create a keytab file by using the net ads keytab command. The create subcommand generates initial entries for the host/machine principal. This command must be run as root, because it requires access to Samba's secrets.tdb file and must be able to write the keytab records to /etc/krb5.keytab:

 $ net ads keytab create -P

It is possible to define a custom location for the keytab file by defining the KRB5_KTNAME environment variable.

New service principals can be added to the machine's account in AD and to the keytab file using net ads keytab add. All that is needed is the principal (service) name, not the full principal/instance syntax. The -P option uses the machine account and prevents you from having to enter user credentials. For example, to add a keytab entry for the HTTP/machine.example.com service principal used by Apache kerberos modules, we would execute:

 $ net ads keytab add HTTP -P Processing principals to add...

This command adds a new servicePrincipalName to the server's account in AD and stores the new key in the local keytab file. Tables 10-1 and 10-2 summarize the keytab-related parameters and tools covered in this section.

Table 10-1. Keytab-related parameters
Parameter	Value	Description	Default	Scope
`use kerberos keytab`	boolean	Enables Samba's keytab management functionality.	`no`	Global

Table 10-2. net ads keytab management options
Command	Description
`add`	Adds a new service principal value for the server's machine account.
`create`	Generates a keytab file based on the existing service principal values associated with the server in AD.
`flush`	Removes all entries from the keytab file.

10.2.3. Locating a Domain Controller

In default configurations, Samba attempts to automatically find domain controllers for any domain that it must contact. These auto lookups rely heavily on network name services. Remember that the order in which these services are queried is controlled by the name resolve order global option.

When configured for security = domain, NetBIOS name services are used to resolve the DOMAIN<0x1b> name when searching for the PDC and the DOMAIN<0x1c> name when any DC will do. Thus, unless the server will communicate only with domain controllers on its own subnet, Samba must be configured to use the WINS server (or servers) for the domain.

In an Active Directory domain, Samba is able to use DNS, just as Windows 2000 and later clients do. If the DNS lookup fails to return one or more domain controller names, Samba may fall back to NetBIOS name queries, much as it did when using domain mode security, assuming that the disable netbios parameter has not been enabled.

Prior to the 3.0.23 release, Samba queried for the SRV record _ldap._tcp.<domain> when searching for an AD domain controller. Beginning with 3.0.23, Samba searches for the _ldap._tcp.dc._msdcs.<domain> record, just as Windows clients do.

You can exert a little more control over which domain controller is used by Samba for its own domain by setting the global password server option. This parameter accepts a list of one or more domain controllers using the standard smb.conf delimiters (whitespace or commas). Names of these preferred DCs can be NetBIOS names, hostnames, or fully qualified DNS names, but they must be resolvable to an address. For instance, to restrict Samba to using the domain controllers named dc1 and dc2, add the following line to the server's smb.conf file:

     password server = dc1 dc2

Samba attempts to contact the host at dc1 first and continues to contact dc2 only if the first server cannot be contacted. As long as dc1 is available, dc2 is not used. Adding the wildcard character (*) to the list instructs Samba to include any domain controllers found using its internal auto lookup support. This means you can use a local DC, but still fall back to any DC, should the preferred DC become unavailable.

NetBIOS: Rest in Peace

It is feasible to remove NetBIOS from your network, but only when operating in an AD environment. Even then, many administrators find it very difficult to remove all applications that have a dependency on some piece of this legacy protocol. However, if you are feeling adventurous, Microsoft operating systems, starting with Windows 2000, can be configured to drop all support for NetBIOS by relying on DNS for name services and using TCP and UDP for the transport protocols. In order to configure Samba to behave the same way, define the following group of parameters:

 [global]     smb ports = 445     disable netbios = yes     name resolve order = hosts

At this point, there is no reason to support network browsing, either, because it does not function properly without the presence of NetBIOS name services. So there is no reason to run the nmbd daemon at all, as it is responsible only for NetBIOS name registrations, acting as a WINS server, and participating in browsing elections.

A word of caution before moving on. It is frequently better to allow Samba to find a domain controller on its own. As with most parameter values, developers work extremely hard to make Samba robust and efficient. In some cases, it is necessary to manually specify the DC that your server will use, but it is recommended that you do this only as a last resort.

Table 10-3 concludes this section by giving a brief listing of the parameters recently covered.

Table 10-3. Domain controller location parameters
Parameter	Value	Description	Default	Scope
`disable netbios`	boolean	Controls Samba use of NetBIOS name services.	`no`	Global
`password server`	list	List of domain controllers Samba should prefer when operating as a member server.	`*`	Global