AD Integration - Admin Authentication

KeyServer supports Admin Authentication based on external authentication sources like Active Directory, which can leverage SSO.

To allow external accounts access to KeyConfigure and the Web UI, the Admin Authentication must be configured, along with a role in Admin Access, and ACLs. The combination of setting an authentication source along with defining privileges and ACLs completes the chain of defining access and permissions. Note this means "administrator" includes any user authenticating to the Web UI regardless if they only achieve "guest" level access. 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 Admin Authentication setup dialog, no additional configuration is required. The admin password 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 admin password 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). You will also need to configure at least one role, as described in the Admin Authentication documentation.

NTLM Authentication

Windows NTLM authentication is a legacy mechanism that is only supported on Windows clients. Furthermore it does not support “credential delegation”, so it cannot be used for authentication from the browser to KeyServer via KeyReporter. Therefore, if you want to allow external admins to log in to KeyReporter, choose either the “Use Secure Authentication” or the “Use Kerberos Authentication” option.

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). You will also need to configure at least one role, as described in the Admin Authentication documentation.

Kerberos Authentication

This option enables "single sign-on", where a KeyServer administrator 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. Also, some browsers might require additional configuration, while other browsers do not support the functionality.

The remainder of this documentation describes the configuration changes that are required in order to enable Kerberos authentication to KeyServer from KeyConfigure and web browsers.

If you choose this option, computers running KeyConfigure must be members of the AD domain or forest, or must be configured to use your AD server as the Kerberos server. The same holds for computers used to access KeyReporter in a browser. Such configuration is outside the scope of this document.

Setting up Kerberos SSO

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 KeyReporter in a browser.

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 and KeyReporter to accept Kerberos tickets for authentication, two Kerberos principals (aka “service principal names” or SPNs) must be configured for the KeyServer host. These values will be associated with an account that we will create, so they can't already be present for the host.

To check if the SPNs are 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 to 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:
-----------

Use the same method to check that there is no HTTP SPN for the server host. For the filter, use “(servicePrincipalName=HTTP/server.ad.sample.net)” as shown below:

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=HTTP/server.ad.sample.net)", attrList,  0, &msg)
Getting 0 entries:
-----------

If there is already an account with one of the SPNs 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 (2): HTTP/server.ad.sample.net; KEYSERVER/server.ad.sample.net;

-----------

Likewise if the HTTP SPN is already assigned to an account:

