.. highlight:: none

Migrating from pam\_krb5 to sssd
================================

*pam\_krb5* was a Pluggable Authentication Module (PAM) for performing
user session authentication against Kerberos (specifically, krb5). Red
Hat formally announced its deprecation in the RHEL-7.4 release.

System Security Services Daemon (*sssd*) is a broader toolsuite for
managing authentication mechanisms and remote directories. It includes a
PAM module, pam\_sss, which can perform the tasks for which pam\_krb5
was previously used.

Architecturally, pam\_krb5 was a monolithic module which performed all
needed tasks within itself. sssd is set up differently: the module
pam\_sss calls out to the running sssd itself for most functionality.

Note: sssd does not currently handle the AFS capabilities of pam\_krb5.
If you would like such functionality, please contact Red Hat Support.

Core functionality
------------------

We will first show an example migration, and then provide detailed
information about specific options.

pam\_krb5 had both PAM configuration and a snippet in krb5.conf. The PAM
configuration would have looked similar to

::

    auth required /lib64/security/pam_krb5.so
    session optional /lib64/security/pam_krb5.so
    account sufficient /lib64/security/pam_krb5.so
    password sufficient /lib64/security/pam_krb5.so

and krb5.conf:

::

    [appdefaults]
        pam = {
            validate = true
            ccache_dir = /var/tmp
            TEST.EXAMPLE.COM = {
                debug = true
                keytab = FILE:/etc/krb5.keytab
            }
        }

The PAM configuration for sssd is very similar:

::

    auth required pam_sss.so
    session optional pam_sss.so
    account sufficient pam_sss.so
    password sufficient pam_sss.so

and in sssd.conf we would add:

::

    [sssd]
        services = nss, pam
        domains = TEST.EXAMPLE.COM

    [domain/TEST.EXAMPLE.COM]
        id_provider = files # set to ldap if LDAP is in use, etc.
        auth_provider = krb5
        krb5_realm = TEST.EXAMPLE.COM
        debug_level = 5
        krb5_validate = true
        krb5_ccachedir = /var/tmp # note that RHEL-7 default to KERNEL ccaches, which are preferred in most cases to FILE
        krb5_keytab = /etc/krb5.keytab

Detailed options (by type)
~~~~~~~~~~~~~~~~~~~~~~~~~~

Wholly deprecated (no replacement)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following pam\_krb5 options have no replacement due to only being
useful for AFS: **afs\_cells**, **external**, **ignore\_afs**,
**null\_afs**, **tokens**, **tokens\_strategy**.

Debugging
^^^^^^^^^

Debugging in pam\_krb5 was controlled by the **debug**,
**debug\_sensitive**, and **trace** options. The debugging of pam\_sss
is not configurable (everything is logged and can be filtered
appropriately). Debugging sssd itself is controlled by the
**debug\_level** parameter of sssd.conf, and can also be adjusted
dynamically using ``sss_debuglevel``. At higher levels, krb5 tracing is
enabled. Sensitive messages are not forwarded from the daemon to the PAM
application unless the value of **pam\_verbosity** is increased above
the default.

Prompting
^^^^^^^^^

pam\_krb5 used the options **banner**, **chpw\_prompt**, and **pwhelp**
to display custom messages to the user when prompting for input. There
is no direct replacement for these; however, an expiration messsage
(**pam\_account\_expired\_message**) and account lockout message
(**pam\_account\_locked\_message**) can be set. See documentation on
pam\_verbosity (in sssd.conf(5)) for more information on when these are
displayed.

pam\_krb's prompting options (**chpw\_prompt**, **initial\_prompt**,
**no\_initial\_prompt**, **subsequent\_prompt**,
**no\_subsequent\_prompt**, **use\_first\_pass**, **try\_first\_pass**,
and **use\_authtok**) are replaced by controls in pam\_sss. In
particular, **use\_authtok** and **use\_first\_pass** keep name and
functionality. The behavior coded by **try\_first\_pass** is the sssd
default. All other prompting is can be enabled by setting
**prompt\_always**. For more information, see pam\_sss(8).

Credential management
^^^^^^^^^^^^^^^^^^^^^

The pam\_krb5 **ccache\_dir**, **ccname\_template**, **keytab**, and
**validate** / **no\_validate** options map to the sssd.conf options
**krb5\_ccachedir**, **krb5\_ccname\_template**, **krb5\_keytab**, and
**krb5\_validate**, respectively. By default, validation is not enabled,
unless the Kerberos provider is IPA or Active Directory. See
sssd-krb5(5) for more information.

pam\_krb5's **validate\_user\_user**, **multiple\_ccaches**, and
**cred\_session** options have no sssd equivalent. Please contact Red
Hat Support if you would like such functionality.

Localauth / .k5login
^^^^^^^^^^^^^^^^^^^^

sssd and pam\_krb5 have different approaches here. In order to enable
.k5login-based access control, set **access\_provider** to krb5 in
sssd.conf. sssd also includes its own localauth plugin (which is
typically enabled using a configuration snippet in /etc/krb5.conf.d).
This replaces the **always\_allow\_localname** and \*\*ignore\_k5login\*
settings from pam\_krb5.

pam\_krb5's **mappings** rules are replaced by **krb5\_map\_user** rules
in sssd. Note that sssd does not support the use of regular expressions
for these rules. Since in both cases it is typically necessary to
configure **auth\_to\_local** in krb5.conf with the inverse, it is
recommended to keep these mappings simple.

sssd refuses to admit users that do not exist (i.e., that cannot be
resolved through its NSS interface). Therefore, the **no\_user\_check**
option from pam\_krb5 (previously marked as potentially dangerous) has
no sssd analogue.

Other
^^^^^

pam\_krb5's **ignore\_unknown\_principals**, **ignore\_unknown\_spn**,
and **ignore\_unknown\_upn** options are united as the pam\_sss
**ignore\_unknown\_user** option. However, as above, note that sssd will
not authenticate users that cannot be resolved. Additionally, for users
whose information cannot be obtained from LDAP (or who do not exist in
LDAP), sssd falls back to "username@REALM".

**minimum\_uid** is called **min\_id** in sssd.conf. Additionally,
sssd.conf allows **max\_id** to limit the maximum UID to check. Note
that this also affects NSS user resolution.

**preauth\_options** is superseded by the certmap rules; see
sss-certmap(5) for more information.

**armor** is superseded by sssd's **krb5\_use\_fast** option. The
**armor\_strategy** option has no direct equivalent in sssd; sssd's
behavior is comparable to that which would have been configured by
setting **armor\_strategy** to *keytab*.

**use\_shmem** does not apply to sssd due to architectural differences.

Tools
-----

pam\_krb5 also included four binaries. Three of them were useful only
for AFS-related work, and no replacement is provided: ``afs5log``,
``pagsh``, and ``pam_newpag``.

The fourth, ``pam_krb5_cchelper``, was intended as an internal tool for
pam\_krb5's use. sssd has its own internal management that is not
exposed to end users. ``pam_krb5_cchelper``'s functionality can be
replicated using ``kinit -c`` or ``kdestroy -c``, and calling ``chown``
and ``chgrp`` as needed.