+

Search Tips   |   Advanced Search

Create a Kerberos configuration file


Overview

To create a Kerberos configuration file for WebSphere Application Server we use wsadmin createkrbConfigFile. We must first create a Kerberos keytab file (krb5.keytab).

The Kerberos configuration file (krb5.ini or krb5.conf) contains client configuration information, including...

The KDC name and realm settings, for both SPNEGO web authentication and Kerberos authentication. are provided in the Kerberos configuration file or through the JVM system properties...

Place a copy of the configuration file in every instance in a cell using a wsadmin command.

For Windows, if the krb5.ini file is not located in the c:\winnt directory it might be located in c:\windows.


Create a Kerberos configuration file

  1. Run...

      >app_server_root/bin
      > wsadmin
      # $AdminTask help createKrbConfigFile

  2. Specify createKrbConfigFile command parameters...

    Option Description
    <krbPath> Required. Fully qualified file system location of the Kerberos configuration file (krb5.ini or krb5.conf).
    <realm> Required. Kerberos realm name. Used by SPNEGO to form the Kerberos service principal name for each of the hosts specified with the property..

      com.ibm.ws.security.spnego.SPN<id>.hostName
    <kdcHost> Required. Host name of the Kerberos KDC.
    <kdcPort> Optional. Port number of the Kerberos KDC. If this port is omitted, the default value is 88.
    <dns> Required. A list of default domain name services DNS, separated by a pipe character, used to produce a fully qualified host name. The first one in the list is the default domain name service.
    <keytabPath> Required. System location of the Kerberos keytab path and file name.
    <encryption> Optional. List of supported encryption types, separated by a pipe character. The default is des-cbc-md5.

  3. Specify an encryption type.

    • des-cbc-md5
    • des-cbc-crc
    • des3-cbc-sha1
    • rc4-hmac
    • arcfour-hmac
    • arcfour-hmac-md5
    • aes128-cts-hmac-sha1-96
    • aes256-cts-hmac-sha1-96

    Not all of the KDC solutions available support all of the encryption types listed previously. Before we choose an encryption type, ensure that your KDC supports the encryption type to use by consulting your Kerberos Administrator's and User's Guide.

    Ensure we have a common encryption type for the Kerberos configuration file, the Kerberos keytab file, the Kerberos service principal name and the Kerberos client. For example, if the Kerberos client uses the RC4-HMAC encryption type, the target server must also support the RC4-HMAC encryption type and the Kerberos configuration file must list RC4-HMAC first in default_tgt_enctypes and default_tkt_enctypes.

  4. KrbPath and krbKeytab location types.

    For example... 

    $AdminTask createKrbConfigFile {-krbPath c:/winnt/krb5.ini 
                                -realm WSSEC.AUSTIN.IBM.COM 
                                -kdcHost host1.austin.ibm.com 
                                -dns austin.ibm.com|raleigh.ibm.com 
                                -keytabPath c:/winnt/krb5.keytab}

    WebSphere variables can also be used to specify krbPath and krbKeytab location paths for the createKrbConfigFile command.

    Use this example to create the c:/winnt/krb5.ini file: 

    [libdefaults]
	default_realm = WSSEC.AUSTIN.IBM.COM
	default_keytab_name = FILE:c:\winnt\krb5.keytab
	default_tkt_enctypes = rc4-hmac des-cbc-md5
	default_tgs_enctypes = rc4-hmac des-cbc-md5
	forwardable  = true 	renewable  = true 	noaddresses = true 	clockskew  = 300
[realms]
	WSSEC.AUSTIN.IBM.COM = {
		kdc = host1.austin.ibm.com:88
		default_domain = austin.ibm.com
	}
