Create a Kerberos configuration file


The Kerberos configuration file contains client configuration information, including the locations of Key Distribution Centers (KDCs) for the realms of interest, defaults for the current Kerberos realm and mappings of host names onto Kerberos realms.

Kerberos settings, the Kerberos key distribution center (KDC) name, and realm settings for both SPNEGO Web authentication and Kerberos authentication are provided in the Kerberos configuration file or through the java.security.krb5.kdc and java.security.krb5.realm JVM system properties. If we don't have a Kerberos configuration file (krb5.ini or krb5.conf), first create a Kerberos configuration file and place it in every instance in a cell using a wsadmin command.

The following are the default Kerberos configuration files and their locations:

Use the wsadmin utility to create a Kerberos configuration file for WebSphere® Application Server:

 

  1. Start the command-line utility by running the wsadmin command from the APP_ROOT/bin directory.

  2. At the wsadmin prompt...

    $AdminTask help createKrbConfigFile 
    

    You can use the following parameters with the createKrbConfigFile command:


    Table 1. createKrbConfigFile command parameters

    Option Description
    <krbPath> Required. It provides the fully qualified file system location of the Kerberos configuration (krb5.ini or krb5.conf) file.
    <realm> Required. It provides the Kerberos realm name. The value of this attribute is 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. It provides the host name of the Kerberos Key Distribution Center (KDC).
    <kdcPort> This parameter is optional. It provides the port number of the Kerberos Key Distribution Center. If this port is omitted, it defaults to 88.
    <dns> Required. It is 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. It provides the file system location of the Kerberos keytab path and file name.
    <encryption> This parameter is optional. It identifies the list of supported encryption types, separated by a pipe character. The default value is des-cbc-md5.

    The following encryption types are supported:

    • 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 today support all of the encryption types listed above. Before you choose an encryption type, ensure that the KDC supports the encryption type to use by consulting the Kerberos Administrator's and User's Guide.

    Ensure you 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.

    The following is an example of the createKrbConfigFile command:

    $AdminTask createKrbConfigFile {-krbPath c:/winnt/krb5.ini 
                                    -realm WSSEC.AUSTIN.IBM.COM 
                                    -kdcHost host1.mpls.setgetweb.com 
                                    -dns mpls.setgetweb.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.

    This example creates the c:/winnt/krb5.ini file as follows:

    [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.mpls.setgetweb.com:88
        default_domain = mpls.setgetweb.com
      }
    [domain_realm]
      .mpls.setgetweb.com = WSSEC.AUSTIN.IBM.COM
      .raleigh.ibm.com = WSSEC.AUSTIN.IBM.COM
    
    

    The createKrbConfigFile command creates a simple Kerberos configuration file. We might have to edit this file as needed, especially when we have a cross or trusted realm environment. The [domain_realm] section of the Kerberos configuration file is needed 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 should be in lowercase.If no translation entry applies, the host's realm is considered to be the host name's 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]
        .mpls.setgetweb.com = WSSEC.AUSTIN.IBM.COM
        .raleigh.ibm.com = WSSEC.AUSTIN.IBM.COM
      

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

      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.

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

    For peer trust cross-realm authentication, see the Kerberos Administrator's and User's Guide for information about how to set up the trust cross-realm authentication on the KDC. You must add information about the foreign realm to the realms and domain_realm sections of the Kerberos configuration file. For example:

    [realms]
           AUSTIN.IBM.COM = {
                 kdc = kdc.mpls.setgetweb.com:88
                 default_domain = mpls.setgetweb.com
           }
           FUBAR.ORG = {
                 kdc = kdc.fubar.org:88
                 default_domain = fubar.org
           }
    [domain_realm]
           mpls.setgetweb.com = AUSTIN.IBM.COM
           .mpls.setgetweb.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 the 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
    
    A [capaths] stanza must be added 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
                }
    

    The krb5.conf file permission must be set to 644, which 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.

 

Results

we have now created a Kerberos configuration file.

 

Related concepts


Kerberos (KRB5) authentication mechanism support for security

 

Related tasks


Create a single sign-on for HTTP requests using SPNEGO Web authentication
Set Kerberos as the authentication mechanism

 

Related


Kerberos authentication
Ktab - Kerberos Key Table Manager
Kerberos: The Network Authentication Protocol