AD Integration — Client Authentication

KeyServer supports client access based on external authentication sources like Active Directory.

To enable single sign-on for users, some additional configuration is required depending on the Client Authentication settings of KeyServer. Note that most sites will not require users to authenticate their KeyAccess client sessions. When referring to users logging in to the Web UI, that is handled by Admin Authentication (even if they do not get admin rights). The main use for Client Authentication is automatic mapping of Computers into Divisions based on AD OU structure.

If you plan on using AD accounts for KeyServer Administration accounts you might want to set that up first (see Active Directory Integration — Admin Authentication). Setting up Active Directory authentication for admins will cover all of the steps in this document, other than actually selecting Active Directory for client authentication (the last step below).

If you are running KeyServer on a non-Windows host, or if your Kerberos servers are Unix based, the configuration steps will be slightly different from what is described below.

Authentication Method

The Active Directory authentication module presents three choices for how passwords will be verified. This choice determines what additional configuration might be needed.

Secure Authentication

When the “Use Secure Authentication” option is chosen in the Client Authentication setup dialog, no additional configuration is required. Users' passwords will be transmitted to KeyServer using a secure “key exchange” mechanism. Some considerations when using this option are that is does not use standardised security protocols, and the user passwords will be known to both the KeyReporter process and the KeyServer process.

If you choose this option, no additional configuration is needed, and you do not need to read further in this document. However, you still need to set up the Active Directory authentication module as described in Authentication methods (you can also follow the instructions in this document so it is easier to switch to the Kerberos option in the future).

NTLM Authentication

Windows NTLM authentication is a legacy mechanism that is only supported on Windows clients. If you have non-Windows clients that need access to KeyServer, choose either the “Use Secure Authentication” or the “Use Kerberos Authentication” option.

Kerberos Authentication

This option enables "single sign-on", where a KeyServer user only needs to provide credentials (name and password) once, and will be able to connect with network services without further prompts. It requires some additional configuration on the host running KeyServer and possibly on the Active Directory server.

The remainder of this documentation describes the configuration changes that are required in order to enable Kerberos authentication for client access.

Setting up Kerberos

Preliminary Checks

Let's assume KeyServer will run on the host named “server.ad.sample.net” and you have a domain controller on “pdc.ad.sample.net”. Note that the various names chosen for this example are mostly arbitrary, but follow typical conventions for Kerberos. You can use whatever names make sense as long as you use them consistently.

It is vital that your DNS is properly configured so that the host running KeyServer has the name “server.ad.sample.net” (or whatever you choose), and that this name is used when connecting to KeyServer.

You can use the nslookup command to check that the DNS is set up as needed. In a command prompt window type the command:

C:\> nslookup server.ad.sample.net
Server:  ad.sample.net
Address:  192.168.0.1

Name:    server.ad.sample.net
Address:  192.168.0.42

The addresses and DNS server will be different, but what you are looking for is that the name “server.ad.sample.net” has the correct address. Also, the results should list “server.ad.sample.net” as the Name, not as an Alias. Next, using the address of the KeyServer host (192.168.0.42 in this example), type the command:

C:\> nslookup 192.168.0.42
Server:  ad.sample.net
Address:  192.168.0.1

Name:    server.ad.sample.net
Address:  192.168.0.42

The result should be the same as before. Most importantly, the Name should be “server.ad.sample.net”.

In order for KeyServer to accept Kerberos tickets for authentication, a Kerberos principal (aka “service principal name” or SPN) must be configured for the KeyServer host. This value will be associated with an account that we will create, so it can't already be present for the host.

To check if the SPN is already present, use a tool like ldp or ldapsearch. For example, using ldp make a connection to your AD, bind to it using an account with sufficient privileges, the choose Search from the Browse menu. Enter the appropriate Base DN, and for the filter use “(servicePrincipalName=KEYSERVER/server.ad.sample.net)” as shown below (for older versions of ldp, set the Attributes field in the Options sub-dialog).

Click the Run button in the Search window and you will see the search results in the main window. There should be no matching entries, so you should see output like this:

***Searching...
ldap_search_s(ld, "DC=ad,DC=sample,DC=net", 2, "(servicePrincipalName=KEYSERVER/server.ad.sample.net)", attrList,  0, &msg)
Getting 0 entries:
-----------

If there is already an account with the SPN we need, you will see output like this:

