PAM_KRB5(5)

📦
version 4.11 · 3 versions
, in epel 10, epel 9, fedora 43, fedora 44

💅 NAME 💅

okay bestie, this is the PAM_KRB5(5) manual page for pam_krb5 — the Kerberos PAM module. That's the whole name section, slay. ✨

✨ SYNOPSIS ✨

Here's the config vibe they're showing you:

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

🦋 DESCRIPTION 🦋

Okay so 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 the deets 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:

🔐 auth

  • Provides implementations of pam_authenticate() and pam_setcred().

The former takes the username from the PAM session, prompts for the user's password (unless configured to use an already-entered password), and then performs a Kerberos initial authentication, storing the obtained credentials (if successful) in a temporary ticket cache. The latter, depending on the flags it is called with, either takes the contents of the temporary ticket cache and writes it out to a persistent ticket cache owned by the user or uses the temporary ticket cache to refresh an existing user ticket cache.

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.

🌸 session

  • Provides implementations of pam_open_session(), which is equivalent to calling pam_setcred() with the PAM_ESTABLISH_CRED flag, and pam_close_session(), which destroys the ticket cache created by pam_setcred().

🎀 account

  • Provides an implementation of pam_acct_mgmt(). All it does is do the same authorization check as performed by the pam_authenticate() implementation described above.

🍓 password

  • Provides an implementation of pam_chauthtok(), which implements password changes. The user is prompted for their existing password (unless configured to use an already entered one) and the PAM module then obtains credentials for the special Kerberos principal "kadmin/changepw". It then prompts the user for a new password, twice to ensure that the user entered it properly (again, unless configured to use an already entered password), and then does a Kerberos password change.

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.

🌈 CONFIGURATION 🌈

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.

🔐 Authorization

Okay bestie, this is the part where pam_krb5 decides who's allowed in — like the bouncer at the club but with more Kerberos and fewer velvet ropes. Let's get into it 💅

  • alt_auth_map=<format> — [3.12] This one does the same kind of job as search_k5login, just with a different sauce. The <format> you hand it gets used as the authentication Kerberos principal, and every %s inside <format> gets swapped out for the username ✨
    • Tiny plot twist: if the username has an @ in it, only the part before the realm gets used to replace %s. And if <format> already contains a realm, that realm is the one that gets used. If it doesn't, the realm of the username (if there even is one) gets tacked onto the result. Also heads up — there is no quote removal. None. Zero. Nada 🙈
    • If you set this option, the default vibe is: try this alternate principal first, then fall back to the standard behavior if that flops. The main character use case is letting alternative principals do auth in programs like sudo. Most examples look like this:
alt_auth_map=%s/root
  • That one tries to authenticate as the root instance of the username first, then falls back to the regular username (but like, go read force_alt_auth and only_alt_auth before you commit to anything 👀).
  • It's also a cheap lil shortcut for trying an alternative realm first and falling back to the primary realm after. Something like:
