App-DocKnot
view release on metacpan - search on metacpan
view release on metacpan or search on metacpan
t/data/generate/pam-krb5/docknot.yaml view on Meta::CPAN
password required pam_krb5.so use_authtok minimum_uid=1000
```
If you have multiple environments that you want to synchronize and you
don't want password changes to continue if the Kerberos password change
fails, use the `clear_on_fail` option. For example:
```
password required pam_krb5.so clear_on_fail minimum_uid=1000
password required pam_unix.so use_authtok obscure sha512
password required pam_smbpass.so use_authtok
```
In this case, if `pam_krb5` cannot change the password (due to password
strength rules on the KDC, for example), it will clear the stored
password (because of the `clear_on_fail` option), and since `pam_unix`
and `pam_smbpass` are both configured with `use_authtok`, they will both
fail. `clear_on_fail` is not the default because it would interfere
with the more common pattern of falling back to local passwords if the
user doesn't exist in Kerberos.
If you use a more complex configuration with the Linux PAM `[]` syntax
for the session and account groups, note that `pam_krb5` returns a
status of ignore, not success, if the user didn't log on with Kerberos.
You may need to handle that explicitly with `ignore=ignore` in your
action list.
There are many, many other possibilities. See the Linux PAM
documentation for all the configuration options.
On Red Hat systems, modify `/etc/pam.d/system-auth` instead, which
contains all of the configuration for the different stacks.
You can also use pam-krb5 only for specific services. In that case,
modify the files in `/etc/pam.d` for that particular service to use
`pam_krb5.so` for authentication. For services that are using passwords
over TLS to authenticate users, you may want to use the `ignore_k5login`
and `no_ccache` options to the authenticate module. `.k5login`
authorization is only meaningful for local accounts and ticket caches
are usually (although not always) only useful for interactive sessions.
Configuring the module for Solaris is both simpler and less flexible,
since Solaris (at least Solaris 8 and 9, which are the last versions of
Solaris with which this module was extensively tested) use a single
`/etc/pam.conf` file that contains configuration for all programs. For
console login on Solaris, try something like:
```
login auth sufficient /usr/local/lib/security/pam_krb5.so minimum_uid=100
login auth required /usr/lib/security/pam_unix_auth.so.1 use_first_pass
login account required /usr/local/lib/security/pam_krb5.so minimum_uid=100
login account required /usr/lib/security/pam_unix_account.so.1
login session required /usr/local/lib/security/pam_krb5.so retain_after_close minimum_uid=100
login session required /usr/lib/security/pam_unix_session.so.1
```
A similar configuration could be used for other services, such as ssh.
See the pam.conf(5) man page for more information. When using this
module with Solaris login (at least on Solaris 8 and 9), you will
probably also need to add `retain_after_close` to the PAM configuration
to avoid having the user's credentials deleted before they are logged
in.
The Solaris Kerberos library reportedly does not support prompting for a
password change of an expired account during authentication. Supporting
password change for expired accounts on Solaris with native Kerberos may
therefore require setting the `defer_pwchange` or `force_pwchange`
option for selected login applications. See the description and
warnings about that option in the pam_krb5(5) man page.
Some configuration options may be put in the `krb5.conf` file used by
your Kerberos libraries (usually `/etc/krb5.conf` or
`/usr/local/etc/krb5.conf`) instead or in addition to the PAM
configuration. See the man page for more details.
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`.
- title: Debugging
body: |
The first step when debugging any problems with this module is to add
`debug` to the PAM options for the module (either in the PAM
configuration or in `krb5.conf`). This will significantly increase the
logging from the module and should provide a trace of exactly what
failed and any available error information.
Many Kerberos authentication problems are due to configuration issues in
`krb5.conf`. If pam-krb5 doesn't work, first check that `kinit` works
on the same system. That will test your basic Kerberos configuration.
If the system has a keytab file installed that's readable by the process
doing authentication via PAM, make sure that the keytab is current and
contains a key for `host/<system>` where <system> is the fully-qualified
hostname. pam-krb5 prevents KDC spoofing by checking the user's
credentials when possible, but this means that if a keytab is present it
must be correct or authentication will fail. You can check the keytab
with `klist -k` and `kinit -k`.
Be sure that all libraries and modules, including PAM modules, loaded by
a program use the same Kerberos libraries. Sometimes programs that use
PAM, such as current versions of OpenSSH, also link against Kerberos
directly. If your sshd is linked against one set of Kerberos libraries
and pam-krb5 is linked against a different set of Kerberos libraries,
this will often cause problems (such as segmentation faults, bus errors,
assertions, or other strange behavior). Similar issues apply to the
com_err library or any other library used by both modules and shared
libraries and by the application that loads them. If your OS ships
Kerberos libraries, it's usually best if possible to build all Kerberos
software on the system against those libraries.
- title: Implementation Notes
body: |
The normal sequence of actions taken for a user login is:
```
pam_authenticate
pam_setcred(PAM_ESTABLISH_CRED)
pam_open_session
pam_acct_mgmt
```
and then at logout:
```
pam_close_session
```
followed by closing the open PAM session. The corresponding `pam_sm_*`
functions in this module are called when an application calls those
public interface functions. Not all applications call all of those
functions, or in particularly that order, although `pam_authenticate` is
always first and has to be.
When `pam_authenticate` is called, pam-krb5 creates a temporary ticket
cache in `/tmp` and sets the PAM environment variable `PAM_KRB5CCNAME`
to point to it. This ticket cache will be automatically destroyed when
the PAM session is closed and is there only to pass the initial
credentials to the call to `pam_setcred`. The module would use a memory
cache, but memory caches will only work if the application preserves the
PAM environment between the calls to `pam_authenticate` and
`pam_setcred`. Most do, but OpenSSH notoriously does not and calls
`pam_authenticate` in a subprocess, so this method is used to pass the
tickets to the `pam_setcred` call in a different process.
`pam_authenticate` does a complete authentication, including checking
the resulting TGT by obtaining a service ticket for the local host if
possible, but this requires read access to the system keytab. If the
keytab doesn't exist, can't be read, or doesn't include the appropriate
credentials, the default is to accept the authentication. This can be
controlled by setting `verify_ap_req_nofail` to true in `[libdefaults]`
in `/etc/krb5.conf`. `pam_authenticate` also does a basic authorization
check, by default calling `krb5_kuserok` (which uses `~/.k5login` if
available and falls back to checking that the principal corresponds to
the account name). This can be customized with several options
documented in the pam_krb5(5) man page.
pam-krb5 treats `pam_open_session` and `pam_setcred(PAM_ESTABLISH_CRED)`
as synonymous, as some applications call one and some call the other.
Both copy the initial credentials from the temporary cache into a
permanent cache for this session and set `KRB5CCNAME` in the
environment. It will remember when the credential cache has been
established and then avoid doing any duplicate work afterwards, since
some applications call `pam_setcred` or `pam_open_session` multiple
times (most notably X.Org 7 and earlier xdm, which also throws away the
module settings the last time it calls them).
`pam_acct_mgmt` finds the ticket cache, reads it in to obtain the
authenticated principal, and then does is another authorization check
against `.k5login` or the local account name as described above.
After the call to `pam_setcred` or `pam_open_session`, the ticket cache
will be destroyed whenever the calling application either destroys the
PAM environment or calls `pam_close_session`, which it should do on user
logout.
The normal sequence of events when refreshing a ticket cache (such as
inside a screensaver) is:
```
pam_authenticate
pam_setcred(PAM_REINITIALIZE_CRED)
pam_acct_mgmt
```
(`PAM_REFRESH_CRED` may be used instead.) Authentication proceeds as
above. At the `pam_setcred` stage, rather than creating a new ticket
cache, the module instead finds the current ticket cache (from the
`KRB5CCNAME` environment variable or the default ticket cache location
from the Kerberos library) and then reinitializes it with the
credentials from the temporary `pam_authenticate` ticket cache. When
refreshing a ticket cache, the application should not open a session.
Calling `pam_acct_mgmt` is optional; pam-krb5 doesn't do anything
different when it's called in this case.
If `pam_authenticate` apparently didn't succeed, or if an account was
configured to be ignored via `ignore_root` or `minimum_uid`,
`pam_setcred` (and therefore `pam_open_session`) and `pam_acct_mgmt`
return `PAM_IGNORE`, which tells the PAM library to proceed as if that
module wasn't listed in the PAM configuration at all.
`pam_authenticate`, however, returns failure in the ignored user case by
default, since otherwise a configuration using `ignore_root` with
pam-krb5 as the only PAM module would allow anyone to log in as root
without a password. There doesn't appear to be a case where returning
`PAM_IGNORE` instead would improve the module's behavior, but if you
know of a case, please let me know.
By default, `pam_authenticate` intentionally does not follow the PAM
standard for handling expired accounts and instead returns failure from
`pam_authenticate` unless the Kerberos libraries are able to change the
account password during authentication. Too many applications either do
not call `pam_acct_mgmt` or ignore its exit status. The fully correct
PAM behavior (returning success from `pam_authenticate` and
`PAM_NEW_AUTHTOK_REQD` from `pam_acct_mgmt`) can be enabled with the
`defer_pwchange` option.
The `defer_pwchange` option is unfortunately somewhat tricky to
implement. In this case, the calling sequence is:
```
pam_authenticate
pam_acct_mgmt
pam_chauthtok
pam_setcred
pam_open_session
```
During the first `pam_authenticate`, we can't obtain credentials and
therefore a ticket cache since the password is expired. But
`pam_authenticate` isn't called again after `pam_chauthtok`, so
`pam_chauthtok` has to create a ticket cache. We however don't want it
to do this for the normal password change (`passwd`) case.
What we do is set a flag in our PAM data structure saying that we're
processing an expired password, and `pam_chauthtok`, if it sees that
flag, redoes the authentication with password prompting disabled after
it finishes changing the password.
Unfortunately, when handling password changes this way, `pam_chauthtok`
will always have to prompt the user for their current password again
even though they just typed it. This is because the saved
authentication tokens are cleared after `pam_authenticate` returns, for
security reasons. We could hack around this by saving the password in
our PAM data structure, but this would let the application gain access
to it (exactly what the clearing is intended to prevent) and breaks a
PAM library guarantee. We could also work around this by having
`pam_authenticate` get the `kadmin/changepw` authenticator in the
expired password case and store it for `pam_chauthtok`, but it doesn't
seem worth the hassle.
- title: History and Acknowledgements
body: |
Originally written by Frank Cusack <fcusack@fcusack.com>, with the
following acknowledgement:
> Thanks to Naomaru Itoi <itoi@eecs.umich.edu>, Curtis King
> <curtis.king@cul.ca>, and Derrick Brashear <shadow@dementia.org>, all
> of whom have written and made available Kerberos 4/5 modules.
> Although no code in this module is directly from these author's
> modules, (except the get_user_info() routine in support.c; derived
> from whichever of these authors originally wrote the first module the
> other 2 copied from), it was extremely helpful to look over their code
> which aided in my design.
The module was then patched for the FreeBSD ports collection with
additional modifications by unknown maintainers and then was modified by
Joel Kociolek <joko@logidee.com> to be usable with Debian GNU/Linux.
It was packaged by Sam Hartman as the Kerberos v5 PAM module for Debian
and improved and modified by him and later by Russ Allbery to fix bugs
and add additional features. It was then adopted by Andres Salomon, who
added support for refreshing credentials.
The current distribution is maintained by Russ Allbery, who also added
support for reading configuration from `krb5.conf`, added many features
for compatibility with the Sourceforge module, commented and
standardized the formatting of the code, and overhauled the
documentation.
Thanks to Douglas E. Engert for the initial implementation of PKINIT
support. I have since modified and reworked it extensively, so any bugs
or compilation problems are my fault.
Thanks to Markus Moeller for lots of debugging and multiple patches and
suggestions for improved portability.
Thanks to Booker Bense for the implementation of the `alt_auth_map`
option.
Thanks to Sam Hartman for the FAST support implementation.
view all matches for this distributionview release on metacpan - search on metacpan
( run in 0.473 second using v1.00-cache-2.02-grep-82fe00e-cpan-2c419f77a38b )