Solving SSH/Kerberos Problems

 » Table of Contents

 » Glossary

 » Index

Kerberos, while powerful, can be cumbersome to configure and deploy. Often, problems that occur with Kerberos are related to misconfiguration of Kerberos, not a software problem with the applications using it. To help determine the cause of connection problems, you can set the following configuration parameters:

  • The GssapiSendError parameter tells the SSH server in gssapi-with-mic authentication mode to send a GSSAPI error message (SSH_MSG_USERAUTH_GSSAPI_ERROR) to the client when an error occurs. This message provides information about the error and is usually displayed to the client user.

    A yes value tells the SSH server to send a GSSAPI error message. A no value tells it not to send the message. By default, his parameter is set to no.

  • The GssapiSendErrtok parameter tells the SSH server or client in gssapi-with-mic authentication mode to send the SSH_MSG_USERAUTH_GSSAPI_ERRTOK message to the peer when an error occurs. This message contains a gssapi error token that is decoded on the peer and causes diagnostic information to be displayed.

    A yes value tells the SSH client or server to send the SSH_MSG_USERAUTH_GSSAPI_ERRTOK message. A no value tells it not to send the SSH_MSG_USERAUTH_GSSAPI_ERRTOK message. This parameter defaults to no.

The following list describes how to respond to some of the common errors related to using SSH with Kerberos:

  • Expired Kerberos ticket

    Kerberos tickets have expiration dates. If you attempt to use the SSH client to connect using a Kerberos authentication method and your ticket has expired, the following message is displayed:

    $ ssh -o"AllowedAuthentications kerberos-2@ssh.com smith@sysb
    Kerberos5 authentication failed: Your ticket has expired. Use kinit
  • Nonforwardable Kerberos ticket with kerberos-tgt-2

    When you use the kerberos-tgt-2 authentication method, your kinit command must include the -f option to tell Kerberos that you want a forwardable TGT. If you have not specified kinit with -f and try to use SSH with kerberos-tgt-2 authentication, the following message is displayed:

    $ ssh -o"AllowedAuthentications kerberos-tgt-2@ssh.com" smith@sysb
    Kerberos5 TGT forwarding failed: Ticket not forwardable? Try using kinit -f
  • No Kerberos ticket at all

    If you use Kerberos based SSH authentication without having issued a kinit command to get a Kerberos TGT, you see this message:

    SYSA> ssh -o"AllowedAuthentications kerberos-tgt-2@ssh.com" smith@sysb
    Kerberos5 TGT forwarding failed: You have no ticket. Use kinit -f
  • Internal credentials cache error with gssapi-with-mic

    You have tried to use the gssapi-with-mic authentication method with a forwardable TGT and the GssapiDelegateCredentials client parameter is set to yes (the default). Authentication fails. The following message is displayed:

    MYHOST> ssh -o"allowedauthentications gssapi-with-mic" -
    _MYHOST> -o"GssapiDelegateCredentials yes" smith@sysb
    GSSAPI error from server: Miscellaneous failure
                              Internal credentials cache error
    warning: Authentication failed.

    This type of failure causes the following warning in the SSH server log file:

    Mon 12 06:43:13 WARNING: Miscellaneous failure
    Internal credentials cache error

    This message is only displayed to the SSH client user if the GssapiSendError server configuration parameter is set to no.

    To correct the problem while using forwardable tickets, set the GssapiDelegateCredentials client configuration parameter for this session by entering the command as follows:

    # ssh -o"allowedauthentications gssapi-with-mic" -
    _$ -o"GssapiDelegateCredentials no" smith@sysb

    To continue without change the configuration options and without using forwardable tickets, enter the kinit again, without the -f option. This command requesets a nonforwardable ticket.

Many problems are caused by errors in systemwide or Kerberos configuration. Misconfiguration can cause problems like:

  • Your SSH server log file shows the following error when trying to authenticate using gssapi-with-mic:

    Mon 12 09:37:37 WARNING: Miscellaneous failure
    Wrong principal in request

    The problem could be an incorrect local host database entry on the SSH server for the SSH server itself. Make sure the fully-qualified host name is used. Note that this message applies only to gssapi-with-mic authentication.

  • Your SSH server log file shows the following error when trying to authenticate using gssapi-with-mic:

    Mon 19 09:19:37 WARNING: Miscellaneous failure
    No principal in keytab matches desired name

    This problem can be caused by a missing or incorrect host principal for the SSH server, or the host principal is correct but the keytab entry is missing or incorrect. This is how the problem manifests itself with gssapi-with-mic authentication.

  • Your SSH client displays something similar to the following:

    $ ssh -o"AllowedAuthentications kerberos-2@ssh.com" smith@sysb
    Kerberos5 authentication failed: krb5_get_credentials(): KRB5KDC_ERR_S_PRINCIPAL_UNKNOWN
    warning: Authentication failed.

    This problem can be caused by a missing or incorrect host principal for the SSH server, or the host principal is correct but the keytab entry is missing or incorrect. This is how the problem manifests itself with the kerberos-2 or kerberos-tgt-2 authentication.

  • The SSH client or server (in the SSH server log) shows a message simlar to one of these:

    WARNING: kerberos-2@ssh.com authentication failed since Kerberos wasn't initialized.
    WARNING: gssapi-with-mic authentication failed since Kerberos wasn't initialized.

    This message indicates that Kerberos for OpenVMS has not been installed properly. Refer to the HP Open Source Security for OpenVMS Volume 3: Kerberos manual for installation instructions to remedy the situation.

If SSH with Kerberos authentication fails, it is helpful to test another Kerberized application, such as TELNET, which will often fail in the same way as does SSH, pointing to a problem with Kerberos configuration, rather than to an SSH software problem.

The SSH server and client diagnostics features show errors and warnings indicating problems with calls to Kerberos library routines. These types of errors list the Kerberos routine that failed and the failure return status.

When you repeatedly make changes to host principals and keytab entries and files, existing tickets in the credentials cache can contain stale information, making it appear that your changes to the Kerberos configuration have not taken effect. Use the kdestroy and kinit commands to clear the credentials cache before testing your configuration changes.