Troubleshooting Kerberos

Sources of diagnostic information and detail of some specific exceptions

Where to look for more information

In general, if you experience an error, check for information in the following trace files:

CICS® trace

XS Exception Trace

Look for calls to R_TICKETSERV. A specimen trace record follows:

XS FE04 XSSK *EXC* FUNCTION(INQUIRE_CLIENT_PRINCIPAL) RESPONSE(EXCEPTION) REASON(INVALID_TOKEN) SAF_RESPONSE(8) SAF_REASON(0) ESM_RESPONSE(10) ESM_REASON(861B6D0B) ESM_SERVICE_NAME(R_TICKETSERV) PRINCIPAL_NAME(000704DA , 000000F4 , 000000F4) USERID_LENGTH(0) USERID()

Identify the response code and look it up in z/OS Security Server RACF Callable Services or RACF and z/OS Integrated Security Services Network Authentication Service.

Full trace for XS trace points x'0A01' , x'0A02', x'FE01', x'FE02', and x'FE04' can show additional information to aid diagnosis. For example, it can show the values of a principal name and of a Kerberos token, before and after base-64 conversion.

SKRKBDC logs

The Key Distribution Centre task SKRBKDC can produce useful messages in its output. For example, the following message might be written to SYSOUT:

EUVF04039W Kerberos login failed for ROBOT@CLOUD.IBM.COM at 9.20.141.141:33063: KDC status 0x96c73a06 - Client principal is not found in security registry.

To obtain more information from SKRBKDC, turn on all trace by issuing the following commands:

F SKRBKDC,DEBUG *.9 F SKRBKDC,DEBUG ON

For more information, see RACF and z/OS Integrated Security Services Network Authentication Service.

SKRKBDC spool files

z/OS® Integrated Security Services Network Authentication provides environment variables that can be used as an aid to diagnosis. For more information see RACF and z/OS Integrated Security Services Network Authentication Service. Note that some of these variables are intended to be used only under the direction of IBM® Service Personnel.

Calls by CICS to z/OS Callable Services and an External Security Manager

Error messages can be written to destination CSCS if errors occur while you are using Kerberos. For example, such messages can be produced if a web service that uses Kerberos fails because of a Kerberos related security failure, or if an EXEC CICS VERIFY TOKEN command does not execute as expected. In the case of an EXEC CICS VERIFY TOKEN command, these messages are in addition to the conditions and EIBRESP2 values produced.

As an aid to showing Kerberos-related identifiers in use by CICS TS, the following messages can be produced during CICS TS initialization:

DFHXS1400 03/04/2014 15:31:36 IYKZZZZ Kerberos realm is MVS2.IBM.COM DFHXS1401 03/04/2014 15:31:36 IYKZZZZ Kerberos principal name is cloud_cics512

Information about specific messages

DFHXS1402 with reason = R_TICKETSERV service responded invalid server principal name.: The server principal name is the Kerberos principal name specified in message DFHXS1401. If you use Tivoli® Federated Identity Manager, set the Kerberos Service Name in the Kerberos Module Configuration to this value.
DFHXS1402 with reason = R_TICKETSERV service responded invalid kerberos token.: A possible reason for this error is that you used an unsupported Kerberos format type, such as http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ. For a list of supported format types, see The <authentication> element.
DFHXS1402 with reason = 'Kerberos not configured': The region has not been configured to support the Kerberos service. For the region to use Kerberos, you must set the KERBEROSUSER system initialization parameter, which specifies a user ID to be associated with the Kerberos service principal.

Information about specific exceptions

INVREQ exception condition with RESP2=40: The key distribution center is not started or is terminating: You must have a key distribution center (KDC) running on the same LPAR as the CICS region that issued the VERIFY TOKEN command. The KDC is the SKRBKDC Started Task that supplies the Network Authentication Service for z/OS.
NOTAUTH exception condition with RESP2=20: The user is not authorized to use this service: RACF® errors do not cause a RACF violation in CICS, or messages in the KDC. The user in this case is likely to be the default user of the CICS region, rather than the CICS region user ID or the ID of the Kerberos Ticket.