Useful information can be found in the official SPNEGO documentation. The documentation includes complete descriptions of parameters and a thorough example of how to set up SSO using Kerberos. At the time of writing, the documentation can be found at the SPNEGO SourceForge webpage.
The setup can then be divided in two areas, the Orchestra server area and the Orchestra client (or Orchestra terminal user) area.
Note that SSO using Kerberos is not working from distributed agents.
Client Area
Only one procedure is required to configure the Orchestra client(s). Set the client browser (Microsoft Internet Explorer) to identify the Orchestra server as an intranet site. Please follow the steps below:
1. Login to the Windows domain using the Windows account of the Orchestra terminal user.
2. Start Internet Explorer.
3. Open the tab: Tools -> Internet Options -> Security.
4. Select Local Intranet.
5. Set the Security Level to Low.
6. Click Sites.
7. Click Advanced.
8. Fill in the IP address or the host name of your Orchestra server and click Add.
9. Close this window.
10. Click OK.
11. Click Advanced.
12. In the Security section, make sure that Enable Integrated Windows Authentication is checked. If not, check the check box, and click Apply.
13. Close the Internet Options window by clicking OK.
14. Close the browser.
The browser is now be configured to support SPNEGO.
Server Area
On the Active Directory domain controller, perform the following steps:
1. Register the host name of the Orchestra service in DNS.
This hostname should be in the same domain as the AD domain and MUST BE a DNS A-record, i.e. NOT a CNAME record.
E.g. if your AD domain is test.q-matic.net, then the host name could be testrd.test.q-matic.net.
2. Create a user that will hold the kerberos / SSO configuration. Alternatively re-use another user.
The user should have a pre-set password that should not be possible to change, and the password should never expire.
Example is a user named "kerberos" in the AD domain "test.q-matic.net".
To edit the properties of the user, right-click on its name in the Active Directory Users and Computers window.
The following window is opened:
In the Account options area of the Account tab, make sure that you check the check box next to This account supports Kerberos AES 128 bit encryption, as shown in the picture above.
3. Register the SPN (Service Principal Name, i.e. the servername) with the user. This is done via the "setspn" command.
The command should be executed like this:
setspn -A HTTP/<hostname> <username>
It is important that the -A HTTP part of the command is in upper case, for this to work!
Using the examples above the command would look like this:
setspn -A HTTP/testrd.test.q-matic.net kerberos
Note that setspn is not available in all versions of Windows 2003 server. You can, however, download the Windows server 2003 support tools from the Microsoft Web site.
The Orchestra server requires a few things in order to enable SSO.
Start by editing the <install_dir>/conf/krb5.conf file or <agent_profile_dir>/conf/krb5.conf file, if the configuration is part of a configuration change in a remote upgrade. Change the following entries in the file to match what is correct for your domain:
• default_realm
• realms
• kdc
• default_domain
• domain_realm
The simplest way to configure is to do the following when starting with the default krb5.conf file:
1. Replace (case-sensitively) all instances of "YOUR.DOMAIN" (in UPPERCASE) with the domain that the Orchestra server resides in, e.g. "MYSUBNET.MYCOMPANY.COM".
This should be in 4 places and in UPPERCASE.
2. Replace the value for kdc "nameofyourkdc.your.domain" with the domain controller (Active directory) in your environment, e.g. "adserver01.mysubnet.mycompany.com".
3. Replace the domain-mapping "your.domain" (in lowercase) with the domain that your Orchestra server resides in, prefixed by a dot (.),
Next, in Orchestra, navigate to the System Administration application and the Parameters tab. In the SSO section, mark the enabled check box as active.
Enter the user created in AD as Pre-authentication username, e.g. "kerberos" and enter the password for the user as Pre-authentication password.
Save the changes and restart Orchestra.
For any distributed QueueAgent instances the configuration made in the UI will be enabled upon restart. However, the krb5.conf file must be modified for each QueueAgent, or modified in an agent profile and sent to the Queue Agent via remote upgrade. It should be identical to the one defined for the central installation, unless the agent profile configuration has been overridden via remote upgrade.
Once configuration is complete, restart the Orchestra server.
If a misconfiguration is made, SSO can be disabled by editing the database.
Change the table qp_central.system_parameter. The field value should be set to "false" for the row with ID "aaa.sso.enabled". This can also be done in the Parameters tab of the System Administration application.
E.g. UPDATE qp_central.application_parameters SET value = 'false' WHERE id = 'aaa.sso.enabled';
SSO can also be disabled for an Agent Profile by remote upgade. Changing the setting Enabled to false in System Administration -> Queue Agents -> Agent Profiles -> Override Global Parameters values -> SSO and performing a remote upgrade disables SSO for every Queue Agent that is currently assigned that profile.
Once the setup is complete, SSO should work.
Once SSO is enabled, there can be issues logging in as superadmin, if using a client that is a member of the domain.
The reason is that the client will attempt to log in automatically, not giving the user the option to log in as superadmin.
A workaround exists:
1. Restart the browser to clear any login information.
2. Manually enter the URL into the browser address field: http://<orchestra host>:<orchestra port>/login.jsp?failMessage=error.login.noApplications
Note that SSO using Kerberos is not working from distributed agents.