App-DocKnot
view release on metacpan or search on metacpan
t/data/generate/pam-krb5/docknot.yaml view on Meta::CPAN
- name: pam-krb5
title: Manual page
developer:
- name: todo
title: To-do list
blurb: |
pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal. It
supports ticket refreshing by screen savers, configurable authorization
handling, authentication of non-local accounts for network services,
password changing, and password expiration, as well as all the standard
expected PAM features. It works correctly with OpenSSH, even with
ChallengeResponseAuthentication and PrivilegeSeparation enabled, and
supports extensive configuration either by PAM options or in krb5.conf or
both. PKINIT is supported with recent versions of both MIT Kerberos and
Heimdal and FAST is supported with recent MIT Kerberos.
description: |
pam-krb5 provides a Kerberos PAM module that supports authentication, user
ticket cache handling, simple authorization (via .k5login or checking
Kerberos principals against local usernames), and password changing. It can
be configured through either options in the PAM configuration itself or
through entries in the system krb5.conf file, and it tries to work around
PAM implementation flaws in commonly-used PAM-enabled applications such as
OpenSSH and xdm. It supports both PKINIT and FAST to the extent that the
underlying Kerberos libraries support these features.
This is not the Kerberos PAM module maintained on Sourceforge and used on
Red Hat systems. It is an independent implementation that, if it ever
shared any common code, diverged long ago. It supports some features that
the Sourceforge module does not (particularly around authorization), and
t/data/generate/pam-krb5/docknot.yaml view on Meta::CPAN
Now, you can run the test suite with:
suffix: |
The default libkadm5clnt library on the system must match the
implementation of your KDC for the module/expired test to work, since the
two kadmin protocols are not compatible. If you use the MIT library
against a Heimdal server, the test will be skipped; if you use the Heimdal
library against an MIT server, the test suite may hang.
Several `module/expired` tests are expected to fail with Heimdal 1.5 due
to a bug in Heimdal with reauthenticating immediately after a
library-mediated password change of an expired password. This is fixed in
later releases of Heimdal.
To run the full test suite, Perl 5.10 or later is required. The following
additional Perl modules will be used if present:
* Test::Pod
* Test::Spelling
All are available on CPAN. Those tests will be skipped if the modules are
not available.
t/data/generate/pam-krb5/docknot.yaml view on Meta::CPAN
accounts. You normally want to do this since otherwise, if the network
is down, the Kerberos authentication can time out and make it difficult
to log in as root and fix matters. This also avoids problems with
Kerberos principals that happen to match system accounts accidentally
getting access to those accounts.
Be sure to include the module in the session group as well as the auth
group. Without the session entry, the user's ticket cache will not be
created properly for ssh logins (among possibly others).
If your users should normally all use Kerberos passwords exclusively,
putting something like:
```
password sufficient pam_krb5.so minimum_uid=1000
password required pam_unix.so try_first_pass obscure md5
```
in `/etc/pam.d/common-password` will change users' passwords in Kerberos
by default and then only fall back on Unix if that doesn't work. (You
can make this tighter by using the more complex new-style PAM
configuration.) If you instead want to synchronize local and Kerberos
passwords and change them both at the same time, you can do something
like:
```
password required pam_unix.so obscure sha512
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:
t/data/generate/pam-krb5/docknot.yaml view on Meta::CPAN
```
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.
t/data/generate/pam-krb5/docknot.yaml view on Meta::CPAN
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
t/data/generate/pam-krb5/output/readme view on Meta::CPAN
Leland Stanford Junior University. Copyright 2005 Andres Salomon
<dilinger@debian.org>. Copyright 1999-2000 Frank Cusack
<fcusack@fcusack.com>. This software is distributed under a BSD-style
license. Please see the section LICENSE below for more information.
BLURB
pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal.
It supports ticket refreshing by screen savers, configurable
authorization handling, authentication of non-local accounts for network
services, password changing, and password expiration, as well as all the
standard expected PAM features. It works correctly with OpenSSH, even
with ChallengeResponseAuthentication and PrivilegeSeparation enabled,
and supports extensive configuration either by PAM options or in
krb5.conf or both. PKINIT is supported with recent versions of both MIT
Kerberos and Heimdal and FAST is supported with recent MIT Kerberos.
DESCRIPTION
pam-krb5 provides a Kerberos PAM module that supports authentication,
user ticket cache handling, simple authorization (via .k5login or
checking Kerberos principals against local usernames), and password
changing. It can be configured through either options in the PAM
configuration itself or through entries in the system krb5.conf file,
and it tries to work around PAM implementation flaws in commonly-used
PAM-enabled applications such as OpenSSH and xdm. It supports both
PKINIT and FAST to the extent that the underlying Kerberos libraries
support these features.
This is not the Kerberos PAM module maintained on Sourceforge and used
on Red Hat systems. It is an independent implementation that, if it
ever shared any common code, diverged long ago. It supports some
t/data/generate/pam-krb5/output/readme view on Meta::CPAN
ensure that necessary environment variables are set up.
The default libkadm5clnt library on the system must match the
implementation of your KDC for the module/expired test to work, since
the two kadmin protocols are not compatible. If you use the MIT library
against a Heimdal server, the test will be skipped; if you use the
Heimdal library against an MIT server, the test suite may hang.
Several module/expired tests are expected to fail with Heimdal 1.5 due
to a bug in Heimdal with reauthenticating immediately after a
library-mediated password change of an expired password. This is fixed
in later releases of Heimdal.
To run the full test suite, Perl 5.10 or later is required. The
following additional Perl modules will be used if present:
* Test::Pod
* Test::Spelling
All are available on CPAN. Those tests will be skipped if the modules
are not available.
t/data/generate/pam-krb5/output/readme view on Meta::CPAN
accounts. You normally want to do this since otherwise, if the network
is down, the Kerberos authentication can time out and make it difficult
to log in as root and fix matters. This also avoids problems with
Kerberos principals that happen to match system accounts accidentally
getting access to those accounts.
Be sure to include the module in the session group as well as the auth
group. Without the session entry, the user's ticket cache will not be
created properly for ssh logins (among possibly others).
If your users should normally all use Kerberos passwords exclusively,
putting something like:
password sufficient pam_krb5.so minimum_uid=1000
password required pam_unix.so try_first_pass obscure md5
in /etc/pam.d/common-password will change users' passwords in Kerberos
by default and then only fall back on Unix if that doesn't work. (You
can make this tighter by using the more complex new-style PAM
configuration.) If you instead want to synchronize local and Kerberos
passwords and change them both at the same time, you can do something
like:
password required pam_unix.so obscure sha512
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:
t/data/generate/pam-krb5/output/readme view on Meta::CPAN
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.
DEBUGGING
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
t/data/generate/pam-krb5/output/readme view on Meta::CPAN
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.
HISTORY AND ACKNOWLEDGEMENTS
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.
t/data/generate/pam-krb5/output/readme-md view on Meta::CPAN
<dilinger@debian.org>. Copyright 1999-2000 Frank Cusack
<fcusack@fcusack.com>. This software is distributed under a BSD-style
license. Please see the section [License](#license) below for more
information.
## Blurb
pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal. It
supports ticket refreshing by screen savers, configurable authorization
handling, authentication of non-local accounts for network services,
password changing, and password expiration, as well as all the standard
expected PAM features. It works correctly with OpenSSH, even with
ChallengeResponseAuthentication and PrivilegeSeparation enabled, and
supports extensive configuration either by PAM options or in krb5.conf or
both. PKINIT is supported with recent versions of both MIT Kerberos and
Heimdal and FAST is supported with recent MIT Kerberos.
## Description
pam-krb5 provides a Kerberos PAM module that supports authentication, user
ticket cache handling, simple authorization (via .k5login or checking
Kerberos principals against local usernames), and password changing. It
can be configured through either options in the PAM configuration itself
or through entries in the system krb5.conf file, and it tries to work
around PAM implementation flaws in commonly-used PAM-enabled applications
such as OpenSSH and xdm. It supports both PKINIT and FAST to the extent
that the underlying Kerberos libraries support these features.
This is not the Kerberos PAM module maintained on Sourceforge and used on
Red Hat systems. It is an independent implementation that, if it ever
shared any common code, diverged long ago. It supports some features that
the Sourceforge module does not (particularly around authorization), and
t/data/generate/pam-krb5/output/readme-md view on Meta::CPAN
that necessary environment variables are set up.
The default libkadm5clnt library on the system must match the
implementation of your KDC for the module/expired test to work, since the
two kadmin protocols are not compatible. If you use the MIT library
against a Heimdal server, the test will be skipped; if you use the Heimdal
library against an MIT server, the test suite may hang.
Several `module/expired` tests are expected to fail with Heimdal 1.5 due
to a bug in Heimdal with reauthenticating immediately after a
library-mediated password change of an expired password. This is fixed in
later releases of Heimdal.
To run the full test suite, Perl 5.10 or later is required. The following
additional Perl modules will be used if present:
* Test::Pod
* Test::Spelling
All are available on CPAN. Those tests will be skipped if the modules are
not available.
t/data/generate/pam-krb5/output/readme-md view on Meta::CPAN
normally want to do this since otherwise, if the network is down, the
Kerberos authentication can time out and make it difficult to log in as
root and fix matters. This also avoids problems with Kerberos principals
that happen to match system accounts accidentally getting access to those
accounts.
Be sure to include the module in the session group as well as the auth
group. Without the session entry, the user's ticket cache will not be
created properly for ssh logins (among possibly others).
If your users should normally all use Kerberos passwords exclusively,
putting something like:
```
password sufficient pam_krb5.so minimum_uid=1000
password required pam_unix.so try_first_pass obscure md5
```
in `/etc/pam.d/common-password` will change users' passwords in Kerberos
by default and then only fall back on Unix if that doesn't work. (You can
make this tighter by using the more complex new-style PAM configuration.)
If you instead want to synchronize local and Kerberos passwords and change
them both at the same time, you can do something like:
```
password required pam_unix.so obscure sha512
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:
t/data/generate/pam-krb5/output/readme-md view on Meta::CPAN
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`.
## Debugging
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
t/data/generate/pam-krb5/output/readme-md view on Meta::CPAN
`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.
## History and Acknowledgements
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
t/data/generate/pam-krb5/output/thread view on Meta::CPAN
[Open HUB code analysis] \break
\link[https://tracker.debian.org/pkg/libpam-krb5]
[Debian package tracker] \break
]
\h2[Blurb]
pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal. It
supports ticket refreshing by screen savers, configurable authorization
handling, authentication of non-local accounts for network services,
password changing, and password expiration, as well as all the standard
expected PAM features. It works correctly with OpenSSH, even with
ChallengeResponseAuthentication and PrivilegeSeparation enabled, and
supports extensive configuration either by PAM options or in krb5.conf or
both. PKINIT is supported with recent versions of both MIT Kerberos and
Heimdal and FAST is supported with recent MIT Kerberos.
\h2[Description]
pam-krb5 provides a Kerberos PAM module that supports authentication, user
ticket cache handling, simple authorization (via .k5login or checking
Kerberos principals against local usernames), and password changing. It
can be configured through either options in the PAM configuration itself
or through entries in the system krb5.conf file, and it tries to work
around PAM implementation flaws in commonly-used PAM-enabled applications
such as OpenSSH and xdm. It supports both PKINIT and FAST to the extent
that the underlying Kerberos libraries support these features.
This is not the Kerberos PAM module maintained on Sourceforge and used on
Red Hat systems. It is an independent implementation that, if it ever
shared any common code, diverged long ago. It supports some features that
the Sourceforge module does not (particularly around authorization), and
t/data/generate/wallet/docknot.yaml view on Meta::CPAN
- name: api/kadmin-mit
title: Wallet::Kadmin::MIT
- name: api/object-base
title: Wallet::Object::Base
- name: api/object-duo
title: Wallet::Object::Duo
- name: api/object-file
title: Wallet::Object::File
- name: api/object-keytab
title: Wallet::Object::Keytab
- name: api/object-password
title: Wallet::Object::Password
- name: api/object-wakeyring
title: Wallet::Object::WAKeyring
- name: api/policy-stanford
title: Wallet::Policy::Stanford
- name: api/report
title: Wallet::Report
- name: api/schema
title: Wallet::Schema
- name: api/server
t/data/generate/wallet/docknot.yaml view on Meta::CPAN
All wallet actions are controlled by a fine-grained set of ACLs. Each
object has an owner ACL and optional get, store, show, destroy, and flags
ACLs that control more specific actions. A global administrative ACL
controls access to administrative actions. An ACL consists of zero or
more entries, each of which is a generic scheme and identifier pair,
allowing the ACL system to be extended to use any existing authorization
infrastructure. Supported ACL types include Kerberos principal names,
regexes matching Kerberos principal names, and LDAP attribute checks.
Currently, the object types supported are simple files, passwords,
Kerberos keytabs, WebAuth keyrings, and Duo integrations. By default,
whenever a Kerberos keytab object is retrieved from the wallet, the key is
changed in the Kerberos KDC and the wallet returns a keytab for the new
key. However, a keytab object can also be configured to preserve the
existing keys when retrieved. Included in the wallet distribution is a
script that can be run via remctl on an MIT Kerberos KDC to extract the
existing key for a principal, and the wallet system will use that
interface to retrieve the current key if the unchanging flag is set on a
Kerberos keytab object for MIT Kerberos. (Heimdal doesn't require any
special support.)
t/data/generate/wallet/docknot.yaml view on Meta::CPAN
MIT Kerberos 1.7 and later.
The WebAuth keyring object support in the wallet server requires the
WebAuth Perl module from
[WebAuth 4.4.0 or later](https://www.eyrie.org/~eagle/software/webauth/).
The Duo integration object support in the wallet server requires the
[Net::Duo](https://www.eyrie.org/~eagle/software/net-duo/), JSON, and
Perl6::Slurp Perl modules.
The password object support in the wallet server requires the
Crypt::GeneratePassword Perl module.
The LDAP attribute ACL verifier requires the Authen::SASL and Net::LDAP
Perl modules. This verifier only works with LDAP servers that support
GSS-API binds.
The NetDB ACL verifier (only of interest at sites using NetDB to manage
DNS) requires the Net::Remctl Perl module.
sections:
t/data/generate/wallet/output/readme view on Meta::CPAN
All wallet actions are controlled by a fine-grained set of ACLs. Each
object has an owner ACL and optional get, store, show, destroy, and
flags ACLs that control more specific actions. A global administrative
ACL controls access to administrative actions. An ACL consists of zero
or more entries, each of which is a generic scheme and identifier pair,
allowing the ACL system to be extended to use any existing authorization
infrastructure. Supported ACL types include Kerberos principal names,
regexes matching Kerberos principal names, and LDAP attribute checks.
Currently, the object types supported are simple files, passwords,
Kerberos keytabs, WebAuth keyrings, and Duo integrations. By default,
whenever a Kerberos keytab object is retrieved from the wallet, the key
is changed in the Kerberos KDC and the wallet returns a keytab for the
new key. However, a keytab object can also be configured to preserve
the existing keys when retrieved. Included in the wallet distribution
is a script that can be run via remctl on an MIT Kerberos KDC to extract
the existing key for a principal, and the wallet system will use that
interface to retrieve the current key if the unchanging flag is set on a
Kerberos keytab object for MIT Kerberos. (Heimdal doesn't require any
special support.)
t/data/generate/wallet/output/readme view on Meta::CPAN
The WebAuth keyring object support in the wallet server requires the
WebAuth Perl module from WebAuth 4.4.0 or later [2].
[2] https://www.eyrie.org/~eagle/software/webauth/
The Duo integration object support in the wallet server requires the
Net::Duo [3], JSON, and Perl6::Slurp Perl modules.
[3] https://www.eyrie.org/~eagle/software/net-duo/
The password object support in the wallet server requires the
Crypt::GeneratePassword Perl module.
The LDAP attribute ACL verifier requires the Authen::SASL and Net::LDAP
Perl modules. This verifier only works with LDAP servers that support
GSS-API binds.
The NetDB ACL verifier (only of interest at sites using NetDB to manage
DNS) requires the Net::Remctl Perl module.
To bootstrap from a Git checkout, or if you change the Automake files
t/data/generate/wallet/output/readme-md view on Meta::CPAN
All wallet actions are controlled by a fine-grained set of ACLs. Each
object has an owner ACL and optional get, store, show, destroy, and flags
ACLs that control more specific actions. A global administrative ACL
controls access to administrative actions. An ACL consists of zero or
more entries, each of which is a generic scheme and identifier pair,
allowing the ACL system to be extended to use any existing authorization
infrastructure. Supported ACL types include Kerberos principal names,
regexes matching Kerberos principal names, and LDAP attribute checks.
Currently, the object types supported are simple files, passwords,
Kerberos keytabs, WebAuth keyrings, and Duo integrations. By default,
whenever a Kerberos keytab object is retrieved from the wallet, the key is
changed in the Kerberos KDC and the wallet returns a keytab for the new
key. However, a keytab object can also be configured to preserve the
existing keys when retrieved. Included in the wallet distribution is a
script that can be run via remctl on an MIT Kerberos KDC to extract the
existing key for a principal, and the wallet system will use that
interface to retrieve the current key if the unchanging flag is set on a
Kerberos keytab object for MIT Kerberos. (Heimdal doesn't require any
special support.)
t/data/generate/wallet/output/readme-md view on Meta::CPAN
MIT Kerberos 1.7 and later.
The WebAuth keyring object support in the wallet server requires the
WebAuth Perl module from [WebAuth 4.4.0 or
later](https://www.eyrie.org/~eagle/software/webauth/).
The Duo integration object support in the wallet server requires the
[Net::Duo](https://www.eyrie.org/~eagle/software/net-duo/), JSON, and
Perl6::Slurp Perl modules.
The password object support in the wallet server requires the
Crypt::GeneratePassword Perl module.
The LDAP attribute ACL verifier requires the Authen::SASL and Net::LDAP
Perl modules. This verifier only works with LDAP servers that support
GSS-API binds.
The NetDB ACL verifier (only of interest at sites using NetDB to manage
DNS) requires the Net::Remctl Perl module.
To bootstrap from a Git checkout, or if you change the Automake files and
t/data/generate/wallet/output/thread view on Meta::CPAN
All wallet actions are controlled by a fine-grained set of ACLs. Each
object has an owner ACL and optional get, store, show, destroy, and flags
ACLs that control more specific actions. A global administrative ACL
controls access to administrative actions. An ACL consists of zero or
more entries, each of which is a generic scheme and identifier pair,
allowing the ACL system to be extended to use any existing authorization
infrastructure. Supported ACL types include Kerberos principal names,
regexes matching Kerberos principal names, and LDAP attribute checks.
Currently, the object types supported are simple files, passwords,
Kerberos keytabs, WebAuth keyrings, and Duo integrations. By default,
whenever a Kerberos keytab object is retrieved from the wallet, the key is
changed in the Kerberos KDC and the wallet returns a keytab for the new
key. However, a keytab object can also be configured to preserve the
existing keys when retrieved. Included in the wallet distribution is a
script that can be run via remctl on an MIT Kerberos KDC to extract the
existing key for a principal, and the wallet system will use that
interface to retrieve the current key if the unchanging flag is set on a
Kerberos keytab object for MIT Kerberos. (Heimdal doesn't require any
special support.)
t/data/generate/wallet/output/thread view on Meta::CPAN
The WebAuth keyring object support in the wallet server requires the
WebAuth Perl module from
\link[https://www.eyrie.org/~eagle/software/webauth/][WebAuth 4.4.0 or
later].
The Duo integration object support in the wallet server requires the
\link[https://www.eyrie.org/~eagle/software/net-duo/][Net::Duo], JSON, and
Perl6::Slurp Perl modules.
The password object support in the wallet server requires the
Crypt::GeneratePassword Perl module.
The LDAP attribute ACL verifier requires the Authen::SASL and Net::LDAP
Perl modules. This verifier only works with LDAP servers that support
GSS-API binds.
The NetDB ACL verifier (only of interest at sites using NetDB to manage
DNS) requires the Net::Remctl Perl module.
To bootstrap from a Git checkout, or if you change the Automake files and
t/data/generate/wallet/output/thread view on Meta::CPAN
\doc[api/config.html][Wallet::Config]
\doc[api/database.html][Wallet::Database]
\doc[api/kadmin.html][Wallet::Kadmin]
\doc[api/kadmin-ad.html][Wallet::Kadmin::AD]
\doc[api/kadmin-heimdal.html][Wallet::Kadmin::Heimdal]
\doc[api/kadmin-mit.html][Wallet::Kadmin::MIT]
\doc[api/object-base.html][Wallet::Object::Base]
\doc[api/object-duo.html][Wallet::Object::Duo]
\doc[api/object-file.html][Wallet::Object::File]
\doc[api/object-keytab.html][Wallet::Object::Keytab]
\doc[api/object-password.html][Wallet::Object::Password]
\doc[api/object-wakeyring.html][Wallet::Object::WAKeyring]
\doc[api/policy-stanford.html][Wallet::Policy::Stanford]
\doc[api/report.html][Wallet::Report]
\doc[api/schema.html][Wallet::Schema]
\doc[api/server.html][Wallet::Server]
]
\h2(after)[License]
The wallet package as a whole is covered by the following copyright and
t/data/spin/input/.rss view on Meta::CPAN
Test entry — with UTF-8 dash.
Date: 2021-08-30 21:25
Title: kstart 4.3
Link: software/kstart/
Description:
Add support for kafs by continuing with -t behavior if kafs is present.
Use libkeyutils if available to isolate a command's keyring from the
invoking program if running a specific command with -t. Use a better
exit status when a command is killed with a signal. Use explicit_bzero
to clear the password for k5start -s. Other portability fixes and
updates.
Date: 2021-08-18 21:30
Title: Review: The Past is Red
Link: reviews/books/1-250-30112-2.html
Description: Review of The Past is Red by Catherynne M. Valente.
Date: 2021-08-16 20:58
Title: Review: Black Sun
Link: reviews/books/1-5344-3769-X.html
t/data/spin/output/changes.html view on Meta::CPAN
Test entry — with UTF-8 dash.
</p></dd>
<dt>2021-08-30 —
<a href="https://www.eyrie.org/~eagle/software/kstart/">kstart 4.3</a></dt>
<dd><p>
Add support for kafs by continuing with -t behavior if kafs is present.
Use libkeyutils if available to isolate a command's keyring from the
invoking program if running a specific command with -t. Use a better
exit status when a command is killed with a signal. Use explicit_bzero
to clear the password for k5start -s. Other portability fixes and
updates.
</p></dd>
<dt>2021-08-18 —
<a href="https://www.eyrie.org/~eagle/reviews/books/1-250-30112-2.html">Review: The Past is Red</a></dt>
<dd><p>
Review of The Past is Red by Catherynne M. Valente.
</p></dd>
<dt>2021-08-16 —
t/data/spin/output/changes.rss view on Meta::CPAN
<guid isPermaLink="false">%DATE%</guid>
</item>
<item>
<title>kstart 4.3</title>
<link>https://www.eyrie.org/~eagle/software/kstart/</link>
<description><![CDATA[
<p>Add support for kafs by continuing with -t behavior if kafs is present.
Use libkeyutils if available to isolate a command's keyring from the
invoking program if running a specific command with -t. Use a better
exit status when a command is killed with a signal. Use explicit_bzero
to clear the password for k5start -s. Other portability fixes and
updates.</p>
]]></description>
<pubDate>%DATE%</pubDate>
<guid isPermaLink="false">%DATE%</guid>
</item>
<item>
<title>Review: The Past is Red</title>
<link>https://www.eyrie.org/~eagle/reviews/books/1-250-30112-2.html</link>
<description><![CDATA[
<p>Review of The Past is Red by Catherynne M. Valente.</p>
t/data/spin/text/input/mjqmail view on Meta::CPAN
require listing every individual list address in the virtualdomains file,
though, so using the qmail-users mechanism is probably simpler for that
case.
------------------------------
Subject: 2.4. Using qmail-users
The qmail-users man page, along with the documentation for qmail-pw2u and
qmail-newu, contains the full details on how the qmail-users mechanism
works, but basically qmail-pw2u is run on the password file to generate a
list of addresses mail is accepted at, what UID and GID to switch to when
delivering mail for a user, and where to deliver the mail (the user's home
directory).
Assuming that Majordomo is installed in /var/qmail/majordomo, create
/var/qmail/users/mailnames if it doesn't exist and add the following:
lists:lists:majordomo
(replacing lists with the name of your Majordomo user). This will be used
t/data/spin/text/output/mjqmail.html view on Meta::CPAN
though, so using the qmail-users mechanism is probably simpler for that
case.
</p>
<h2><a name="S2.4" id="S2.4">2.4. Using qmail-users</a></h2>
<p>
The qmail-users man page, along with the documentation for qmail-pw2u and
qmail-newu, contains the full details on how the qmail-users mechanism
works, but basically qmail-pw2u is run on the password file to generate a
list of addresses mail is accepted at, what UID and GID to switch to when
delivering mail for a user, and where to deliver the mail (the user's home
directory).
</p>
<p>
Assuming that Majordomo is installed in /var/qmail/majordomo, create
/var/qmail/users/mailnames if it doesn't exist and add the following:
</p>
t/data/update/pam-krb5/docknot.yaml view on Meta::CPAN
---
advisories:
- date: 2009-02-11
threshold: '3.13'
versions: 3.12 and earlier
blurb: |
pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal. It
supports ticket refreshing by screen savers, configurable authorization
handling, authentication of non-local accounts for network services,
password changing, and password expiration, as well as all the standard
expected PAM features. It works correctly with OpenSSH, even with
ChallengeResponseAuthentication and PrivilegeSeparation enabled, and
supports extensive configuration either by PAM options or in krb5.conf or
both. PKINIT is supported with recent versions of both MIT Kerberos and
Heimdal and FAST is supported with recent MIT Kerberos.
build:
autoconf: '2.64'
automake: '1.11'
autotools: true
kerberos: true
t/data/update/pam-krb5/docknot.yaml view on Meta::CPAN
years: 2005-2010, 2014-2015, 2017
- holder: The Board of Trustees of the Leland Stanford Junior University
years: 2009-2011
- holder: Andres Salomon <dilinger@debian.org>
years: '2005'
- holder: Frank Cusack <fcusack@fcusack.com>
years: 1999-2000
description: |
pam-krb5 provides a Kerberos PAM module that supports authentication, user
ticket cache handling, simple authorization (via .k5login or checking
Kerberos principals against local usernames), and password changing. It
can be configured through either options in the PAM configuration itself
or through entries in the system krb5.conf file, and it tries to work
around PAM implementation flaws in commonly-used PAM-enabled applications
such as OpenSSH and xdm. It supports both PKINIT and FAST to the extent
that the underlying Kerberos libraries support these features.
This is not the Kerberos PAM module maintained on Sourceforge and used on
Red Hat systems. It is an independent implementation that, if it ever
shared any common code, diverged long ago. It supports some features that
the Sourceforge module does not (particularly around authorization), and
t/data/update/pam-krb5/docknot.yaml view on Meta::CPAN
normally want to do this since otherwise, if the network is down, the
Kerberos authentication can time out and make it difficult to log in as
root and fix matters. This also avoids problems with Kerberos principals
that happen to match system accounts accidentally getting access to those
accounts.
Be sure to include the module in the session group as well as the auth
group. Without the session entry, the user's ticket cache will not be
created properly for ssh logins (among possibly others).
If your users should normally all use Kerberos passwords exclusively,
putting something like:
```
password sufficient pam_krb5.so minimum_uid=1000
password required pam_unix.so try_first_pass obscure md5
```
in `/etc/pam.d/common-password` will change users' passwords in Kerberos
by default and then only fall back on Unix if that doesn't work. (You can
make this tighter by using the more complex new-style PAM configuration.)
If you instead want to synchronize local and Kerberos passwords and change
them both at the same time, you can do something like:
```
password required pam_unix.so obscure sha512
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:
t/data/update/pam-krb5/docknot.yaml view on Meta::CPAN
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: Configuring
- 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.
t/data/update/pam-krb5/docknot.yaml view on Meta::CPAN
`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: Implementation Notes
- 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
t/data/update/pam-krb5/docknot.yaml view on Meta::CPAN
Now, you can run the test suite with:
suffix: |
The default libkadm5clnt library on the system must match the
implementation of your KDC for the module/expired test to work, since the
two kadmin protocols are not compatible. If you use the MIT library
against a Heimdal server, the test will be skipped; if you use the Heimdal
library against an MIT server, the test suite may hang.
Several `module/expired` tests are expected to fail with Heimdal 1.5 due
to a bug in Heimdal with reauthenticating immediately after a
library-mediated password change of an expired password. This is fixed in
later releases of Heimdal.
vcs:
browse: https://git.eyrie.org/?p=kerberos/pam-krb5.git
github: rra/pam-krb5
openhub: https://www.openhub.net/p/pamkrb5
type: Git
url: https://git.eyrie.org/git/kerberos/pam-krb5.git
version: '4.8'
t/data/update/pam-krb5/old/blurb view on Meta::CPAN
pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal. It
supports ticket refreshing by screen savers, configurable authorization
handling, authentication of non-local accounts for network services,
password changing, and password expiration, as well as all the standard
expected PAM features. It works correctly with OpenSSH, even with
ChallengeResponseAuthentication and PrivilegeSeparation enabled, and
supports extensive configuration either by PAM options or in krb5.conf or
both. PKINIT is supported with recent versions of both MIT Kerberos and
Heimdal and FAST is supported with recent MIT Kerberos.
t/data/update/pam-krb5/old/description view on Meta::CPAN
pam-krb5 provides a Kerberos PAM module that supports authentication, user
ticket cache handling, simple authorization (via .k5login or checking
Kerberos principals against local usernames), and password changing. It
can be configured through either options in the PAM configuration itself
or through entries in the system krb5.conf file, and it tries to work
around PAM implementation flaws in commonly-used PAM-enabled applications
such as OpenSSH and xdm. It supports both PKINIT and FAST to the extent
that the underlying Kerberos libraries support these features.
This is not the Kerberos PAM module maintained on Sourceforge and used on
Red Hat systems. It is an independent implementation that, if it ever
shared any common code, diverged long ago. It supports some features that
the Sourceforge module does not (particularly around authorization), and
t/data/update/pam-krb5/old/sections/configuring view on Meta::CPAN
normally want to do this since otherwise, if the network is down, the
Kerberos authentication can time out and make it difficult to log in as
root and fix matters. This also avoids problems with Kerberos principals
that happen to match system accounts accidentally getting access to those
accounts.
Be sure to include the module in the session group as well as the auth
group. Without the session entry, the user's ticket cache will not be
created properly for ssh logins (among possibly others).
If your users should normally all use Kerberos passwords exclusively,
putting something like:
```
password sufficient pam_krb5.so minimum_uid=1000
password required pam_unix.so try_first_pass obscure md5
```
in `/etc/pam.d/common-password` will change users' passwords in Kerberos
by default and then only fall back on Unix if that doesn't work. (You can
make this tighter by using the more complex new-style PAM configuration.)
If you instead want to synchronize local and Kerberos passwords and change
them both at the same time, you can do something like:
```
password required pam_unix.so obscure sha512
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:
t/data/update/pam-krb5/old/sections/configuring view on Meta::CPAN
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`.
t/data/update/pam-krb5/old/sections/implementation-notes view on Meta::CPAN
`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.
t/data/update/pam-krb5/old/test/suffix view on Meta::CPAN
The default libkadm5clnt library on the system must match the
implementation of your KDC for the module/expired test to work, since the
two kadmin protocols are not compatible. If you use the MIT library
against a Heimdal server, the test will be skipped; if you use the Heimdal
library against an MIT server, the test suite may hang.
Several `module/expired` tests are expected to fail with Heimdal 1.5 due
to a bug in Heimdal with reauthenticating immediately after a
library-mediated password change of an expired password. This is fixed in
later releases of Heimdal.
( run in 1.688 second using v1.01-cache-2.11-cpan-49f99fa48dc )