alt_auth_map=%s@EXAMPLE.COM
  • That tries the EXAMPLE.COM realm first, then falls back on the local default realm. Way more convenient than running the module multiple times with multiple default realms set via realm — but it's very limited: only two realms can be tried, and the alternate realm is always tried first. No cap.
  • You can set this in "[appdefaults]" in krb5.conf, although honestly it usually doesn't make sense there — normally you'd use it in the PAM options of config for specific programs. It's only applicable to the auth and account groups. And check it: if you set it for the auth group, make sure you set it for the account group too, or account authorization may just fail on you 💀
  • force_alt_auth — [3.12] Pairs with alt_auth_map and forces authentication as the mapped principal, as long as that principal actually exists in the KDC. Only if the KDC comes back with principal unknown does the Kerberos PAM module fall back to normal authentication. Perfect for forcing auth with an alternate instance. If alt_auth_map isn't set, this does absolutely nothing 🫠
    • Can be set in "[appdefaults]" in krb5.conf, and it's only applicable to the auth group.
  • ignore_k5login — [2.0] Never ever look for a .k5login file in the user's home directory. Instead, just check that the Kerberos principal maps to the local account name. The default check is that the realm matches the local realm and the user portion of the principal matches the local account name — but you can customize that by setting up an aname to localname mapping in krb5.conf. Obsessed with flexibility 💖
    • Can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and account groups.
  • ignore_root — [1.1] Do literally nothing if the username is "root". The authentication and password calls will silently fail (so you can ignore that status with a control of "optional" or "sufficient"), and the account and session calls (including pam_setcred) will return PAM_IGNORE, telling the PAM library to proceed like they weren't even mentioned in the PAM configuration. This option is supported and will stay supported — but ngl, normally you want minimum_uid instead 👑
    • Can be set in "[appdefaults]" in krb5.conf.
  • minimum_uid=<uid> — [2.0] Do nothing if the authenticated account name corresponds to a local account and that local account has a UID lower than <uid>. Both conditions gotta be true, then: the authentication and password calls silently fail (again, ignorable via a control of "optional" or "sufficient"), and the account and session calls (including pam_setcred) return PAM_IGNORE, telling the PAM library to proceed like they were never in the PAM config 🌸
    • Using this is highly recommended if you don't need Kerberos to authenticate password logins to the root account — which isn't recommended anyway, since Kerberos requires a network connection. It gives you some defense in depth against user principals that happen to match a system account incorrectly authenticating as that system account. That's a whole mess you do not want 😭
    • Can be set in "[appdefaults]" in krb5.conf.
  • only_alt_auth — [3.12] Works with alt_auth_map and forces the use of the mapped principal for authentication. It disables fallback to normal authentication in all cases and overrides search_k5login and force_alt_auth. If alt_auth_map isn't set, it has no effect and the standard auth behavior is used. It's giving "all or nothing" energy 💅
    • Can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
  • search_k5login — [2.0] Normally, the Kerberos implementation of pam_authenticate tries to obtain tickets for the authenticating username in the local realm. But if this option is set and the local user has a .k5login file in their home directory, the module instead opens and reads that .k5login file, trying to use the supplied password to authenticate as each principal listed there, one at a time, in turn 🔥
    • If any of those authentications succeed, the user is successfully authenticated. Otherwise, authentication fails. No in-between, bestie.
    • This is useful for allowing password authentication (via console or sshd without GSS-API support) to shared accounts. If there's no .k5login file, behavior is the same as normal. And yes — using this requires that the user's .k5login file be readable at the time of authentication 🔑
    • Can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

🧚 Kerberos Behavior

