Creating a service principal name and keytab file 

---

Create a service account in Microsoft™ Active Directory to support a service principal name (SPN) for IBM® Connections, and then create a keytab file that the Kerberos authentication service can use to establish trust with the web browser.

Before you begin

You must configure IBM Connections to use Active Directory as the user directory. For more information, see the Setting up federated repositories topic.

Do not perform this procedure until after you have populated the Profiles database. For more information, see the Populating the Profiles database topic.

Active Directory and the domain controller must be hosted on Windows™ systems but IBM Connections may be installed on AIX®, Linux™, or Windows systems.

About this task

A service principal name (SPN) account uniquely identifies an instance of a service. Before the Kerberos authentication service can use an SPN to authenticate a service, you must register the SPN on the account object that the service instance uses to log on. You must then create a keytab file. When a web browser tries to access the service, it must get a ticket from the Active Directory key distribution center to send with the access request. Active Directory uses the keytab file to decrypt the ticket sent from the web browser to establish that the application server can trust the browser.

In a network deployment of IBM Connections, each node is granted a key inside a key table file. This task shows you how to merge the keys for all the nodes in your deployment into a single key table.

An SPN consists of the following information:

Service type

Specifies the protocol to use, such as HTTP.

Instance

Specifies the name of the server hosting the application. For example: finance1.us.example.com. Use the IBM HTTP Server name or the virtual host name through which users access IBM Connections applications. You do not need to specify a port number.

Realm

Specifies the domain name of the server hosting the application. For example: US.EXAMPLE.COM.

Specify an SPN using the following syntax: service_type/instance@realm

For example: HTTP/finance1.us.example.com@US.EXAMPLE.COM

To create a service principal name and keytab file, complete the following steps:

Procedure

1. Synchronize the clocks of the systems hosting IBM Connections. If the host clocks are not synchronized with the Kerberos server clock, authentication will fail.
• AIX or Linux:
For information about synchronizing the system clocks in an AIX or Linux environment, refer to your operating system documentation. For examples of the ntpdate command, go to the ntpdate Command topic in the AIX information center.

• Windows:
Using the domain controller as the time server, run the TimeSyn.bat file on each IBM WebSphere® Application Server system hosting IBM Connections. Use the Windows Task Scheduler to run the batch file.

For example, when finance.us.example.com is both the domain controller and the NTP time server, the TimeSyn.bat file contains the following commands:



w32tm /config /manualpeerlist:financè.us.example.com,0x8 /syncfromflags:MANUAL

net stop w32time

net start w32time

w32tm /resync



For more information about how to use the domain controller as the time server, go to the How to configure an authoritative time server in Windows Server topic on the Microsoft Support website. For more information about running the Windows schedule task, go to this Time synchronization topic on the Microsoft Support website.

2. Install Windows Support Tools on the systems hosting Active Directory. You must have access to these tools to run the ktpass command later in this procedure.
   
For more information, go to the Install Windows Support Tools webpage on the Microsoft Technet website.

3. Log in to the Windows Domain Controller. You must know which server is the domain controller and you must have an administrative level user name and password.
4. Create a new account for IBM Connections by accessing the Active Directory Users and Computers settings.
5. In the New Object - User window, enter a user name in the User logon name field and specify the domain in the corresponding field. For example, enter lcserver01 in the User logon name field, and enter @us.example.com in the domain field.
6. Click Next.
7. Type a password for the logon name in the Password field.
8. On the Account page, select the User cannot change password and Password never expires check boxes. By preventing the password from expiring, you avoid having to recreate the keytab file after the password has changed. Click OK to save the new user information.
9. Map the service principal name to the IBM Connections user account that you created and generate a keytab file. Generate the keytab file using the IBM HTTP Server name or the virtual host as the instance in the service principal name. Run the following ktpass command on the domain controller:
   
ktpass -out <path_to_keytab> –princ <SPN>

-mapuser <account_name> -mapOp set –pass <account_password>

where you must provide values for the following variables:

<path_to_keytab>
File path where you want to store the generated keytab file.
<SPN>
The Kerberos service principal name.
<account_name>
The service account name.
<account_password>
Password associated with the service account.

For example:



ktpass -out c:\finance1.keytab -princ HTTP/finance1.us.example.com@US.EXAMPLE.COM -mapuser icserver01 -mapOp set -pass Passw0rd1



Note: For extra security, you should consider creating a keytab file for each system, where each system has its own user account. If you use the same user account to generate the keytab file, use the -mapOp add parameter instead of the -mapOp set parameter.

This example shows how to create unique keytab files for different systems:



ktpass -out c:\finance1.keytab -princ HTTP/finance1.us.example.com@US.EXAMPLE.COM -mapuser icserver01 -mapOp set -pass Passw0rd1  

ktpass -out c:\finance2.keytab -princ HTTP/finance2.us.example.com@US.EXAMPLE.COM -mapuser icserver02 -mapOp set -pass Passw0rd2  

