You can use the administrative console to configure Kerberos as the authentication
mechanism for the application server. When you have entered and applied the required information to
the configuration, the Kerberos service principal name is formed as <service
name>/<fully qualified hostname>@KerberosRealm, and
is used to verify incoming Kerberos token requests.
Before you begin
Read about Kerberos (KRB5) authentication mechanism support for security to
understand the Kerberos authentication mechanism in this version of WebSphere® Application Server. You must have completed the following steps
before you configure Kerberos as the authentication mechanism using the administrative console:
- If you do not already have a Kerberos configuration file, krb5.ini or krb5.conf,
use the createkrbConfigFile command task to create the Kerberos configuration file. Read
about Creating a Kerberos configuration file for more information.
- You must have a Kerberos keytab file, krb5.keytab, that contains a Kerberos service
principal name (SPN), <service_name>/<fully_qualified
hostname>@KerberosRealm, for each machine that run WebSphere application servers. The service name can be anything you
choose; the default value is WAS.
For example, if you have two application server
machines, host1.austin.ibm.com and host2.austin.ibm.com, the Kerberos keytab file
must contain the <service_name>/host1.austin.ibm.com and
<service_name>/host2.austin.ibm.com SPNs and their Kerberos keys.
Kerberos will only load and use one keytab file per session. For example, if
Kerberos is configured, and you want to use a new keytab file with the same name and location as the
previous keytab file, you must first restart the server to use the new keytab file.
If you are configuring Kerberos for the first time, and you accidentally
use the wrong keytab file, you must unconfigure Kerberos and restart the server before you can
configure Kerberos again using a new keytab file. This is not true, however, if you have the Java™ SE Development Kit (JDK) with SP3 installed.
You must first enable global and application security.
If Kerberos is configured in global security, but you want to configure
Simple and Protected GSS-API Negotiation (SPNEGO) on a domain using a different Kerberos realm, you
must first use the Java
ktab -m command to merge existing keytab files into one keytab file. Use that merged keytab
file to configure Kerberos and SPNEGO on global and domain security.
Procedure
-
In the administrative console, click Security > Global security.
-
From Authentication, click Kerberos configuration.
-
Enter your Kerberos service name.
By convention, a Kerberos service principal is divided into three parts: the primary, the
instance, and the Kerberos realm name. The format of the Kerberos service principal name is
<service_Name>/<fully_qualified hostName>@KERBEROS_REALM. The
service name is the first part of the Kerberos service principal name. For example, in
WAS/test.austin.ibm.com@AUSTIN.IBM.COM, the service name is
WAS. In this example,
the keytab file must have the Kerberos service principal
name,
WAS/test.austin.ibm.com@AUSTIN.IBM.COM, and its keys.
-
Enter the Kerberos configuration file name or click Browse to locate it.
The Kerberos client configuration file,
krb5.conf or
krb5.ini, contains Kerberos
configuration information, including the locations of the Key Distribution Centers (KDCs) for the
realm of interest. The
krb5.conf file is the default file name for all platforms except the
Windows operating system, which uses the
krb5.ini file.
Note: The Kerberos configuration file name and Kerberos keytab file name path do not have to be
absolute paths. You can use WebSphere variables for the
paths instead. If you have a mixed platform environment, you can use the
${CONF_OR_INI} variable for the Kerberos configuration file. Security configuration
will expand it to ini for Windows or conf for non-Windows
platforms For example:
${WAS_INSTALL_ROOT}\etc\krb5\krb5.${CFG_OR_INI}
- Optional:
Enter the Kerberos keytab file name or click Browse to locate it.
The Kerberos keytab file contains one or more Kerberos service principal names and keys. The
default keytab file is
krb5.keytab. It is important for hosts to protect their Kerberos
keytab files by storing them on the local disk, which makes them readable only by authorized users.
Read about
Creating a Kerberos service principal name and keytab file for more information. If you do not
specify this parameter, the default keytab in the Kerberos configuration file is used.
Note: The
Kerberos configuration file name and Kerberos keytab file name path do not have to be absolute
paths. You can use WebSphere variables for the paths
instead.
${WAS_INSTALL_ROOT}\etc\krb5\krb5.keytab
-
Enter the name of your Kerberos realm in the Kerberos realm name field.
In most cases, your realm is your domain name in uppercase letters. If you do not specify this
parameter, the default Kerberos realm name in the Kerberos configuration file is used.
For
example, a machine with the domain name of test.austin.ibm.com has a Kerberos realm name of
AUSTIN.IBM.COM.
Note: The Kerberos realm name for the KDC for Microsoft is an uppercase value of the Domain Controller
name.
- Optional:
Trim Kerberos realm from principal name is selected by default. You can clear this
option if you want the suffix of the Kerberos principal name to be retained.
This option specifies whether the Kerberos login module removes the suffix of the principal
user name, starting from the @ that precedes the Kerberos realm name. If this attribute is set to
true, the suffix of the principal user name is removed. If this attribute is set to
false, the suffix of the principal name is retained. The default value used is
true.
- Optional:
Enable delegation of Kerberos credentials is selected by default.
This option specifies whether the Kerberos delegated credentials are extracted from the client
request. The Kerberos authentication token (KRBAuthnToken) is created with the client principal name
and the client delegate Kerberos ticket if the client is sent the Kerberos delegation credential as
part of the request. The KRBAuthnToken is stored in the client subject. The KRBAuthnToken is
propagated to the downstream server as part of the security attribute propagation. If a customer
application needs the GSSCredential for authentication with a backend resource or a downstream
server, you must retrieve the GSSCredential from the KRBAuthnToken using the
com.ibm.wsspi.wssecurity.platform.token.KRBAuthnToken.getGSSCredential() method and place it in the
subject.
If you don't check this option, the KRBAuthnToken only has the Kerberos principal
name.
Note: If this parameter is true, and the runtime environment cannot extract a
client GSS delegation credential, then a warning message is displayed.
-
Click OK.
Results
When you select Apply or OK the Kerberos authentication is automatically tested. If
the Kerberos configuration is not complete, a message is displayed that indicates authentication
failure.
You have now configured and saved Kerberos as the authentication mechanism for WebSphere Application Server.
What to do next
To enable SPNEGO, click SPNEGO web authentication enablement from Related
Configuration.
SPNEGO web authentication and Kerberos authentication use the same Kerberos client configuration
and keytab files.
When you attempt to authenticate to the administrative console, use an administrative user ID
that exists in the KDC that is associated with the application server. If you use an administrative
user ID exists in a different KDC that is not associated with the administrative console, the login
process fails and following error message is added to the log
file:
SECJ9200E: No Kerberos credential found in subject credential set.
For
example, the client might be associated with a different KDC than the application server.