pam_krb5(8)

📦
version 2.4.13 · 3 versions
, in opensuse-leap 16.0

💖 pam_krb5(8) — System Administrator's Manual, bestie edition 💖

✨ NAME ✨

  • pam_krb5 — Kerberos 5 authentication 💅

🌸 SYNOPSIS 🌸

PAM config lines, copy-paste energy:

auth required /usr/$LIB/security/pam_krb5.so
session optional /usr/$LIB/security/pam_krb5.so
account sufficient /usr/$LIB/security/pam_krb5.so
password sufficient /usr/$LIB/security/pam_krb5.so

🦋 DESCRIPTION 🦋

Okay so pam_krb5.so is the PAM module that makes Kerberos 5 password-checking slide into applications that use PAM like it was always invited. No cap, it creates session-specific credential caches. If the system is an AFS client, it will also attempt to obtain tokens for the local cell, the cell which contains the user's home directory, and any explicitly-configured cells. AFS girlies, this one's for you.

When a user logs in, the module's authentication function performs a simple password check and, if possible, obtains Kerberos 5 credentials, caching them for later use. When the application requests initialization of credentials (or opens a session), the usual ticket files are created. When the application subsequently requests deletion of credentials or closing of the session, the module deletes the ticket files. When the application requests account management: if the module did not participate in authenticating the user, it will signal libpam to ignore the module. If the module did participate in authenticating the user, it will check for an expired user password and verify the user's authorization using the .k5login file of the user being authenticated — and that file is expected to be accessible to the module. Read that again: accessible to the module.

🎀 ARGUMENTS 🎀

  • debug — turns on debugging via syslog(3). Debugging messages are logged with priority LOG_DEBUG.
  • debug_sensitive — turns on debugging of sensitive information via syslog(3). Debug messages are logged with priority LOG_DEBUG. Sensitive info, bestie — be normal about it.
  • afs_cells=cell.example.com[,...] — tells pam_krb5.so to obtain tokens for the named cells, in addition to the local cell, for the user. The module will guess the principal name of the AFS service for the named cells, or it can be specified by giving cell in the form cellname=principalname.
  • always_allow_localname — tells pam_krb5.so, when performing an authorization check using the target user's .k5login file, to always allow access when the principal name being authenticated maps to the local user's name (as configured using the auth_to_local_names and auth_to_local settings in krb5.conf(5), if your implementation provides those settings). Otherwise, if the file exists and can be read, but the principal is not explicitly listed, access is typically denied. This setting is disabled by default.
  • armor = true|false|service [...] — attempt to use armoring when communicating with the KDC. This option is currently mainly only useful for testing, as the keytab method should not be expected to work when the module is called from an unprivileged process, and the pkinit method requires that the KDC is properly configured to offer anonymous PKINIT, and that the client is also properly configured to trust the KDC's CA. The default is false.
  • armor_strategy = keytab,pkinit — controls how the module will attempt to obtain tickets for use as armor. The value should be a comma-separated list of methods. Supported methods include ketyab and pkinit — the page really says ketyab, bestie, we keep it exact 💀. The default is keytab,pkinit.
  • banner=Kerberos 5 — tells pam_krb5.so how to identify itself when users attempt to change their passwords. The default setting is "Kerberos 5".
  • ccache_dir=/tmp — tells pam_krb5.so which directory to use for storing credential caches. The default setting is /tmp.
  • ccname_template=DIR:/run/user/%U/krb5cc_XXXXXX — specifies the location in which to place the user's session-specific credential cache. This value is treated as a template, and these sequences are substituted:
    • %u — login name
    • %U — login UID
    • %p — principal name
    • %r — principal's realm name
    • %h — home directory
    • %d — the default ccache directory (as set with ccache_dir)
    • %P — the current process ID
    • %% — literal %

