NAME¶
pam_krb5 - Kerberos PAM module
SYNOPSIS¶
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¶
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:
- 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.
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. 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 if
this feature is used.
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.
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.
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, and 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. It supports many of the same options, has some additional
options, and doesn't support some of the options the Sourceforge module does.
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.
Authorization¶
- alt_auth_map=<format>
- 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 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.
- force_alt_auth
- 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 krb5.conf and is only applicable to the
auth group.
- ignore_k5login
- 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 krb5.conf and is only applicable to the
auth and account groups.
- ignore_root
- 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 krb5.conf.
- minimum_uid=<uid>
- 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 krb5.conf.
- only_alt_auth
- 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 krb5.conf and is only applicable to the
auth group.
- search_k5login
- 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 krb5.conf and is only applicable to the
auth group.
Kerberos Behavior¶
- anon_fast
- 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 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.
- fast_ccache=<ccache_name>
- 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 krb5.conf and is only applicable to the
auth and password groups.
- forwardable
- 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 krb5.conf and is only applicable to the
auth group.
- keytab=<path>
- 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 krb5.conf and is only applicable to the
auth group.
- realm=<realm>
- 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.
- renew_lifetime=<lifetime>
- 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 krb5.conf and is only applicable to the
auth group.
- ticket_lifetime=<lifetime>
- 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 krb5.conf and is only applicable to the
auth group.
- user_realm
- 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
- 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 krb5.conf and is only applicable to the
password group.
- debug
- 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 krb5.conf.
- defer_pwchange
- 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 can be set in krb5.conf and is only applicable to the
auth group.
- fail_pwchange
- 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 krb5.conf and is only applicable to the
auth group.
- force_pwchange
- 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 krb5.conf and is only applicable to the
auth group.
- silent
- 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>
- 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>
- 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 krb5.conf and is only applicable to the
auth and password groups.
- pkinit_prompt
- 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 krb5.conf and is only applicable to the
auth and password groups.
- pkinit_user=<userid>
- 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 krb5.conf and is only applicable to the
auth and password groups.
- preauth_opt=<option>
- 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 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.
- try_pkinit
- 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 rearchitecting of the PKINIT authentication method to fix.
This option can be set in krb5.conf and is only applicable to the
auth and password groups.
- use_pkinit
- Require PKINIT authentication. You will probably also need to set the
pkinit_user configuration option. If PKINIT fails, authentication
will fail. This option is currently only supported if pam-krb5 was built
against Heimdal 0.8rc1 or later. MIT Kerberos doesn't provide a method to
enforce use of PKINIT, so try_pkinit must be used with that
implementation instead.
This option can be set in krb5.conf and is only applicable to the
auth and password groups.
Prompting¶
- banner=<banner>
- 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 krb5.conf and is only applicable to the
password group.
- expose_account
- 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 krb5.conf and is only applicable to the
auth and password groups.
- force_first_pass
- 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.
- no_prompt
- 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.
- prompt_principal
- 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.
- try_first_pass
- 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.
- use_authtok
- 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.
- use_first_pass
- 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.
Ticket Caches¶
- ccache=<pattern>
- 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 krb5.conf and is only applicable to the
auth and session groups.
- ccache_dir=<directory>
- 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 krb5.conf and is only applicable to the
auth and session groups.
- no_ccache
- 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.
- retain_after_close
- 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 desireable. (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 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(), to point to the new
credential cache for the user. See the ccache and ccache_dir
options. By default, the cache name will be prefixed with
"FILE:" to make the cache type unambiguous.
- PAM_KRB5CCNAME
- Set by pam_authenticate() to point to the temporary ticket cache
used for authentication (unless the no_ccache option was given).
pam_setcred() then uses that environment variable to locate the
temporary cache even if it was not called in the same PAM session as
pam_authenticate() (a problem with sshd running in some
modes). 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. The pattern may be
changed 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 is 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.
CAVEATS¶
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.
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
http://www.eyrie.org/~eagle/software/pam-krb5/
<
http://www.eyrie.org/~eagle/software/pam-krb5/>.