pam_krb5 - Man Page

[3.12] This functions similarly to the search_k5login option.  The <format> argument is used as the authentication Kerberos principal, with any %s in <format> replaced with the username.  If the username contains an @, only the part of the username before the realm is used to replace %s.  If <format> contains a realm, it will be used; otherwise, the realm of the username (if any) will be appended to the result.  There is no quote removal.

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.

[3.12] This option is used with alt_auth_map and forces authentication as the mapped principal if that principal exists in the KDC.  Only if the KDC returns principal unknown does the Kerberos PAM module fall back to normal authentication.  This can be used to force authentication with an alternate instance.  If alt_auth_map is not set, it has no effect.

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

[2.0] Never look for a .k5login file in the user's home directory. Instead, only check that the Kerberos principal maps to the local account name.  The default check is to ensure the realm matches the local realm and the user portion of the principal matches the local account name, but this can be customized by setting up an aname to localname mapping in krb5.conf.

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

[1.1] Do not do anything if the username is root.  The authentication and password calls will silently fail (allowing that status to be ignored via 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 as if they weren't mentioned in the PAM configuration.  This option is supported and will remain, but normally you want to use minimum_uid instead.

This option can be set in [appdefaults] in krb5.conf.

[2.0] Do not do anything if the authenticated account name corresponds to a local account and that local account has a UID lower than <uid>.  If both of those conditions are true, the authentication and password calls will silently fail (allowing that status to be ignored via 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 as if they weren't mentioned in the PAM configuration.

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.

[3.12] This option is used 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 is not set, it has no effect and the standard authentication behavior is used.

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

[2.0] Normally, the Kerberos implementation of pam_authenticate attempts to obtain tickets for the authenticating username in the local realm.  If this option is set and the local user has a .k5login file in their home directory, the module will instead open and read that .k5login file, attempting to use the supplied password to authenticate as each principal listed there in turn.  If any of those authentications succeed, the user will be successfully authenticated; otherwise, authentication will fail. This option is useful for allowing password authentication (via console or sshd without GSS-API support) to shared accounts.  If there is no .k5login file, the behavior is the same as normal.  Using this option requires that the user's .k5login file be readable at the time of authentication.

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

[4.6] Attempt 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 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.

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.

[4.3] The same as anon_fast, but use an existing Kerberos ticket cache rather than anonymous Pkinit.  This allows use of 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, 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.

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

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

[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 wish to point it to another keytab the application can read.  The first principal found in the keytab will be used as the principal for credential verification.

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

[2.2] Set the default Kerberos realm and obtain credentials in that realm, rather than in the normal default realm for this system.  If this option is used, it should be set for all groups being used for consistent results.  This setting will affect authorization decisions since it changes the default realm.  This setting 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

[3.0] Attempt PKINIT authentication before trying a regular password.  You will probably also need to set the pkinit_user configuration option. If PKINIT fails, the PAM module will fall back on regular password authentication.  This option is currently only supported if pam-krb5 was built against Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later.

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.

[3.0, 4.9 for MIT Kerberos] Require PKINIT authentication.  You will probably also need to set the pkinit_user configuration option.  If PKINIT fails, authentication will fail.  This option is 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, 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.

[3.0] By default, the prompts when a user changes their password are:

    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.

[3.0] By default, the Kerberos PAM module password prompt is simply “Password:”.  This 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.  This string is also added before the colon on prompts when changing the user's password.

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.

[4.0] Use the password obtained by a previous authentication or password module to authenticate the user without prompting the user again.  If no previous module obtained the user's password, fail without prompting the user.  Also see try_first_pass and use_first_pass for weaker versions of this option.

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.

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

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.

[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 allows the user to 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 authorize that principal to access the local account.

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.

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

This option is only applicable to the auth and password groups.  For the password group, it applies only to the old password.

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

This option is only applicable to the password group.

[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.  Also see try_first_pass and force_first_pass for other versions of this option.

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.

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

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

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

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

[1.0] Do not create a ticket cache after authentication.  This option shouldn't be set in general, but is useful as part of the PAM configuration for a particular service that uses PAM for authentication but isn't creating user sessions and doesn't want the overhead of ever writing the user credentials to disk.  When using this option, the application should only call pam_authenticate(); other functions like pam_setcred(), pam_start_session(), and pam_acct_mgmt() don't make sense with this option.  Don't use this option if the application needs PAM account and session management calls.

This option is only applicable to the auth group.

[2.3] Normally, the user's ticket cache is destroyed when either pam_end() or pam_close_session() is called by the authenticating application so that ticket caches aren't left behind after the user logs out.  In some cases, however, this isn't desirable.  (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.  If you set this, you may want to call kdestroy in the shell's logout configuration or run a temporary file removal program to avoid 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.