PAM_KRB5(5) | pam-krb5 | PAM_KRB5(5) |
pam_krb5 - Kerberos PAM module
auth sufficient pam_krb5.so minimum_uid=1000 session required pam_krb5.so minimum_uid=1000 account required pam_krb5.so minimum_uid=1000 password sufficient pam_krb5.so minimum_uid=1000
The Kerberos service module for PAM, typically installed at /lib/security/pam_krb5.so, provides functionality for the four PAM operations: authentication, account management, session management, and password management. pam_krb5.so is a shared object that is dynamically loaded by the PAM subsystem as necessary, based on the system PAM configuration. PAM is a system for plugging in external authentication and session management modules so that each application doesn't have to know the best way to check user authentication or create a user session on that system. For details on how to configure PAM on your system, see the PAM man page, often pam(7).
Here are the actions of this module when called from each group:
Passwords as long or longer than PAM_MAX_RESP_SIZE octets (normally 512 octets) will be rejected, since excessively long passwords can be used as a denial of service attack.
After doing the initial authentication, the Kerberos PAM module will attempt to obtain tickets for a key in the local system keytab and then verify those tickets. Unless this step is performed, the authentication is vulnerable to KDC spoofing, but it requires that the system have a local key and that the PAM module be running as a user that can read the keytab file (normally /etc/krb5.keytab. You can point the Kerberos PAM module at a different keytab with the keytab option. If that keytab cannot be read or if no keys are found in it, the default (potentially insecure) behavior is to skip this check. If you want to instead fail authentication if the obtained tickets cannot be checked, set "verify_ap_req_nofail" to true in the [libdefaults] section of /etc/krb5.conf. Note that this will affect applications other than this PAM module.
By default, whenever the user is authenticated, a basic authorization check will also be done using krb5_kuserok(). The default behavior of this function is to check the user's account for a .k5login file and, if one is present, ensure that the user's principal is listed in that file. If .k5login is not present, the default check is to ensure that the user's principal is in the default local realm and the user portion of the principal matches the account name (this can be changed by configuring a custom aname to localname mapping in krb5.conf; see the Kerberos documentation for details). This can be customized with several configuration options; see below.
If the username provided to PAM contains an "@" and Kerberos can, treating the username as a principal, map it to a local account name, pam_authenticate() will change the PAM user to that local account name. This allows users to log in with their Kerberos principal and let Kerberos do the mapping to an account. This can be disabled with the no_update_user option. Be aware, however, that this facility cannot be used with OpenSSH. OpenSSH will reject usernames that don't match local accounts before this remapping can be done and will pass an invalid password to the PAM module. Also be aware that several other common PAM modules, such as pam_securetty, expect to be able to look up the user with getpwnam() and cannot be called before pam_krb5 when using this feature.
When pam_setcred() is called to initialize a new ticket cache, the environment variable KRB5CCNAME is set to the path to that ticket cache. By default, the cache will be named /tmp/krb5cc_UID_RANDOM where UID is the user's UID and RANDOM is six randomly-chosen letters. This can be configured with the ccache and ccache_dir options.
pam-krb5 does not use the default ticket cache location or default_cc_name in the "[libdefaults]" section of krb5.conf. The default cache location would share a cache for all sessions of the same user, which causes confusing behavior when the user logs out of one of multiple sessions.
If pam_setcred() initializes a new ticket cache, it will also set up that ticket cache so that it will be deleted when the PAM session is closed. Normally, the calling program (login, sshd, etc.) will run the user's shell as a sub-process, wait for it to exit, and then close the PAM session, thereby cleaning up the user's session.
Passwords as long or longer than PAM_MAX_RESP_SIZE octets (normally 512 octets) will be rejected, since excessively long passwords can be used as a denial of service attack.
Unlike the normal Unix password module, this module will allow any user to change any other user's password if they know the old password. Also, unlike the normal Unix password module, root will always be prompted for the old password, since root has no special status in Kerberos. (To change passwords in Kerberos without knowing the old password, use kadmin(8) instead.)
Both the account and session management calls of the Kerberos PAM module will return PAM_IGNORE if called in the context of a PAM session for a user who did not authenticate with Kerberos (a return code of "ignore" in the Linux PAM configuration language).
Note that this module assumes the network is available in order to do a Kerberos authentication. If the network is not available, some Kerberos libraries have timeouts longer than the timeout imposed by the login process. This means that using this module incautiously can make it impossible to log on to console as root. For this reason, you should always use the ignore_root or minimum_uid options, list a local authentication module such as pam_unix first with a control field of "sufficient" so that the Kerberos PAM module will be skipped if local password authentication was successful.
This is not the same PAM module as the Kerberos PAM module available from Sourceforge, or the one included on Red Hat systems. It supports many of the same options, has some additional options, and doesn't support some of the options those modules do.
The Kerberos PAM module takes many options, not all of which are relevant to every PAM group; options that are not relevant will be silently ignored. Any of these options can be set in the PAM configuration as arguments listed after "pam_krb5.so". Some of the options can also be set in the system krb5.conf file; if this is possible, it will be noted below in the option description.
To set a boolean option in the PAM configuration file, just give the name of the option in the arguments. To set an option that takes an argument, follow the option name with an equal sign (=) and the value, with no separating whitespace. Whitespace in option arguments is not supported in the PAM configuration.
To set an option for the PAM module in the system krb5.conf file, put that option in the "[appdefaults]" section. All options must be followed by an equal sign (=) and a value, so for boolean options add "= true". The Kerberos PAM module will look for options either at the top level of the "[appdefaults]" section or in a subsection named "pam", inside or outside a section for the realm. For example, the following fragment of a krb5.conf file would set forwardable to true, minimum_uid to 1000, and set ignore_k5login only if the realm is EXAMPLE.COM.
[appdefaults] forwardable = true pam = { minimum_uid = 1000 EXAMPLE.COM = { ignore_k5login = true } }
For more information on the syntax of krb5.conf, see krb5.conf(5). Note that options that depend on the realm will be set only on the basis of the default realm, either as configured in krb5.conf(5) or as set by the realm option described below. If the user authenticates to an account qualified with a realm, that realm will not be used when determining which options will apply.
There is no difference to the PAM module whether options are specified at the top level or in a "pam" section; the "pam" section is supported in case there are options that should be set for the PAM module but not for other applications.
If the same option is set in krb5.conf and in the PAM configuration, the latter takes precedent. Note, however, that due to the configuration syntax, there's no way to turn off a boolean option in the PAM configuration that was turned on in krb5.conf.
The start of each option description is annotated with the version of pam-krb5 in which that option was added with the current meaning.
If this option is present, the default behavior is to try this alternate principal first and then fall back to the standard behavior if it fails. The primary usage is to allow alternative principals to be used for authentication in programs like sudo. Most examples will look like:
alt_auth_map=%s/root
which attempts authentication as the root instance of the username first and then falls back to the regular username (but see force_alt_auth and only_alt_auth).
This option also allows a cheap way to attempt authentication in an alternative realm first and then fall back to the primary realm. A setting like:
alt_auth_map=%s@EXAMPLE.COM
will attempt authentication in the EXAMPLE.COM realm first and then fall back on the local default realm. This is more convenient than running the module multiple times with multiple default realms set with realm, but it is very limited: only two realms can be tried, and the alternate realm is always tried first.
This option can be set in "[appdefaults]" in krb5.conf, although normally it doesn't make sense to do that; normally it is used in the PAM options of configuration for specific programs. It is only applicable to the auth and account groups. If this option is set for the auth group, be sure to set it for the account group as well or account authorization may fail.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and account groups.
This option can be set in "[appdefaults]" in krb5.conf.
Using this option is highly recommended if you don't need to use Kerberos to authenticate password logins to the root account (which isn't recommended since Kerberos requires a network connection). It provides some defense in depth against user principals that happen to match a system account incorrectly authenticating as that system account.
This option can be set in "[appdefaults]" in krb5.conf.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
FAST is a mechanism to protect Kerberos against password guessing attacks and provide other security improvements. To work, FAST requires that a ticket be obtained with a strong key to protect exchanges with potentially weaker user passwords. This option uses anonymous authentication to obtain that key and then uses it to protect the subsequent authentication.
If anonymous PKINIT is not available or fails, FAST will not be used and the authentication will proceed as normal.
To instead use an existing ticket cache for the FAST credentials, use fast_ccache instead of this option. If both fast_ccache and anon_fast are set, the ticket cache named by fast_ccache will be tried first, and the Kerberos PAM module will fall back on attempting anonymous PKINIT if that cache could not be used.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
The operation is the same as if using the fast_ccache option, but the cache is created and destroyed automatically. If both fast_ccache and anon_fast options are used, the fast_ccache takes precedent and no anonymous authentication is done.
<ccache_name> should be a credential cache containing a ticket obtained using a strong key, such as the randomized key for the host principal of the local system. If <ccache_name> names a ticket cache that is readable by the authenticating process and has tickets then FAST will be attempted. The easiest way to use this option is to use a program like k5start to maintain a ticket cache using the host's keytab. This ticket cache should normally only be readable by root, so this option will not be able to protect authentications done as non-root users (such as screensavers).
If no credentials are present in the ticket cache, or if the ticket cache does not exist or is not readable, FAST will not used and authentication will proceed as normal. However, if the credentials in that ticket cache are expired, authentication will fail if the KDC supports FAST.
To use anonymous PKINIT to protect the FAST exchange, use the anon_fast option instead. anon_fast is easier to configure, since no existing ticket cache is required, but requires PKINIT be available and configured and that the local realm support anonymous authentication. If both fast_ccache and anon_fast are set, the ticket cache named by fast_ccache will be tried first, and the Kerberos PAM module will fall back on attempting anonymous PKINIT if that cache could not be used.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
If you only want to set the realm assumed for user principals without changing the realm for authorization decisions or the service principal used to verify credentials, see the user_realm option.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
Setting this option provides a way to work around this behavior. If this option is set and a Kerberos password change is attempted and fails (due to network errors or password strength checking on the KDC, for example), this module will clear the stored password in the PAM stack. This will force any subsequent modules that have use_authtok set to fail so that those environments won't get out of sync with the password in Kerberos. The Kerberos PAM module will not meddle with the stored password if it skips the user due to configuration such as minimum_uid.
Unfortunately, setting this option interferes with other desirable PAM configurations, such as attempting to change the password in Kerberos first and falling back on the local Unix password database if that fails. It therefore isn't the default. Turn it on (and list pam_krb5 first after pam_cracklib if used) when synchronizing passwords between multiple environments.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the password group.
This option can be set in "[appdefaults]" in krb5.conf.
According to the PAM standard, this is not the correct way to handle expired passwords. Instead, pam_authenticate() should return success without attempting a password change, and then pam_acct_mgmt() should return PAM_NEW_AUTHTOK_REQD, at which point the calling application is responsible for either rejecting the authentication or calling pam_chauthtok(). However, following the standard requires that all applications call pam_acct_mgmt() and check its return status; otherwise, expired accounts may be able to successfully authenticate. Many applications do not do this.
If this option is set, pam-krb5 uses the fully correct PAM mechanism for handling expired accounts instead of failing in pam_authenticate(). Due to the security risk of widespread broken applications, be very careful about enabling this option. It should normally only be turned on to solve a specific problem (such as using Solaris Kerberos libraries that don't support prompting for password changes during authentication), and then only for specific applications known to call pam_acct_mgmt() and check its return status properly.
This option is only supported when pam-krb5 is built with MIT Kerberos. If built against Heimdal, this option does nothing and normal expired password change handling still happens. (Heimdal is missing the required API to implement this option, at least as of version 1.6.)
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
This option is only applicable to the auth and password groups.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
PKCS11:/usr/lib/pkcs11/lib/soft-pkcs11.so
to specify the module to use with a smart card. It may also point to a user certificate or to other types of user IDs. See the Kerberos library documentation for more details. This option is only used if try_pkinit or use_pkinit are set.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
The primary use of this option, at least in the near future, will be to set options for the MIT Kerberos PKINIT support. For the full list of possible options, see the PKINIT plugin documentation. At the time of this writing, "X509_user_identity" is equivalent to pkinit_user and "X509_anchors" is equivalent to pkinit_anchors. "flag_DSA_PROTOCOL" can only be set via this option.
Any settings made with this option are applied after the pkinit_anchors and pkinit_user options, so if an equivalent setting is made via preauth_opt, it will probably override the other setting.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups. Note that there is no way to remove a setting made in krb5.conf using the PAM configuration, but options set in the PAM configuration are applied after options set in krb5.conf and therefore may override earlier settings.
If this option is set and pam-krb5 is built against MIT Kerberos, and PKINIT fails and the module falls back to password authentication, the user's password will not be stored in the PAM stack for subsequent modules. This is a bug in the interaction between the module and MIT Kerberos that requires some reworking of the PKINIT authentication method to fix.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
Be aware that, with MIT Kerberos, this option is implemented by using a responder without a prompter, and thus any informational messages from the Kerberos libraries or KDC during authentication will not be displayed.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
Current Kerberos password: Enter new Kerberos password: Retype new Kerberos password:
The string "Kerberos" is inserted so that users aren't confused about which password they're changing. Setting this option replaces the word "Kerberos" with whatever this option is set to. Setting this option to the empty string removes the word before "password:" entirely.
If set in the PAM configuration, <banner> may not contain whitespace. If you want a value containing whitespace, set it in krb5.conf.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the password group.
Enabling this option with ChallengeResponseAuthentication enabled in OpenSSH may cause problems for some ssh clients that only recognize "Password:" as a prompt. This option is automatically disabled if search_k5login is enabled since the principal displayed would be inaccurate.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
This option is only applicable to the auth and password groups. For the password group, it applies only to the old password. See use_authtok for a similar setting for the new password.
The major disadvantage of this option is that it means the PAM module will never see the user's password and therefore cannot save it in the PAM module data for any subsequent modules. In other words, this option cannot be used if another module is in the stack behind the Kerberos PAM module and wants to use use_first_pass. The Kerberos library also usually includes the principal in the prompt, and therefore this option implies behavior similar to expose_account. Similar to expose_account, this can cause problems with OpenSSH if ChallengeResponseAuthentication is enabled, since clients may not recognize password prompts other than "Password:".
Using this option with search_k5login would result in a password prompt for every principal listed in the user's .k5login file. This is probably not desired behavior, although it's not prohibited by the module.
This option is only applicable to the auth and password groups. For the password group, it applies only to the authentication process; the user will still be prompted for a new password.
Be cautious when using this configuration option and don't use it with OpenSSH PasswordAuthentication, only ChallengeResponseAuthentication. Some PAM-enabled applications expect PAM modules to only prompt for passwords and may even blindly give the password to the first prompt, no matter what it is. Such applications, in combination with this option, may expose the user's password in log messages and Kerberos requests.
This option is only applicable to the auth and password groups. For the password group, it applies only to the old password.
This option is only applicable to the password group.
This option is only applicable to the auth and password groups. For the password group, it applies only to the old password. See use_authtok for a similar setting for the new password.
If <pattern> ends in the literal string "XXXXXX" (six X's), that string will be replaced by randomly generated characters and the ticket cache will be created using mkstemp(3). This is strongly recommended if <pattern> points to a world-writable directory.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and session groups.
Be aware that pam_krb5 creates and stores a temporary ticket cache file owned by root during the login process. If you set ccache above to avoid using the system /tmp directory for user ticket caches, you may also want to set ccache_dir to move those temporary caches to some other location. This will allow pam_krb5 to continue working even if the system /tmp directory is full.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and session groups.
This option is only applicable to the auth group.
This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and session groups.
If try_pkinit is set and pam-krb5 is built with MIT Kerberos, the user's password is not saved in the PAM data if PKINIT fails and the module falls back to password authentication.
Be sure to list this module in the session group as well as the auth group when using it for interactive logins. Otherwise, some applications (such as OpenSSH) will not set up the user's ticket cache correctly.
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.
pam_authenticate() returns failure when called for an ignored account, requiring the system administrator to use "optional" or "sufficient" to ignore the module and move on to the next module. It's arguably more correct to return PAM_IGNORE, which causes the module to be ignored as if it weren't in the configuration, but this increases the risk of inadvertent security holes when listing pam-krb5 as the only authentication module.
This module treats the empty password as an authentication failure rather than attempting to use that password to avoid unwanted prompting behavior in the Kerberos libraries. If you have a Kerberos principal that intentionally has an empty password, it won't work with this module.
This module will not refresh an existing ticket cache if called with an effective UID or GID different than the real UID or GID, since refreshing an existing ticket cache requires trusting the KRB5CCNAME environment variable and the environment should not be trusted in a setuid context.
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, 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.
pam-krb5 was originally written by Frank Cusack. Andres Salomon made extensive modifications, and then Russ Allbery <eagle@eyrie.org> adopted it and made even more extensive modifications. Russ Allbery currently maintains the module.
Copyright 2005-2010, 2014, 2020 Russ Allbery <eagle@eyrie.org>
Copyright 2008-2014 The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
SPDX-License-Identifier: FSFAP
kadmin(8), kdestroy(1), krb5.conf(5), pam(7), passwd(1), syslog(3)
The current version of this module is available from its web page at <https://www.eyrie.org/~eagle/software/pam-krb5/>.
2021-10-17 | 4.11 |