Creating a Kerberos service principal name and keytab file

This task is necessary to process SPNEGO web or Kerberos authentication requests to WebSphere® Application Server. You can create a Kerberos service principal name and keytab file by using Microsoft Windows, IBM i, Linux®, Solaris, Massachusetts Institute of Technology (MIT) and z/OS® operating systems key distribution centers (KDCs).

• Create a Kerberos service principal name and keytab file by using Microsoft Windows KDC:
  This task is performed on the active directory domain controller machine. Complete the following steps to ensure that the Windows Server that is running the active directory domain controller is configured properly to the associated KDC.
  1. Create a user account in the Microsoft Active Directory for the WebSphere Application Server:

     1. Click Start > Programs > Administrative Tools > Active Directory Users and Computers.

        Use the name for WebSphere Application Server. For example, if the application server you are running on the WebSphere Application Server machine is called myappserver.austin.ibm.com, create a new user in an active directory called myappserver.

     2. Make sure that you do not have the computer name myappserver under Computers and Domain Controllers. If you already have a computer named myappserver, then you must create a different user account name.

        • Click Start > Programs > Administrative Tools > Active Directory Users and Computers > Computers.
        • Click Programs > Administrative Tools > Active Directory Users and Computers > Domain Controllers.
  2. Use the setspn command to map the Kerberos service principal name, <service name>/<fully qualified host name>, to a Microsoft user account.

     The service name for SPNEGO web authentication must be HTTP. However, the service name for Kerberos authentication can be any strings that are allowed by the KDC.

     An example of the setspn command usage for SPNEGO web authentication is as follows:

     C:>setspn -S HTTP/myappserver.austin.ibm.com myappserver

     Note: The host name must be a fully-qualified host name.
  3. Use the ktpass tool to create the Kerberos keytab file for the service principal name (SPN). Use the latest version of the ktpass tool that matches the Windows server level that you are using.
     For more information on the ktpass tool, see the ktpass command.

     Note: A Kerberos keytab file contains a list of keys that are analogous to user passwords. It is important for hosts to protect their Kerberos keytab files by storing them on the local disk.

     To determine the appropriate parameter values for the ktpass tool, run the ktpass -? command from the command line. This command lists the encryption types supported by the ktpass tool.

     The following code shows the functions that are available when you enter the ktpass -? command on the command line. This information might be different depending on the version of the toolkit that you are using.

     The following code is from ktpass /? from Windows 2016.

     C:\Program Files\Support Tools>ktpass -?                                  
     Command line options:                                                     
                                                                               
     ---------------------most useful args                                     
     [- /]          out : Keytab to produce                                    
     [- /]        princ : Principal name (user@REALM)                          
     [- /]         pass : password to use                                      
                          use "*" to prompt for password.                      
     [- +]      rndPass : ... or use +rndPass to generate a random password    
     [- /]      minPass : minimum length for random password (def:15)          
     [- /]      maxPass : maximum length for random password (def:256)         
     ---------------------less useful stuff                                    
     [- /]      mapuser : map princ to this user account (default:     
     don't)                                                                    
     [- /]        mapOp : how to set the mapping attribute (default: add it)   
     [- /]        mapOp :  is one of:                                          
     [- /]        mapOp :        add : add value (default)                     
     [- /]        mapOp :        set : set value                               
     [- +]      DesOnly : Set account for des-only encryption (default:don't)  
     [- /]           in : Keytab to read/digest                                
     ---------------------options for key generation                           
     [- /]       crypto : Cryptosystem to use                                  
     [- /]       crypto :  is one of:                                                             
     [- /]       crypto : aes128-cts-hmac-sha1-96 : default 128-bit encryption             
     [- /]        ptype : principal type in question                           
     [- /]        ptype :  is one of:                                          
     [- /]        ptype : KRB5_NT_PRINCIPAL : The general ptype-- recommended  
     [- /]        ptype : KRB5_NT_SRV_INST : user service instance             
     [- /]        ptype : KRB5_NT_SRV_HST : host service instance              
     [- /]         kvno : Override Key Version Number                          
                          Default: query DC for kvno.  Use /kvno 1 for Win2K compat.                                                                 
     [- +]       Answer : +Answer answers YES to prompts.  -Answer answers     
     NO.                                                                       
     [- /]       Target : Which DC to use.  Default:detect                     
     [- /]      RawSalt : raw salt to use when generating key (not needed)
     [- +]     DumpSalt : show us the MIT salt being used to generate the key
     [- +]       SetUpn : Set the UPN in addition to the SPN. Default DO.
     [- +]      SetPass : Set the user's password if supplied.
     

     Important: Do not use the -pass switch on the ktpass command to reset a password for a Microsoft Windows server account.

     Depending on the encryption type, you use the ktpass tool in one of the following ways to create the Kerberos keytab file. The following section shows the different types of encryption that are used by the ktpass tool. It is important that you run the ktpass -? command to determine which -crypto parameter value is expected by the particular toolkit in your Microsoft Windows environment.

     • For the following example, from a command prompt, run the ktpass command:

       ktpass -out c:\temp\myappserver.keytab
       -princ HTTP/myappserver.austin.ibm.com@WSSEC.AUSTIN.IBM.COM
       -mapUser myappserv 
       -mapOp set 
       -pass was1edu
       -crypto AES256-SHA1 
       -pType KRB5_NT_PRINCIPAL

       Table 1. Using ktpass for a single DES encryption type .

       This table describes how to use ktpass for a single DES encryption type.

       Option	Explanation
       -out c:\temp\myappserver.keytab	The key is written to this output file.
       -princ HTTP/myappserver.austin.ibm.com@WSSEC.AUSTIN.IBM.COM	The concatenation of the user logon name, and the realm must be in uppercase.
       -mapUser	The key is mapped to the user, myappserver.
       -mapOp	This option sets the mapping.
       -pass was1edu	This option is the password for the user ID.
       -crypto AES256-SHA1	This option is the recommended encryption type. DES encryption types might cause a security warning as they are less secure. Users can adjust the encryption type such as -crypto AES256-SHA1|AES128-SHA1
       -pType KRB5_NT_PRINCIPAL	This option specifies the KRB5_NT_PRINCIPAL principal value. Specify this option to avoid toolkit warning messages.

     • The Kerberos keytab file is created for use with SPNEGO.

       Important:

       When you are mapping your SPN(s), map a maximum of 1 SPN to an individual AD user. If want to map multiple SPNs to an individual AD user, ensure that the Microsoft ktpass tool supports the steps that you are following.

       You might see the following message:

       [JGSS_DBG_CTX]  WebContainer : 0 Error authenticating request. Reporting to client
       Major code = 11, Minor code = 0
       org.ietf.jgss.GSSException, major code: 11, minor code: 0
       	major string: General failure, unspecified at GSSAPI level
       	minor string: Kerberos error while decoding and verifying token: com.ibm.security.krb5.internal.crypto.KrbCryptoException, status code: 0
       	message: com.ibm.security.krb5.internal.KrbException, status code: 31
       	message: Integrity check on decrypted field failed
       

       If you see this message, ensure that the following information is correct:

       • The current user password matches the one that was defined when the keytab was generated.
       • You are using the latest release of the ktpass tool from Microsoft.
       • You are using the latest fix pack for the application server and the latest JDK version.

       If the previous recommendations do not resolve the issue, contact Microsoft to proceed with further debug.
• Create a Kerberos service principal name and keytab file by using iSeries, Linux, Solaris and MIT KDCs:

  See your Kerberos implementation documents for the kadmin, kadmin.local addprinc and ktadd commands for more detailed information.

  This task is performed on a Linux, Solaris or a MIT KDC machine.

  1. Create a Kerberos service principal for Kerberos authentication, for example:

     WAS/testmach.austin.ibm.com 
     kadmin.local: addprinc WAS/testmach.austin.ibm.com 

  2. Add the newly-created Kerberos service principal, WAS/testmach.austin.ibm.com to a default krb5.keytab file, for example:

     kadmin.local: ktadd WAS/testmach.austin.ibm.com