[domain_realm]
	.austin.ibm.com = WSSEC.AUSTIN.IBM.COM
	.raleigh.ibm.com = WSSEC.AUSTIN.IBM.COM

    The createKrbConfigFile command creates a simple Kerberos configuration file. We can edit this file, as needed, to specify a TCP or UDP preference or when we have a cross or trusted realm environment.

    In the [libdefaults] section, we can specify a TCP or UDP protocol preference. By default, the Java Kerberos configuration uses the UDP protocol. However, the Java Kerberos supports a TCP or a UDP protocol configuration using the udp_preference_limit parameter. To use the TCP protocol, specify the udp_preference_limit parameter with a 1 value to always use the TCP protocol. For example: 

    udp_preference_limit =1

    If not specified, the Java Kerberos library uses the TCP protocol only if the Kerberos ticket request using the UDP protocol fails and the KDC returns the KRB_ERR_RESPONSE_TOO_BIG error code.

    When the application server receives a client request, the Kerberos configuration on the server might return a Connection reset, IOException, or Broken pipe exception if we use the TCP protocol and the KDC returns a bad packet. The application server makes three attempts to capture the correct Kerberos packet. If a correct Kerberos packet is returned as a result of one of the three attempts, the client request is successfully processed and we can ignore the exceptions. If the application server cannot obtain the correct Kerberos packet after three attempts, the client request fails. At this point, review the KDC, network, and application server configurations to determine the issue.

  5. Complete the [domain_realm] section of the Kerberos configuration file for a cross realm environment

    • [domain_realm]: Provides a translation from a domain name or host name to a realm name. The tag name can be a host name or a domain name. Domain names are indicated by a prefix of a period ('.'). The value of the relation is the realm name for that particular host or domain. Host names and domain names must be lowercase.

      If no translation entry applies, the host realm is considered to be the host name domain portion converted to uppercase. For example, the following [domain_realm] section maps tech.ibm.com into the TEST.AUSTIN.IBM.COM realm: 

      [domain_realm]
	.austin.ibm.com = WSSEC.AUSTIN.IBM.COM
	.raleigh.ibm.com = WSSEC.AUSTIN.IBM.COM

      All other hosts in the austin.ibm.com and .raleigh.ibm.com domains map to WSSEC.AUSTIN.IBM.COM by default.

      The following example contains more than one Kerberos realm name: 

      [domain_realm]
       .ibm.com =AUSTIN.IBM.COM
       ibm.com =AUSTIN.IBM.COM
       tech.ibm.com =TEST.AUSTIN.IBM.COM
       .fubar.org =FUBAR.ORG

      All other hosts in the ibm.com domain map by default to the AUSTIN.IBM.COM realm and all hosts in the fubar.org domain map by default to the FUBAR.ORG realm.

    Without the entries for the ibm.com and fubar.org hosts, these hosts map into the realms COM and ORG, respectively.

    For peer trust cross-realm authentication, see your Kerberos Administrator's and User's Guide for information about how to set up the trust cross-realm authentication on the KDC.

  6. Add information about the foreign realm to the realms and domain_realm sections of the Kerberos configuration file: 

    [realms]
       AUSTIN.IBM.COM = {
             kdc = kdc.austin.ibm.com:88
             default_domain = austin.ibm.com
       }
       FUBAR.ORG = {
             kdc = kdc.fubar.org:88
             default_domain = fubar.org
       }
[domain_realm]
       austin.ibm.com = AUSTIN.IBM.COM
       .austin.ibm.com = AUSTIN.IBM.COM
       fubar.org = FUBAR.ORG
       .fubar.org = FUBAR.ORG

    In a transitive trust, two realms trust each other if they trust the intermediate realms involved in granting a ticket. If each realm involved in granting the service ticket is present in the trust path, then the ticket is trusted. See your Kerberos Administrator's and User's Guide for information about how to configure transitive trust on the KDC.

    To set up transitive trust, separate realms with cross-realm authentication must be defined between A and B and between B and C, but not between A and C. With transitive trust, REALMA and REALMC can communicate with each other, but only by going through REALMB. 

    REALMA	<->	REALMB	<->	REALMC

  7. Add data to stanzas. Add a [capaths] stanza to each krb5.conf file.

    The krb5.conf files on all machines must list all three realms in the [realms] stanza. REALMA must list itself and REALMB and REALMC; REALMB must list itself and REALMA and REALMC; REALMC must list itself and REALMA and REALMB. In the [domain_realm] stanza of the krb5.conf files list all three host names and realm names to be able to execute from REALMA to REALMC and from REALMC to REALMA. 

    [capaths]
       REALMA.AUSTIN.IBM.COM = {
       		REALMB.AUSTIN.IBM.COM = .
       		REALMC.AUSTIN.IBM.COM = REALMB.AUSTIN.IBM.COM
            }
       REALMB.AUSTIN.IBM.COM = {
       		REALMC.AUSTIN.IBM.COM = .
       		REALMA.AUSTIN.IBM.COM = .
            }
       REALMC.AUSTIN.IBM.COM = {
       		REALMB.AUSTIN.IBM.COM = .
       		REALMA.AUSTIN.IBM.COM = REALMB.AUSTIN.IBM.COM
            }

  8. Set the krb5.conf file permission to 644.

    This means that we can read and write the file. However, members of the group that the file belongs to and all other users can only read the file.

    Since the Kerberos configuration and keytab file are set by the JVM system properties, java.security.krb5.conf and KRB5_KTNAME respectively, if SPNEGO web authentication and Kerberos authentication are both enabled use the same Kerberos configuration and keytab files for both.

We have now created a Kerberos configuration file.


Related:

  • Kerberos (KRB5) authentication mechanism support for security
  • Create a single sign-on for HTTP requests using SPNEGO Web authentication
  • Configure Kerberos as the authentication mechanism
  • Set up Kerberos as the authentication mechanism for WAS
  • Kerberos authentication settings
  • Ktab - Kerberos Key Table Manager
  • Kerberos: The Network Authentication Protocol