TN 4291: Preparing a Windows-based KeyReporter for Active Directory admin authentication

KeyServer 7.0 supports administrator access based on external authentication sources like Active Directory. To allow external administrators to run reports via KeyReporter, some additional configuration is reqired depending on the Admin Authentication settings of KeyServer.

2012.04.26

If you are running KeyReporter 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.

Case 1: The “Use Secure Authentication” Option

When the “Use Secure Authentication” is option chosen in the Admin Authentication setup dialog, no additional configuration is required. The admin password will be transmitted from the browser to KeyReporter, and then from KeyReporter 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 is known to both the KeyReporter process and the KeyServer process.

Case 2: The “Use NTLM Authentication” Option

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.

Case 3: The “Use Kerberos Authentication” Option

This option requires some additional configuration on the host running KeyReporter and on the Active Directory server. Additionally, certain browsers (Firefox) will require configuration, while other browsers do not support the functionality. MS Internet Explorer should work without extra configuration.

Preliminary Checks

Let's assume KeyReporter will run on the host named “keyreporter.ad.sample.org” and you have a domain controller on “pdc.ad.sample.org”. 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 KeyReporter has the name “keyreporter.ad.sample.org” (or whatever you choose), and that this name is used when connecting to KeyReporter in a browser.

In order for KeyReporter to accept Kerberos tickets from web browsers, a Kerberos principal (aka “service principal name” or SPN) must be configured for the host running the KeyReporter process. 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=HTTP*)” as shown:

Click the Options button, set the Attributes field to “servicePrincipalName;sAMAccountName”, then click OK:

Click the Run button back 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=org", 2, "(servicePrincipalName=HTTP*)", attrList, 0, &msg) Result <0>: (null) Matched DNs: 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=org", 2, "(servicePrincipalName=HTTP*)", attrList, 0, &msg) Result <0>: (null) Matched DNs: Getting 1 entries: >> Dn: CN=Some Account,CN=Users,DC=ad,DC=sample,DC=org 1> sAMAccountName: someacct; 1> servicePrincipalName: HTTP/keyreporter.ad.sample.org; -----------

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):

[dos-prompt] setspn -D HTTP/keyreporter.ad.sample.org someacct Unregistering servicePrincipalNames for CN=Some Account,CN=Users,DC=AD,DC=sample,DC=org HTTP/keyreporter.ad.sample.org 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.org -b "dc=ad,dc=sample,dc=org" \ -D "cn=account,cn=users,dc=ad,dc=sample,dc=org" -x -W \ '(servicePrincipalName=HTTP*)' servicePrincipalName sAMAccountName Enter LDAP Password: hidden # refldap://ad.sample.org/CN=Configuration,DC=ad,DC=sample,DC=org 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).

Setup Service Account

The KeyReporter process will run in a new 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. "KeyReporter", and give it a strong password, e.g. "x3oM8pvEud"

[dos-prompt] net user KeyReporter x3oM8pvEud /ADD /COMMENT:"KeyReporter service account" Registering servicePrincipalNames for CN=KeyReporter,CN=Users,DC=AD,DC=sample,DC=org HTTP/keyreporter.ad.sample.org Updated object

— Run the setspn command like this (all on one line):

[dos-prompt] setspn -A HTTP/keyreporter.ad.sample.org KeyReporter Registering servicePrincipalNames for CN=KeyReporter,CN=Users,DC=AD,DC=sample,DC=org HTTP/keyreporter.ad.sample.org Updated object

The account must also have the ability to use delegated Kerberos tickets. To enable this privilege, check the “Account is trusted for delegation” box in the account's Properties window:

Note that any user account that will be used with KeyReporter 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.

Setup KeyReporter Process

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

[dos-prompt] net stop KeyReporter The KeyReporter service is stopping. The KeyReporter service was stopped successfully.

KeyReporter must be given access to its executable and its data files. Use Windows Explorer or run this command to grant access. The command below assumes that KeyReporter has been installed in the default location:

[dos-prompt] cacls "c:\Program Files\Sassafras K2\Reporter" /e /t /g KeyReporter:F processed dir: c:\Program Files\Sassafras K2\Reporter ...

KeyReporter must also be told what the SPN is. Using Notepad, open the file in KeyReporter Data Folder named “kr.conf” and add these lines:

<key>principal<key> <string>HTTP/keyreporter.ad.sample.org<string>

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

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

Web Browser Configuration

KeyReporter 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

The Windows computer on which Internet Explorer runs must be a member of the Domain that KeyReporter (and KeyServer) run in.

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 KeyReporter host, “keyreporter.ad.sample.org” 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”).

Web Browser Configuration

If you've followed the above steps and you cannot run reports 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 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 (“keyreporter.ad.sample.org” in this example) resolves to the KeyReporter host.

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

[dos-prompt] setspn -L KeyReporter Registered servicePrincipalNames for CN=KeyReporter,CN=Users,DC=AD,DC=sample,DC=org: HTTP/keyreporter.ad.sample.org

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

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

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

— Try logging in with Internet Explorer, 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-IE) browser.