Configuring Kerberos as the authentication mechanism using the administrative console

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

The following items are required before you attempt to configure Kerberos as the authentication mechanism using the administrative console:

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

  1. In the administrative console, click Security > Global security.
  2. From Authentication, click Kerberos configuration.
  3. 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 <serviceName>/<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.
  4. 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 filename 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 a variable ${CONF_OR_INI} 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}
  5. 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 filename path do not have to be absolute paths. You can use WebSphere variables for the paths instead.
    ${WAS_INSTALL_ROOT}\etc\krb5\krb5.keytab
  6. 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 would usually have a Kerberos realm name of AUSTIN.IBM.COM.

    Note: The Kerberos realm name for the Microsoft® KDC is an uppercase of the Microsoft Domain Controller name.
  7. Optional: Trim Kerberos realm from principal name is selected by default. You can deselect 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: You must set this field to true if you are using both the Local Operating System registry on z/OS and the built-in mapping module to map Kerberos principals to SAF identities.
  8. 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 cannot extract a client GSS delegation credential, then a warning message is displayed.
  9. Optional: Use built-in mapping module to map Kerberos principals to SAF identities is not selected by default. You can select this option if you want to 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.
    Note: There is some additional setup required. Read Mapping a Kerberos principal to a System Authorization Facility (SAF) identity on z/OS for more information.
    Avoid trouble Avoid trouble: If you select the option to use the built-in mapping module, you should not configure other custom JAAS login modules to map the Kerberos principal to a SAF identity.gotcha
  10. Click OK.
    Note: 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.
  11. 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:
    1. Click Security > Global Security > External authorization providers.
    2. Ensure that System Authorization Facility (SAF) authorization is selected from the drop-down menu.
    3. Click Configure.
    4. Deselect Use APPL profile to restrict access to WebSphere Application Server.

    For more information on this setting, read about z/OS System Authorization Facility authorization.

Results

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.



In this information ...


Related tasks

IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Feb 5, 2014 9:49:51 PM CST
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-mp&topic=tsec_kerb_auth_mech
File name: tsec_kerb_auth_mech.html