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. Use the wsadmin utility
to create a Kerberos configuration file for WebSphere® Application Server.
About this task
Note: You can not use the createkrbConfigFile wsadmin command
if you do not have a Kerberos keytab file (krb5.keytab).
Kerberos
configuration settings, the Kerberos key distribution center (KDC)
name, and realm settings for both Simple and Protected GSS-API Negotiation
Mechanism (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 Java™ virtual
machine system properties.
If you do not have a Kerberos configuration
file (
krb5.ini or
krb5.conf), you must first create
a Kerberos configuration file and place it in every instance in a
cell using a
wsadmin command. See the following default Kerberos
configuration files and their locations:
Procedure
- Start the command-line utility by running the wsadmin command from the
app_server_root/bin directory.
- At the wsadmin prompt, enter the following command:
$AdminTask help createKrbConfigFile
- Specify createKrbConfigFile command parameters.
Table 1. createKrbConfigFile command parameters. This table lists the parameters you can use with the createKrbConfigFile command:
Option |
Description |
<krbPath> |
Required. Provides the fully qualified file
system location of the Kerberos configuration (krb5.ini or krb5.conf)
file. |
<realm> |
Required. 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. Provides the host name of the Kerberos
Key Distribution Center (KDC). |
<kdcPort> |
Optional. Provides the port number of the Kerberos
Key Distribution Center. 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, that is used to produce a fully
qualified host name. The first one in the list is the default domain
name service. |
<keytabPath> |
Required. Provides the file system location
of the Kerberos keytab path and file name. |
<encryption> |
Optional. Identifies the list of supported encryption types, separated by a
pipe character. |
- Specify an encryption type.
The following encryption types are supported:
- aes128-cts-hmac-sha1-96
- aes256-cts-hmac-sha1-96
Attention: Not all of the KDC solutions available support all of the encryption types
previously listed. 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 aes128-cts-hmac-sha1-96 encryption type, the target server
must also support the aes128-cts-hmac-sha1-96 encryption type and the Kerberos configuration file
must list aes128-cts-hmac-sha1-96 first in default_tgt_enctypes and default_tkt_enctypes.
- Specify the krbPath and krbKeytab location types.
The
following code 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.
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 = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
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 can 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.
- 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.
Note the entries for the hosts, ibm.com and fubar.org. Without these entries,
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.
- 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
- 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
}
- Set the krb5.conf file permission to 644.
This
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.
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 you must use the same Kerberos configuration and
keytab files for both.
Results
You have now created a Kerberos configuration file.