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.
Note: If you receive an error message
when enabling Kerberos, it is possible that the fully qualified hostname
might need to be manually changed to the long name, not the short
name.
- 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.
Note: The
built-in mapping module uses the full Kerberos principal name and
Kerberos realm for the mapping, regardless of what the Trim Kerberos
realm from principal name field is set to.
- 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.
- Optional: Under Mapping Kerberos
principal names to SAF identities, select the Use the KERB segment
of a SAF user profiler radio button to o use the built-in mapping
module to map a Kerberos principal name to System Authorization Facility
(SAF) identity on z/OS®.
This mapping only takes place when the active user registry
is Local OS.
Note: The built-in mapping module uses the full Kerberos
principal name and Kerberos realm for the mapping, regardless of what
the Trim Kerberos realm from principal name field is set to.
- Click OK.
- Optional: Configure SAF to not
use the APPL class for restricting access to applications running
on WebSphere Application
Server. The default value is enabled. You might want to disable checking
the SAF APPL class if this class was previously inactive on your z/OS security server, but will
then be activated after configuring the z/OS KDC.
To disable it in the administrative console:
- Click Security >
Global Security > External authorization
providers.
- Ensure that System Authorization Facility
(SAF) authorization is
selected from the drop-down menu.
- Click Configure.
- Deselect Use APPL profile to restrict access to WebSphere Application Server.
For
more information on this setting, read about the z/OS
System Authorization Facility authorization.
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.