view release on metacpan or  search on metacpan

t/data/update/pam-krb5/docknot.yaml  view on Meta::CPAN

  user:
  - name: pam-krb5
    title: Manual page
format: v1
license:
  name: BSD-3-clause-or-GPL-1+
maintainer: Russ Allbery <eagle@eyrie.org>
name: pam-krb5
quote:
  author: Joyce McGreevy
  date: 2003-11-17
  text: |
    "You're always going to have some people who can't appreciate the thrill
    of a tepid change for the somewhat better," explained one source.
  title: '"Look, ma, no hands!"'
  work: Salon
requirements: |
  Either MIT Kerberos (or Kerberos implementations based on it) or Heimdal
  are supported.  MIT Keberos 1.3 or later may be required; this module has
  not been tested with earlier versions.

  For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later
  are required.  Earlier MIT Kerberos 1.6 releases have a bug in their
  handling of PKINIT options.

  For FAST (Flexible Authentication Secure Tunneling) support, MIT Kerberos
  1.7 or higher is required.  For anonymous FAST support, anonymous
  authentication (generally anonymous PKINIT) support is required in both
  the Kerberos libraries and in the local KDC.

  This module should work on Linux and Solaris (and build with gcc, clang,
  or the Sun C compiler), but has been far more heavily tested on Linux.
  There is beta-quality support for the AIX NAS Kerberos implementation.
  Other PAM implementations will probably require some porting, although
  untested build system support is present for FreeBSD, Mac OS X, and HP-UX.
  I personally can only test on Linux and rely on others to report problems
  on other operating systems.

  Old versions of OpenSSH are known to call `pam_authenticate` followed by
  `pam_setcred(PAM_REINITIALIZE_CRED)` without first calling
  `pam_open_session`, thereby requesting that an existing ticket cache be
  renewed (similar to what a screensaver would want) rather than requesting
  a new ticket cache be created.  Since this behavior is indistinguishable
  at the PAM level from a screensaver, pam-krb5 when used with these old
  versions of OpenSSH will refresh the ticket cache of the OpenSSH daemon
  rather than setting up a new ticket cache for the user.  The resulting
  ticket cache will have the correct permissions (this is not a security
  concern), but will not be named correctly or referenced in the user's
  environment and will be overwritten by the next user login.  The best
  solution to this problem is to upgrade OpenSSH.  I'm not sure exactly when
  this problem was fixed, but at the very least OpenSSH 4.3 and later do not
  exhibit it.