Now we're getting into the actual Kerberos mechanics — the FAST tunnels, the keytabs, the forwardable tickets. Buckle up buttercup ⭐

  • anon_fast — [4.6] Attempts to use Flexible Authentication Secure Tunneling (FAST) by first authenticating as the anonymous user (WELLKNOWN/ANONYMOUS) and using its credentials as the FAST armor. This requires that anonymous PKINIT be enabled for the local realm, that PKINIT be configured on the local system, and that the Kerberos library support FAST and anonymous PKINIT. Three things, all required, no shortcuts 🌈
    • So what even is FAST? It's a mechanism to protect Kerberos against password guessing attacks and to provide other security improvements. To work, FAST needs a ticket obtained with a strong key to protect exchanges with potentially weaker user passwords. This option uses anonymous authentication to get that key and then uses it to protect the subsequent authentication. Iconic layered defense ✨
    • If anonymous PKINIT isn't available or fails, FAST just won't be used and authentication proceeds as normal. No drama.
    • Wanna use an existing ticket cache for the FAST credentials instead? Use fast_ccache instead of this option. And if both fast_ccache and anon_fast are set, the ticket cache named by fast_ccache gets tried first, and the Kerberos PAM module falls back on attempting anonymous PKINIT if that cache couldn't be used. Teamwork 💖
    • Can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
    • The operation is the same as using the fast_ccache option, except the cache is created and destroyed automatically. And if both fast_ccache and anon_fast are used, fast_ccache takes precedent and no anonymous authentication is done. Periodt.
  • fast_ccache=<ccache_name> — [4.3] Same as anon_fast, but grabs an existing Kerberos ticket cache instead of doing anonymous PKINIT. This lets you use FAST with a realm that doesn't support PKINIT or doesn't support anonymous authentication 🙌
    • <ccache_name> should be a credential cache containing a ticket obtained using a strong key — like the randomized key for the host principal of the local system. If <ccache_name> names a ticket cache that's readable by the authenticating process and has tickets, then FAST will be attempted 🎀
    • Easiest way to do this: 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 won't be able to protect authentications done as non-root users (screensavers, looking at you 👀).
    • If there are no credentials in the ticket cache, or the ticket cache doesn't exist or isn't readable, FAST won't be used and authentication proceeds as normal. But — if the credentials in that ticket cache are expired, authentication will fail if the KDC supports FAST. Yeah. Careful with that one 💀
    • Wanna use anonymous PKINIT to protect the FAST exchange instead? That's the anon_fast option. anon_fast is easier to configure since no existing ticket cache is required, but it requires PKINIT to be available and configured and requires that the local realm support anonymous authentication. If both fast_ccache and anon_fast are set, the ticket cache named by fast_ccache is tried first, and the Kerberos PAM module falls back on attempting anonymous PKINIT if that cache couldn't be used 🦋
    • Can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.
  • forwardable — [1.0] Obtain forwardable tickets. If set (to either true or false, although it can only be set to false in krb5.conf), this overrides the Kerberos library default set in the [libdefaults] section of krb5.conf. Simple, clean, forwardable 💫
    • Can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
  • keytab=<path> — [3.0] Specifies the keytab to use when validating the user's credentials. The default is the default system keytab (normally /etc/krb5.keytab), which is usually only readable by root 🔐
    • Applications not running as root that use this PAM module for authentication may want to point it at another keytab the application can actually read. The first principal found in the keytab will be used as the principal for credential verification. First come, first served, iykyk.
    • Can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.
  • realm=<realm> — [2.2] okay so this one sets the default Kerberos realm and grabs credentials in that realm instead of the normal default realm for your system. If you use it, set it for all groups being used for consistent results — fr fr. This setting will affect authorization decisions since it changes the default realm. It will also change the service principal used to verify the obtained credentials to be in the specified realm. 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. 💅
  • renew_lifetime=<lifetime> — [2.0] Obtain renewable tickets with a maximum renewable lifetime of <lifetime>. <lifetime> should be a Kerberos lifetime string such as "2d4h10m" or a time in minutes. If set, this overrides the Kerberos library default set in the [libdefaults] section of krb5.conf. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group. ✨
  • ticket_lifetime=<lifetime> — [3.0] Obtain tickets with a maximum lifetime of <lifetime>. <lifetime> should be a Kerberos lifetime string such as "2d4h10m" or a time in minutes. If set, this overrides the Kerberos library default set in the [libdefaults] section of krb5.conf. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group. 🎀
  • user_realm — [4.6] Obtain credentials in the specified realm rather than in the default realm for this system. If this option is used, it should be set for all groups being used for consistent results (although the account group currently doesn't care about realm). This will not change authorization decisions. If the obtained credentials are supposed to allow access to a shell account, the user will need an appropriate .k5login file entry or the system will have to have a custom aname_to_localname mapping. 🦋

🌸 PAM Behavior 🌸

  • clear_on_fail — [3.9] When changing passwords, PAM first does a preliminary check through the complete password stack, and then calls each module again to do the password change. After that preliminary check, the order of module invocation is fixed. This means that even if the Kerberos password change fails (or if one of the other password changes in the stack fails), other password PAM modules in the stack will still be called even if the failing module is marked required or requisite. When using multiple password PAM modules to synchronize passwords between multiple systems when they change, this behavior can cause unwanted differences between the environments.

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.

  • debug — [1.0] Log more verbose trace and debugging information to syslog at LOG_DEBUG priority, including entry and exit from each of the external PAM interfaces (except pam_close_session). This option can be set in "[appdefaults]" in krb5.conf. 🔍
  • defer_pwchange — [3.11] By default, pam-krb5 lets the Kerberos library handle prompting for a password change if an account's password is expired during the auth group. If this fails, pam_authenticate() returns an error.

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.

  • fail_pwchange — [4.2] By default, pam-krb5 lets the Kerberos library handle prompting for a password change if an account's password is expired during the auth group. If this option is set, expired passwords are instead treated as an authentication failure identical to an incorrect password. Also see defer_pwchange and force_pwchange. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group. 🙈
  • force_pwchange — [3.11] If this option is set and authentication fails with a Kerberos error indicating the user's password is expired, attempt to immediately change their password during the authenticate step. Under normal circumstances, this is unnecessary. Most Kerberos libraries will do this for you, and setting this option will prompt the user twice to change their password if the first attempt (done by the Kerberos library) fails. However, some system Kerberos libraries (such as Solaris's) have password change prompting disabled in the Kerberos library; on those systems, you can set this option to simulate the normal library behavior. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group. ⚡
  • no_update_user — [4.7] Normally, if pam-krb5 is able to canonicalize the principal to a local name using krb5_aname_to_localname() or similar calls, it changes the PAM_USER variable for this PAM session to the canonicalized local name. Setting this option disables this behavior and leaves PAM_USER set to the initial authentication identity. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group. 🫶
  • silent — [1.0] Don't show messages and errors from Kerberos, such as warnings of expiring passwords, to the user via the prompter. This is equivalent to the behavior when the application passes in PAM_SILENT, but can be set in the PAM configuration. This option is only applicable to the auth and password groups. 🤫
  • trace=<log-file> — [4.6] Enables Kerberos library trace logging to the specified log file if it is supported by the Kerberos library. This is intended for temporary debugging.