***Searching...
ldap_search_s(ld, "DC=ad,DC=sample,DC=net", 2, "(servicePrincipalName=KEYSERVER/server.ad.sample.net)", attrList,  0, &msg)
Getting 1 entries:
Dn: CN=Some Account,CN=Users,DC=ad,DC=sample,DC=net
sAMAccountName: someacct;
servicePrincipalName: KEYSERVER/server.ad.sample.net;
-----------

In this case you must either choose a different host, or delete the SPN from the existing account using setspn like this (you must give the sAMAccountName value in this command, not the display name):

C:\> setspn -D KEYSERVER/server.ad.sample.net someacct
Unregistering servicePrincipalNames for CN=Some Account,CN=Users,DC=AD,DC=sample,DC=net
	KEYSERVER/server.ad.sample.net
Updated object

If you have ldapsearch installed on Windows or you have access to a Unix computer with this tool, you can use the following command instead of ldp:

[unix-prompt] ldapsearch -h pdc.ad.sample.net -b "dc=ad,dc=sample,dc=net" \
		-D "cn=account,cn=users,dc=ad,dc=sample,dc=net" -x -W \
		'(servicePrincipalName=KEYSERVER/server.ad.sample.net)' \
		servicePrincipalName sAMAccountName
Enter LDAP Password: hidden
# refldap://ad.sample.net/CN=Configuration,DC=ad,DC=sample,DC=net
no entries will be returned

Note that this will transmit your password over the network. Use the -Q option instead to perform a secure bind to AD when you have Kerberos credentials (see ldapsearch documentation for details).

Service Account

The KeyServer process should run in an AD account that we will create and configure. Commands that you type are in bold below.

— Open a command prompt window as a user with sufficient privileges to manage AD accounts
— Create an account in AD, e.g. "KSServiceAccount", and give it a strong password, e.g. "x3oM.8pv@Eud"

C:\> net user KSServiceAccount x3oM.8pv@Eud /ADD /COMMENT:"KeyServer service account"

— Run the setspn command to add the KEYSERVER SPN:

C:\> setspn -A KEYSERVER/server.ad.sample.net KSServiceAccount
Registering servicePrincipalNames for CN=KSServiceAccount,CN=Users,DC=AD,DC=sample,DC=net
	KEYSERVER/server.ad.sample.net
Updated object

The account must also have the ability to use delegated Kerberos tickets. To enable this privilege, check the option “Trust this user for delegation to any service” box in the Delegation tab of the account's Properties window:

In older versions of Windows, check the “Account is trusted for delegation” box in the Account tab of the account's Properties window.

Note that any user account that will be used with KeyServer must be delegatable. Accounts are delegatable by default, but to be sure, you can verify that the “Account is sensitive and cannot be delegated” box in the account's Properties window is not checked.

Now that the account is created, KeyServer must be set up to run within that account. First make sure KeyServer is not running. Use the Services control panel, or run this command:

C:\> net stop KeyServer
The KeyServer service is stopping.
The KeyServer service was stopped successfully.

KeyServer must be given access to its executable and its data files. Use Windows Explorer or a command prompt as follows to grant access. The command below assumes that KeyServer has been installed in the default location.

For pre-2008 Windows Systems:

C:\> cacls "c:\Program Files (x86)\Sassafras K2\Server" /e /t /g KSServiceAccount:F

For 2012 and newer Windows Systems:

C:\> icacls "c:\Program Files\Sassafras K2\Server" /grant KSServiceAccount:F /t

Finally, open the Services control panel, open the Properties window for KeyServer, and click the Log On tab. Configure the service account as below, using the password you gave when creating the account:

Start the KeyServer service in the Services control panel or by typing the command “net start KeyServer”. If you see an error starting the service, check that the account password is correct, and check that the file permissions were properly modified.

Authentication settings

Now that the service account is configured and KeyServer is running within that account, launch KeyConfigure and logon as the KeyServer Administrator account. From the Config Menu choose Client Authentication. In the Method pop-up menu choose Active Directory. If all the above configuration has been successful you should not need to change any of the default settings, except to make sure that "Use Kerberos Authentication" is selected:

The AD Host, AD Login, and AD Password values can be left blank, and KeyServer will use the permissions it has by virtue of running in the KSServiceAccount that you set up. The Principal field can be left blank, and KeyServer will use the default KEYSERVER/server.ad.sample.net. If your AD is a tree or forest, you should check the option “Connect to Global Catalog” for best performance. See the AD Authentication documentation for more information.