sections:
- body: |
    Just installing the module does not enable it or change anything about
    your system authentication configuration.  To use the module for all
    system authentication on Debian systems, put something like:

    ```
        auth  sufficient   pam_krb5.so minimum_uid=1000
        auth  required     pam_unix.so try_first_pass nullok_secure
    ```

    in `/etc/pam.d/common-auth`, something like:

    ```
        session  optional  pam_krb5.so minimum_uid=1000
        session  required  pam_unix.so
    ```

    in `/etc/pam.d/common-session`, and something like:

    ```
        account  required  pam_krb5.so minimum_uid=1000
        account  required  pam_unix.so
    ```

    in `/etc/pam.d/common-account`.  The `minimum_uid` setting tells the PAM
    module to pass on any users with a UID lower than 1000, thereby bypassing
    Kerberos authentication for the root account and any system accounts.  You
    normally want to do this since otherwise, if the network is down, the
    Kerberos authentication can time out and make it difficult to log in as
    root and fix matters.  This also avoids problems with Kerberos principals
    that happen to match system accounts accidentally getting access to those
    accounts.

    Be sure to include the module in the session group as well as the auth
    group.  Without the session entry, the user's ticket cache will not be
    created properly for ssh logins (among possibly others).

    If your users should normally all use Kerberos passwords exclusively,
    putting something like:

    ```
        password sufficient pam_krb5.so minimum_uid=1000
        password required   pam_unix.so try_first_pass obscure md5
    ```

    in `/etc/pam.d/common-password` will change users' passwords in Kerberos
    by default and then only fall back on Unix if that doesn't work.  (You can
    make this tighter by using the more complex new-style PAM configuration.)
    If you instead want to synchronize local and Kerberos passwords and change
    them both at the same time, you can do something like:

    ```
        password required   pam_unix.so obscure sha512
        password required   pam_krb5.so use_authtok minimum_uid=1000
    ```

    If you have multiple environments that you want to synchronize and you
    don't want password changes to continue if the Kerberos password change
    fails, use the `clear_on_fail` option.  For example:

    ```
        password required   pam_krb5.so clear_on_fail minimum_uid=1000
        password required   pam_unix.so use_authtok obscure sha512
        password required   pam_smbpass.so use_authtok
    ```

    In this case, if `pam_krb5` cannot change the password (due to password
    strength rules on the KDC, for example), it will clear the stored password
    (because of the `clear_on_fail` option), and since `pam_unix` and
    `pam_smbpass` are both configured with `use_authtok`, they will both fail.
    `clear_on_fail` is not the default because it would interfere with the
    more common pattern of falling back to local passwords if the user doesn't
    exist in Kerberos.

    If you use a more complex configuration with the Linux PAM `[]` syntax for
    the session and account groups, note that `pam_krb5` returns a status of
    ignore, not success, if the user didn't log on with Kerberos.  You may
    need to handle that explicitly with `ignore=ignore` in your action list.

    There are many, many other possibilities.  See the Linux PAM documentation
    for all the configuration options.

    On Red Hat systems, modify `/etc/pam.d/system-auth` instead, which
    contains all of the configuration for the different stacks.

    You can also use pam-krb5 only for specific services.  In that case,
    modify the files in `/etc/pam.d` for that particular service to use
    `pam_krb5.so` for authentication.  For services that are using passwords
    over TLS to authenticate users, you may want to use the `ignore_k5login`
    and `no_ccache` options to the authenticate module.  `.k5login`
    authorization is only meaningful for local accounts and ticket caches are
    usually (although not always) only useful for interactive sessions.

    Configuring the module for Solaris is both simpler and less flexible,
    since Solaris (at least Solaris 8 and 9, which are the last versions of
    Solaris with which this module was extensively tested) use a single
    `/etc/pam.conf` file that contains configuration for all programs.  For
    console login on Solaris, try something like:

    ```
        login auth sufficient /usr/local/lib/security/pam_krb5.so minimum_uid=100
        login auth required /usr/lib/security/pam_unix_auth.so.1 use_first_pass
        login account required /usr/local/lib/security/pam_krb5.so minimum_uid=100
        login account required /usr/lib/security/pam_unix_account.so.1
        login session required /usr/local/lib/security/pam_krb5.so retain_after_close minimum_uid=100
        login session required /usr/lib/security/pam_unix_session.so.1
    ```

    A similar configuration could be used for other services, such as ssh.
    See the pam.conf(5) man page for more information.  When using this module
    with Solaris login (at least on Solaris 8 and 9), you will probably also
    need to add `retain_after_close` to the PAM configuration to avoid having
    the user's credentials deleted before they are logged in.

    The Solaris Kerberos library reportedly does not support prompting for a
    password change of an expired account during authentication.  Supporting
    password change for expired accounts on Solaris with native Kerberos may
    therefore require setting the `defer_pwchange` or `force_pwchange` option
    for selected login applications.  See the description and warnings about
    that option in the pam_krb5(5) man page.

    Some configuration options may be put in the `krb5.conf` file used by your
    Kerberos libraries (usually `/etc/krb5.conf` or
    `/usr/local/etc/krb5.conf`) instead or in addition to the PAM
    configuration.  See the man page for more details.

    The Kerberos library, via pam-krb5, will prompt the user to change their
    password if their password is expired, but when using OpenSSH, this will
    only work when `ChallengeResponseAuthentication` is enabled.  Unless this
    option is enabled, OpenSSH doesn't pass PAM messages to the user and can
    only respond to a simple password prompt.

    If you are using MIT Kerberos, be aware that users whose passwords are
    expired will not be prompted to change their password unless the KDC
    configuration for your realm in `[realms]` in `krb5.conf` contains a
    `master_kdc` setting or, if using DNS SRV records, you have a DNS entry
    for `_kerberos-master` as well as `_kerberos`.
  title: Configuring
- body: |
    The first step when debugging any problems with this module is to add
    `debug` to the PAM options for the module (either in the PAM configuration
    or in `krb5.conf`).  This will significantly increase the logging from the
    module and should provide a trace of exactly what failed and any available
    error information.

    Many Kerberos authentication problems are due to configuration issues in
    `krb5.conf`.  If pam-krb5 doesn't work, first check that `kinit` works on
    the same system.  That will test your basic Kerberos configuration.  If
    the system has a keytab file installed that's readable by the process
    doing authentication via PAM, make sure that the keytab is current and
    contains a key for `host/<system>` where <system> is the fully-qualified
    hostname.  pam-krb5 prevents KDC spoofing by checking the user's
    credentials when possible, but this means that if a keytab is present it
    must be correct or authentication will fail.  You can check the keytab
    with `klist -k` and `kinit -k`.

    Be sure that all libraries and modules, including PAM modules, loaded by a
    program use the same Kerberos libraries.  Sometimes programs that use PAM,
    such as current versions of OpenSSH, also link against Kerberos directly.
    If your sshd is linked against one set of Kerberos libraries and pam-krb5
    is linked against a different set of Kerberos libraries, this will often
    cause problems (such as segmentation faults, bus errors, assertions, or
    other strange behavior).  Similar issues apply to the com_err library or
    any other library used by both modules and shared libraries and by the
    application that loads them.  If your OS ships Kerberos libraries, it's
    usually best if possible to build all Kerberos software on the system