At the wsadmin prompt, enter the following command:
$AdminTask help createKrbConfigFile
Table 1. createKrbConfigFile command parameters. This table lists the parameters you can use with the createKrbConfigFile command:
Option |
Description |
<krbPath> |
This parameter is required. It provides the
fully qualified file system location of the Kerberos configuration
(krb5.ini or krb5.conf) file. |
<realm> |
This parameter is 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 com.ibm.ws.security.spnego.SPN<id>.hostName
property. |
<kdcHost> |
This parameter is 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> |
This parameter is required. It is a list of
default domain name services DNS, separated by a pipe character, that
is used to produce a fully qualified host name. The first one in the
list is the default domain name service. |
<keytabPath> |
This parameter is 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
Attention: Not all of the KDC solutions available
today support all of the previously listed encryption types. Before
you choose an encryption type, ensure that your KDC supports the encryption
type that you want to use by consulting your 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.austin.ibm.com
-dns austin.ibm.com|raleigh.ibm.com
-keytabPath c:/winnt/krb5.keytab}
Note: 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.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. You might have to edit
this file, as needed, to specify a TCP or UDP preference or when you
have a cross or trusted realm environment.
In the [libdefaults]
section, you 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.
If you need 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
you do not specify this parameter, 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.
Avoid trouble: 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 you 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 you 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.
gotcha
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]
.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 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 your 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.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
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 you 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.
Because the Kerberos
configuration and keytab file are set by the java.security.krb5.conf and KRB5_KTNAME Java virtual machine (JVM) system
properties respectively, if SPNEGO Web authentication and Kerberos
authentication are both enabled you must use the same Kerberos configuration
and keytab files for both.