If the resulting template does not end with XXXXXX, a suffix will be added to the configured value. If not set, the module attempts to read the default used by libkrb5 from krb5.conf(5), and if one is not found, the default is DIR:/run/user/%U/krb5cc_XXXXXX" (yes, with the stray quote the page has — keeping it exact 🙈).

  • chpw_prompt — tells pam_krb5.so to allow expired passwords to be changed during authentication attempts. While this is the traditional behavior exhibited by kinit, it is inconsistent with the behavior expected by PAM, which expects authentication to (appear to) succeed, only to have password expiration be flagged by a subsequent call to the account management function. Some applications which don't handle password expiration correctly will fail unconditionally if the user's password is expired, and this flag can be used to attempt to work around this bug in those applications. The default is false.
  • cred_session — specifies that pam_krb5 should create and destroy credential caches, as it does when the calling application opens and closes a PAM session, when the calling application establishes and deletes PAM credentials. This is done to compensate for applications which expect to create a credential cache but which don't use PAM session management. It is usually a harmless redundancy in applications which don't require it, so this option is enabled by default except for these services: "sshd".
  • external, external=sshd — the external=sshd form tells pam_krb5.so to use Kerberos credentials provided by the calling application during session setup. This is most often useful for obtaining AFS tokens. (The page lists plain external on its own too.)
  • ignore_afs=true|false|service [...] — tells pam_krb5.so to completely ignore the presence of AFS, preventing any attempts to obtain new tokens on behalf of the calling application.
  • ignore_k5login — specifies that pam_krb5 should skip checking the user's .k5login file to verify that the principal name of the client being authenticated is authorized to access the user account. (Actually, the check is performed by a function offered by the Kerberos library, which controls which files it will consult.) The default is to perform the check.
  • ignore_unknown_principals, ignore_unknown_spn, ignore_unknown_upn — specify that pam_krb5 should return a PAM_IGNORE code to libpam instead of PAM_USER_UNKNOWN for users for whom the determined principal name is expired or does not exist. (The page's exact wording has “not pam_krb5 should return”; that reads like a typo, but the codes and behavior are what matter here. 😭)
  • keytab=FILE:/etc/krb5.keytab — tells pam_krb5.so the location of a keytab to use when validating credentials obtained from KDCs.
  • minimum_uid=0 — tells pam_krb5.so to ignore authentication attempts by users with UIDs below the specified number.
  • multiple_ccaches — specifies that pam_krb5 should maintain multiple credential caches for this service, because it both sets credentials and opens a PAM session, but it sets the KRB5CCNAME variable after doing only one of the two. This option is usually not necessary for most services.
  • no_initial_prompt — tells pam_krb5.so to not ask for a password before attempting authentication, and to instead allow the Kerberos library to trigger a request for a password only in cases where one is needed.
  • no_subsequent_prompt — tells pam_krb5.so to only provide the previously-entered password in response to any request for a password which the Kerberos library might make. If the calling application does not properly support PAM conversations (possibly due to limitations of a network protocol which it is serving), this may need to be used to prevent the application from supplying the user's current password in password-changing situations when a new password is called for.
  • no_user_check — tells pam_krb5.so to not check if a user exists on the local system, to skip authorization checks using the user's .k5login file, and to create ccaches owned by the current process's UID. This is useful for situations where a non-privileged server process needs to use Kerberized services on behalf of remote users who may not have local access. Note that such a server should have an encrypted connection with its client in order to avoid allowing the user's password to be eavesdropped. Encrypted connection. Please. 🙏
  • no_validate, no_validate=vlock — tells pam_krb5.so to not attempt to use the local keytab to verify that the TGT obtained from the realm's servers has not been spoofed. The libdefaults verify_ap_req_nofail setting can affect whether or not errors reading the keytab which are encountered during validation will be suppressed.
  • null_afs — tells pam_krb5.so, when it attempts to set tokens, to try to get credentials for services with names which resemble afs@REALM before attempting to get credentials for services with names resembling afs/cell@REALM. The default is to assume that the cell's name is the instance in the AFS service's Kerberos principal name.
  • preauth_options=[] — controls the preauthentication options which pam_krb5 passes to libkrb5, if the system-defaults need to be overridden. The list is treated as a template, and these sequences are substituted:
    • %u — login name
    • %U — login UID
    • %p — principal name
    • %r — principal's realm name
    • %h — home directory
    • %d — the default ccache directory
    • %P — the current process ID
    • %% — literal %

A list of recognized values should be listed in the kinit(1) manual page as parameters for its -X option.

  • pwhelp=filename — specifies the name of a text file whose contents will be displayed to clients who attempt to change their passwords. There is no default.
  • realm=realm — overrides the default realm set in /etc/krb5.conf, which pam_krb5.so will attempt to authenticate users to.
  • tokens — the page lists this one with no separate description in this section. 🫶

...and the option parade keeps going, bestie, we're so close 🎀

  • tokens=imap — this one tells pam_krb5.so that it should make a brand-new AFS PAG and grab AFS tokens during authentication, on top of the normal session setup. It's mostly for server apps that need to peek at a user's files but don't bother opening PAM sessions first. Important tea: a properly-written server won't need this flag at all to work right, so don't go slapping it on everything, okay? 💅
  • trace — turns on libkrb5's library tracing, bestie. All those trace messages get logged to syslog(3) with priority LOG_DEBUG. It's giving detective mode 🔍✨
  • try_first_pass — this tells pam_krb5.so to check the password that was already entered, just like with use_first_pass, BUT if that one flops it goes ahead and prompts the user for another one. And plot twist: this is the default mode of operation 👑 so if you do nothing, this is what you get.
  • use_first_pass — tells pam_krb5.so to just take the user's already-entered password as it was stored by a module earlier in the stack — usually pam_unix or pam_pwdb — instead of bugging the user with a prompt. No extra typing, we love efficiency 🫶
  • use_authtok — tells pam_krb5.so to never prompt for new passwords when changing passwords. Super useful if you've got pam_cracklib or pam_passwdqc in the mix trying to force people into less-easy-to-guess passwords. Let the password police do their job 🚨
  • use_shmem
  • use_shmem=sshd — these two tell pam_krb5.so to pass credentials from the authentication service function over to the session management service function using shared memory — or, with the =sshd flavour, to do that specifically for certain services. Sharing is caring (but like, securely) 💌
  • validate_user_user
  • validate_user_user=gnome-screensaver — this specifies that when the module tries to validate the TGT, it should attempt user-to-user authentication using a previously-obtained TGT in the default ccache, if validation can't be done with a keytab. Backup plan energy, honestly iconic 🌈

📁 FILES 📁

  • /etc/krb5.conf

👀 SEE ALSO 👀

Go read those too, iykyk 📚

💀 BUGS 💀

Probably, but let's hope not 😭 If you do find any, please file them in the bug database at http://bugzilla.redhat.com/ against the pam_krb5 component. Do it for the girls (the girls being everyone using this module) 🫶

👑 AUTHOR 👑

Nalin Dahyabhai <nalin@redhat.com> — literally the main character of this manpage, we stan 🌟

okay that's the whole thing, bestie, you made it to the end 🎉 this little masterpiece is from openSUSE, dated 2013/09/21, and it lives at pam_krb5(8). Go forth and authenticate slayfully 💅✨🦋

📦 where this page comes from