***Searching...
ldap_search_s(ld, "DC=ad,DC=sample,DC=net", 2, "(servicePrincipalName=HTTP/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 (2): HTTP/server.ad.sample.net; 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

C:\> setspn -D HTTP/server.ad.sample.net someacct
Unregistering servicePrincipalNames for CN=Some Account,CN=Users,DC=AD,DC=sample,DC=net
	HTTP/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

— Run the setspn command again, to add the HTTP SPN:

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

The account must also have the ability to use delegated Kerberos tickets. The simplest way to enable this privilege is to check the option “Trust this user for delegation to any service” 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.

[PS-prompt] $acct = Get-ADUser -Identity KSServiceAccount
[PS-prompt] Set-ADUser KSServiceAccount -PrincipalsAllowedToDelegateToAccount $acct

[PS-prompt] Get-ADUser KSServiceAccount -Properties PrincipalsAllowedToDelegateToAccount

DistinguishedName                    : CN=KSServiceAccount,CN=Users,DC=ad,DC=sample,DC=net
...
PrincipalsAllowedToDelegateToAccount : {CN=KSServiceAccount,CN=Users,DC=ad,DC=sample,DC=net}
...

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 Admin 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 and Admin Authentication documentation for more information.

Admin Roles

The settings so far have made it possible for any user in your Active Directory to authenticate to KeyServer. Since it is unlikely that you want all AD users to be KeyServer administrators, you need to tell KeyServer which users are KS admins, and what those users are allowed to do. This is done through KeyServer Roles, which are created and managed in KeyConfigure's “Admin Access” window.

For this example we'll set up a Role that designates members of the AD group “KeyServer Admins” as full administrators of KeyServer. First, create a group named “KeyServer Admins” in your Active Directory and add a test user to that group (it would be simplest to add your AD account to this group so you can test that your setup works). This can be done in the Windows UI, or via the command line as follows (the command prompt window must be open as Administrator):

C:\> net group "KeyServer Admins" /ADD /COMMENT:"Designated administrators of KeyServer"
The command completed successfully.

C:\> net group "KeyServer Admins" "Your Account" /ADD
The command completed successfully.

Next run KeyConfigure and logon as Administrator. Open “Admin Access” from the Window menu, then right-click in the window and select “New Role”. Give this new role a name (you can use any name that makes sense to you, as long as it is not already the name of an existing role). In the Group field enter the name of the AD group you created, and in the Permissions panel click “Full”.

With that role created and saved, you can test the logon in KeyConfigure. First, exit KeyConfigure then run it again. This time, in the Logon dialog, enter your AD account name (presuming you added it as a member of the KeyServer Admins group), leave the Password field empty, and click OK. You should then see all of KeyConfigure's windows just as if you had logged in using the KS Administrator account.

Instead of specifying the name of an AD group that is associated with a Role, you can instead manually create External Accounts in KeyConfigure, and then associate them individually with different Roles. In this case, the external Authentication method is only used to check the password.

You can create more Roles for separate administrator tasks and assign different AD groups to those roles. See the Admin Access documentation for more information.

Web Browser Configuration

KeyServer uses the “Negotiate” authentication protocol, which is supported by most mainstream browsers. Depending on the browser there might be additional configuration steps or restrictions. Consult the browser documentation for the most accurate and up to date information.

Internet Explorer/Edge
The Windows computer on which Internet Explorer/Edge runs must be a member of the Domain that KeyServer runs in. Furthermore, the Security options need to allow single sign-on for the KeyServer host. In the Security tab of the Internet Options dialog, click Trusted Sites:

Then click the Sites button to bring up the list of defined trusted sites, and add the URL of your server (you should add both the http:// form and the https:// form of the URL):

Back in the Internet Options dialog click Custom Level..., which brings up the Security Settings for the Trusted Sites zone. Scroll to the end of the list and click the option “Automatic logon with current user name and password”:

Safari
The Mac OS X computer on which Safari runs must have Kerberos configured with information about the Active Directory server and domain (realm).

Firefox
When running on Windows, open a new window and enter “about:config” in the address bar. In the Search field, type “network.negotiate” and hit Enter. In the “network.negotiate-auth.trusted-uris” field, type the name of the KeyServer host, “server.ad.sample.net” in this example. Do the same for the “network.negotiate-auth.delegation-uris” field. If there are already values in these fields you can add new values by separating them with a comma.

When running on Mac OS X, Kerberos must be configured with information about the Active Directory server and domain (realm). It might also be necessary to edit the “about:config” fields as in the Windows case above.

Chrome, Opera, etc.
Consult the documentation for the browsers to determine their support for the Negotiate protocol (sometimes referred to as “SPNEGO”).

Troubleshooting

If you've followed the above steps and you cannot connect using an account from AD, here are some things to check:

— Try to connect in KeyConfigure using the AD account. If that does not work, you need to check the Admin Authentication settings and the Admin Access settings in KeyConfigure.

— Check the permissions granted to the KeyServer Roles that the AD account is part of. Make sure the Role(s) include permissions to login with KeyConfigure (if you want to do that) and any other desirable permissions (e.g., view and run reports).

— Go through the above steps again, making sure you've done everything exatly as described.

— Check that the host name you chose (“server.ad.sample.net” in this example) resolves to the KeyServer host.

— Verify that the SPN is set for the KeyServer service account using a command like this:

C:\> setspn -L KSServiceAccount
Registered servicePrincipalNames for CN=KSServiceAccount,CN=Users,DC=ad,DC=sample,DC=net:
	HTTP/server.ad.sample.net

— Verify that the SPN is not also assigned to some other account. Use ldp or ldapsearch as described above.

— Check that the KeyServer service is running in the account. Open Task Manager, click the Processes tab, check “Show processes from all users”, then look for ks.exe in the Image Name column. The corresponding item in the User Name column should be the account you created for KeyServer.

— Try logging in a few times (with the expected failure), then look in the Applications log in Event Viewer for any KeyServer error entries.

— Try logging in with Internet Explorer/Edge, running on a Windows computer that is a member of your domain. If that works, then the problem is likely a misconfiguration of the (non-Microsoft) browser.