The specified file will be appended to without further security checks, so do not specify a file in a publicly writable directory like /tmp. 🚨

🦋 PKINIT 🦋

  • pkinit_anchors=<anchors> — [3.0] When doing PKINIT authentication, use <anchors> as the client trust anchors. This is normally a reference to a file containing the trusted certificate authorities. 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. 🔐
  • pkinit_prompt — [3.0] Before attempting PKINIT authentication, prompt the user to insert a smart card. You may want to set this option for programs such as gnome-screensaver that call PAM as soon as the mouse is touched and don't give the user an opportunity to enter the smart card first. Any information entered at the first prompt is ignored. If try_pkinit is set, a user who wishes to use a password instead can just press Enter and then enter their password as normal. 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. 💳
  • pkinit_user=<userid> — [3.0] When doing PKINIT authentication, use <userid> as the user ID. The value of this string is highly dependent on the type of PKINIT implementation you're using, but will generally be something like:
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. 🪪

  • preauth_opt=<option> — [3.3] Sets a preauth option (currently only applicable when built with MIT Kerberos). <option> is either a key/value pair with the key separated from the value by "=" or a boolean option (in which case it's turned on). In krb5.conf, multiple options should be separated by whitespace. In the PAM configuration, this option can be given multiple times to set multiple options. In either case, <option> may not contain whitespace. 🧚

Settings here get applied after pkinit_anchors and pkinit_user, so if you set basically the same thing through preauth_opt, it'll probably override the other one. Order matters, bestie. 💅

You can set this one in [appdefaults] inside krb5.conf, and it only does anything for the auth and password groups. Heads up though: there's no way to remove a setting made in krb5.conf using the PAM configuration 😭 — but PAM config options get applied after krb5.conf ones, so you can override earlier settings from there. Sneaky but legal.

  • try_pkinit — [3.0] Try PKINIT authentication before falling back to a regular password. You'll probably also need to set the pkinit_user configuration option. If PKINIT fails, the PAM module goes back to regular password auth, no drama.

This one's only supported if pam-krb5 was built against Heimdal 0.8rc1 or later, or MIT Kerberos 1.6.3 or later. Check your build, diva.

⚠️ Real bug alert: 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. It's a bug in the interaction between the module and MIT Kerberos, and fixing it requires some reworking of the PKINIT authentication method. Not us, not our fault, but definitely our problem. 💀

Settable in [appdefaults] in krb5.conf, and only applicable to the auth and password groups.

  • use_pkinit — [3.0, 4.9 for MIT Kerberos] PKINIT is mandatory now, no backup plan. You'll probably also need to set the pkinit_user configuration option. If PKINIT fails, authentication fails. Periodt. Only supported if pam-krb5 was built against Heimdal 0.8rc1 or later or MIT Kerberos 1.12 or later.
Be aware that, with MIT Kerberos, this option is implemented by using a responder without a prompter — so any informational messages from the Kerberos libraries or KDC during authentication will not be displayed. 🙈 You just won't see them. At all.

Settable in [appdefaults] in krb5.conf, only applicable to the auth and password groups.

🌸 Prompting 🌸

  • banner=<banner> — [3.0] By default, the prompts when a user changes their password are literally:
Current Kerberos password:
Enter new Kerberos password:
Retype new Kerberos password:

The string Kerberos gets inserted so nobody gets confused about which password they're changing — iconic UX, honestly. Setting this option replaces the word Kerberos with whatever you set it to. Set it to the empty string and the word before password: disappears entirely. ✨

If set in the PAM configuration, <banner> may not contain whitespace. If you want a value containing whitespace, set it in krb5.conf instead. The PAM config simply cannot handle the spaces, bestie.

Settable in [appdefaults] in krb5.conf, and only applicable to the password group.

  • expose_account — [3.0] By default, the Kerberos PAM module password prompt is simply Password:. That's deliberate — it avoids leaking any information about the system realm or account-to-principal conversions. If this option is set, the string for <principal> is added before the colon, where <principal> is the user's principal. That string also shows up before the colon on prompts when changing the user's password. 🌈
Turning this on with ChallengeResponseAuthentication enabled in OpenSSH may cause problems for some ssh clients that only recognize Password: as a prompt. They see the extra text and just short-circuit. 😭

This option is automatically disabled if search_k5login is enabled, since the principal displayed would be inaccurate. Can't be out here lying in a prompt.

Settable in [appdefaults] in krb5.conf, and only applicable to the auth and password groups.

  • force_first_pass — [4.0] Use the password obtained by a previous authentication or password module to authenticate the user, without prompting them again. If no previous module obtained the user's password — fail. No prompting, no mercy. Also see try_first_pass and use_first_pass for weaker versions of this option (this one is the strict older sister 👑).

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.

  • no_prompt — [4.6] Never prompt for the current password. Instead, pass in a NULL password to the Kerberos library and let the Kerberos library do the prompting. This may be needed if, for example, the Kerberos library is configured to use other authentication mechanisms than passwords and needs full control over the prompting process. Hand over the mic, basically. 🎤
The major disadvantage: 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. Nope. Not happening. 💀

The Kerberos library also usually includes the principal in the prompt, so this option implies behavior similar to expose_account. And 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. Probably not the vibe you're going for, although it's not prohibited by the module. 🙈

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.

  • prompt_principal — [3.6] Before prompting for the user's password (or using the previously entered password, if try_first_pass, use_first_pass, or force_first_pass are set), prompt the user for the Kerberos principal to use for authentication. This lets the user authenticate with a different principal than the one corresponding to the local username — provided that either a .k5login file or local Kerberos principal-to-account mapping authorizes that principal to access the local account. Slay, but with authorization. 🔥
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. Very much not the look. 😭
  • try_first_pass — [1.0] If the authentication module isn't the first on the stack, and a previous module obtained the user's password, use that password to authenticate the user without prompting them again. If that authentication fails, fall back on prompting the user for their password. This option has no effect if the authentication module is first in the stack, or if no previous module obtained the user's password. Also see use_first_pass and force_first_pass for stronger versions of this option.

Only applicable to the auth and password groups. For the password group, it applies only to the old password.

  • use_authtok — [4.0] Use the new password obtained by a previous password module when changing passwords, rather than prompting for the new password. If the new password isn't available — fail. This can be used to require passwords be checked by another, prior module, such as pam_cracklib. Teamwork, bestie. 🫶

Only applicable to the password group.

  • use_first_pass — [1.0] Use the password obtained by a previous authentication module to authenticate the user without prompting the user again. If no previous module obtained the user's password for either an authentication or password change, fall back on prompting the user. If a previous module did obtain the user's password but authentication with that password fails — fail, without further prompting the user. Commit to the bit. 💅 Also see try_first_pass and force_first_pass for other versions of this option.

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.

🎟️ Ticket Caches 🎟️

  • ccache=<pattern> — [2.0] Use <pattern> as the pattern for creating credential cache names. <pattern> must be in the form <type>:<residual>, where <type> and the following colon are optional if a file cache should be used. The special token %u, anywhere in <pattern>, is replaced with the user's numeric UID. The special token %p, anywhere in <pattern>, is replaced with the current process ID. 🎀
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. Like, genuinely, please do this. 🔥

Settable in [appdefaults] in krb5.conf, and only applicable to the auth and session groups.

  • ccache_dir=<directory> — [1.2] Store both the temporary ticket cache used during authentication and user ticket caches in <directory> instead of in /tmp. The algorithm for generating the ticket cache name is otherwise unchanged. <directory> may be prefixed with FILE: to make the cache type unambiguous (and this may be required on systems that use a cache type other than file as the default). 🦋
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. Main character energy: keeps functioning while everything else is falling apart. 👑

Settable in [appdefaults] in krb5.conf, and only applicable to the auth and session groups.

  • no_ccache — [1.0] ok so this one says: do not make a ticket cache after authenticating. Ngl you shouldn't set this in general 🙈, but it's lowkey useful when it's part of the PAM config for a specific service that uses PAM for auth but never creates user sessions, and therefore doesn't want the overhead of ever writing the user's credentials to disk. When you use this option, the app should only call pam_authenticate() — other functions like pam_setcred(), pam_start_session(), and pam_acct_mgmt() genuinely don't make sense with it. So like, don't use this option if the application needs PAM account and session management calls, bestie. 💀

This option is only applicable to the auth group.

  • retain_after_close — [2.3] normally the user's ticket cache gets destroyed when either pam_end() or pam_close_session() is called by the authenticating application, so that ticket caches aren't just left behind after the user logs out. But sometimes that's not the vibe you want. (On Solaris 8, for instance, the default behavior means login will destroy the ticket cache before running the user's shell. 😭) If this option is set, the PAM module will never destroy the user's ticket cache. Fair warning tho: if you set this, you may want to call kdestroy in the shell's logout configuration or run a temporary file removal program, otherwise you'll be accumulating hundreds of ticket caches in /tmp. 🫠

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and session groups.