ktpass -out c:\finance3.keytab -princ HTTP/finance3.us.example.com@US.EXAMPLE.COM -mapuser icserver03 -mapOp set -pass Passw0rd3



10. Merge all the keytab files to make the Deployment Manager aware of the SPNs for each node.
    
The following example demonstrates the procedure for merging keytab files.

Assuming that you have created the following keytab files:

• krb5.keytab on the Deployment Manager
• krb5NodeA.keytab on Node A
• krb5NodeB.keytab on Node B
  
  
Run the ktab command with the following switch:

-m <source_keytab_name> <destination_keytab_name>

where <source_keytab_name> is the name of the keytab file on the source system and <destination_keytab_name> is the name of the keytab file on the destination system.

Step 1: merge the keytab file on Node A into the keytab file on the Deployment Manager:



# ./ktab -m /etc/krb5NodeA.keytab /etc/krb5.keytab

Merging keytab files:   source=krb5NodeA.keytab   destination=krb5.keytab

Done! 



Step 2: merge the keytab file on Node B into the keytab file on the Deployment Manager:



 # ./ktab -m /etc/krb5NodeB.keytab /etc/krb5.keytab

Merging keytab files:   source=krb5NodeB.keytab   destination=krb5.keytab

Done! 



For more information, go to the Using the ktab command to manage the Kerberos keytab file topic in the IBM WebSphere Application Server 7 information center.

11. Create a Kerberos configuration file named krb5.conf for each node. You do not need to create a configuration file for the deployment manager. To create a Kerberos configuration file, complete the following steps:
1. If IBM Connections is not installed on the system that hosts the domain controller, copy the keytab file to the system where IBM Connections is installed.
   
2. Open a command prompt on the system hosting the Deployment Manager and start the wsadmin client with the following parameters:
   
• AIX or Linux:

./wsadmin.sh -lang jacl -user <admin_user_id> -password <admin_password> -port <SOAP_CONNECTOR_ADDRESS Port>



• Microsoft Windows:

wsadmin -lang jacl -user <admin_user_id> -password <admin_password> -port <SOAP_CONNECTOR_ADDRESS Port>



where:

• <admin_user_id> is the user account for the Administrator role for IBM WebSphere Application Server.
• <admin_password> is the password of the WebSphere Application Server administrator.
• <SOAP_CONNECTOR_ADDRESS Port> is the SOAP port for the WebSphere Application Server Deployment Manager. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter.
  
  
3. Enter the following command as one line in the wsadmin client:
   
$AdminTask createKrbConfigFile

{

-krbPath <appserver>\java\jre\lib\security\krb5.conf

-realm <REALM>

-kdcHost <kdc_hostname>

-dns <dns_hostname>

-keytabPath <path_to_keytab>

}

using the following variables:

<appserver>
The path to the WebSphere Application Server root directory. Do not specify the path to the IBM Connections application. The krbPath parameter defines where the resulting krb5.conf configuration file is stored.
<REALM>
The Kerberos realm. Enter the name of the realm in uppercase letters.
<kdc_hostname>
The name of the Active Directory key distribution center host. This name is typically the domain controller server.
<dns_hostname>
The DNS server name of the domain controller server.
<path_to_keytab>
The file path to the directory in which the keytab file is stored.

Use the following sample configuration file to format your entry:



C:\IBM\WebSphere\AppServer\java\jre\lib\security\krb5.conf

 [libdefaults]

	default_realm = EXAMPLE.COM

	default_keytab_name = FILE:C:\finance1.keytab

	default_tkt_enctypes = des-cbc-md5 rc4-hmac

	default_tgs_enctypes = des-cbc-md5 rc4-hmac

	kdc_default_options = 0x54800000

#	forwardable  = true

#	proxiable  = true

#	noaddresses = true

 [realms]

	EXAMPLE.COM = {

		kdc = finance1.us.example.com:88

		default_domain = finance1.us.example.com

	}

 [domain_realm]

	.finance1.us.example.com = EXAMPLE.COM



4. Copy the merged keytab file and the new krb5.conf file to the same location on each node.
   
For more information, go to the Creating a Kerberos configuration file topic in the IBM WebSphere Application Server 7 information center.

Parent topic: Enabling single sign-on for the Windows desktop
Previous topic: Mapping an Active Directory account to administrative roles
Next topic: Creating a redirect page for users without SPNEGO support

Related tasks
Starting the wsadmin client
Configuring Kerberos and SPNEGO
Enabling single sign-on for Tivoli Access Manager with SPNEGO
Enabling single sign-on for SiteMinder with SPNEGO
Setting up federated repositories
Populating the Profiles database

Related reference
http://publib.boulder.ibm.com/infocenter/aix/v7r1/topic/com.ibm.aix.cmds/doc/aixcmds4/ntpdate.htm
How to configure an authoritative time server in Windows Server
Time synchronization
Install Windows Support Tools
Creating a Kerberos configuration file