🌸 ENVIRONMENT 🌸

  • KRB5CCNAME — set by pam_setcred() with the PAM_ESTABLISH_CRED option, and therefore also by pam_open_session(), so it points to the new credential cache for the user. Peep the ccache and ccache_dir options for how that name gets built. By default the cache name will be prefixed with "FILE:" so the cache type is unambiguous. 💅
  • PAM_KRB5CCNAME — set by pam_authenticate() to point to the temporary ticket cache used for authentication (unless the no_ccache option was given, obviously). Then pam_setcred() uses that environment variable to locate the temporary cache even if it wasn't called in the same PAM session as pam_authenticate() (which is, like, an actual problem with sshd running in some modes ✨). Heads up: this environment variable is only used internal to the PAM module. 🔒

🎀 FILES 🎀

  • /tmp/krb5cc_UID_RANDOM — the default credential cache name. UID is the decimal UID of the local user and RANDOM is a random six-character string. You can change the pattern with the ccache option and the directory with the ccache_dir option. 🗂️
  • /tmp/krb5cc_pam_RANDOM — the credential cache name used for the temporary credential cache created by pam_authenticate(). This cache gets removed again when the PAM session is ended or when pam_setcred() is called, and will normally not be user-visible. RANDOM is a random six-character string. 🧚
  • ~/.k5login — file containing Kerberos principals that are allowed access to that account. 👑

💀 BUGS 💀

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. That's just how it is rn. 😭

🔥 CAVEATS 🔥

ok bestie, this whole section is the "read before you ship it" section, pls actually read it 🙏

Be sure to list this module in the session group as well as the auth group when you're using it for interactive logins. Otherwise some applications (such as OpenSSH) will not set up the user's ticket cache correctly. No cap.

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 that 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, which requires 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 that increases the risk of inadvertent security holes when listing pam-krb5 as the only authentication module. So like, tradeoffs. ⚖️

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. So if you have a Kerberos principal that intentionally has an empty password, it won't work with this module. periodt. 💅

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. 🦋

👑 AUTHOR 👑

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. iconic lineage honestly ✨

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

⭐ SEE ALSO ⭐

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/. 🔗

and that's the whole page, bestie!! 🎀 this lil beauty is version 4.11, dated 2021-10-17, and it's the PAM_KRB5(5) manual page — go forth and authenticate responsibly 💖✨

📦 where this page comes from