svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
pam_krb5(7)
Standards, Environments, Macros, Character Sets, and miscellany
pam_krb5(7)
NAME
pam_krb5 - authentication, account, session, and password management
PAM modules for Kerberos V5
SYNOPSIS
/usr/lib/security/pam_krb5.so.1
DESCRIPTION
The Kerberos V5 service module for PAM provides functionality for all
four PAM modules: authentication, account management, session manage‐
ment, and password management. The service module is a shared object
that can be dynamically loaded to provide the necessary functionality
upon demand. Its path is specified in the PAM configuration file.
Kerberos Authentication Module
The Kerberos V5 authentication component provides functions to verify
the identity of a user, pam_sm_authenticate(), and to manage the Ker‐
beros credentials cache, pam_sm_setcred().
pam_sm_authenticate() authenticates a user principal through the Ker‐
beros authentication service. If PAM_AUSER and PAM_USER are both speci‐
fied and PAM_USER is a role, the user_attr(5) keyword roleauth is
checked to determine if the password that is checked is for the role
(PAM_USER) or the assuming user (PAM_AUSER). If the authentication
request is successful, the authentication service sends a ticket-grant‐
ing ticket (TGT) back to the service module, which then verifies that
the TGT came from a valid Key Distribution Center (KDC) by attempting
to get a service ticket for the local host service. For this to suc‐
ceed, the local host's keytab file (/etc/krb5/krb5.keytab) must contain
the entry for the local host service. For example, in the file
host/hostname.com@REALM, hostname.com is the fully qualified local
hostname and REALM is the default realm of the local host as defined in
/etc/krb5/krb5.conf. If the host entry is not found in the keytab file,
the authentication fails. Administrators can optionally disable this
"strict" verification by setting "verify_ap_req_nofail = false" in
/etc/krb5/krb5.conf. This allows TGT verification to succeed in the
absence of a keytab host principal entry.
If pam_sm_authenticate() is called and the pkinit module option is set,
the Kerberos V5 authentication module tries to do PKINIT authentica‐
tion, assuming that both the system and the KDC are configured to sup‐
port this type of authentication. This form of authentication uses a
user's certificate and private key to acquire the user's initial Ker‐
beros credential (TGT). One of the keystore formats supported is PKCS11
which supports use of any PKCS11 compatible keystore capable of storing
the required credential and private key needed for PKINIT authentica‐
tion (PKCS11 compatible smartcards are an example). This form of
authentication is typically useful for services where the system on
which the auth stack is being processed has access to the user's cer‐
tificate and private key.
If pam_sm_authenticate() is called and the pkinit module option is not
set then the Kerberos V5 authentication module does password based
authentication.
In either case, if the PAM_AUTHTOK password item has been set when
pam_sm_authenticate() is called, which is the case when pam_krb5 is
stacked after pam_authtok_get in the auth stack, the Kerberos V5
authentication module uses that PAM_AUTHTOK password for either PKINIT
or password based Kerberos authentication.
If the PAM_USER item is not set, pam_krb5 with the pkinit option
prompts for and sets that item.
If the PAM_AUTHTOK password item has not been set when pam_sm_authenti‐
cate() is called, which is the case when pam_krb5 is stacked before
pam_authtok_get in the auth stack, and the pkinit option is present the
Kerberos V5 authentication module allows the Kerberos pkinit preauth
plugin to prompt for whatever information is needed to perform PKINIT
(typically this is for the user's PIN). No PAM items are set by way of
this prompting.
The pam_krb5 module sets the KRB5CCNAME shell environment variable upon
successful authentication or password change to FILE:/tmp/volatile-
user/uid/krb5cc_uid where uid is the UID of the user that pam_krb5
authenticated.
If it is desirable to initially have the Kerberos V5 authentication
module try PKINIT Kerberos authentication and fall back to password
based Kerberos authentication then either the sufficient or optional
control flags must be provided for the instance of pam_krb5 with the
pkinit module option set and another instance of pam_krb5 without the
pkinit module option must be stacked below pam_authtok_get. If there
are PAM modules other than pam_krb5 that must be evaluated below
pam_authtok_get then the control flag should be set to optional for the
instance of pam_krb5 with the pkinit module option set otherwise the
control flag should be set to sufficient.
Only two instances of pam_krb5 are supported in a auth stack.
pam_sm_authenticate(3PAM) can be passed the following flag:
PAM_DISALLOW_NULL_AUTHTOK
This flag is ignored. The Kerberos authentication mechanism does
not allow an empty password string by default.
pam_sm_setcred() creates and modifies the user's credential cache. This
function initializes the user's credential cache, if it does not
already exist, and stores the initial credentials for later use by Ker‐
beros network applications. The following flags can be set in the flags
field. They are best described by their effect on the user's credential
cache.
PAM_ESTABLISH_CRED
Stores the initial credentials in the user's credential cache so
that the user can access Kerberos network services. If a successful
authentication pass was made, the new credentials are stored in the
credential cache, overwriting any existing credentials that were
previously stored. If an unsuccessful authentication pass was made,
PAM_CRED_UNAVAIL is returned.
PAM_DELETE_CRED
This flag has no effect on the credential cache and always returns
PAM_SUCCESS. The credential cache is not deleted because there is
no accurate method to determine if the credentials are needed by
another process. The credential cache can be deleted with the kde‐
stroy(1) command.
PAM_REINITIALIZE_CRED
Deletes the user's existing credential cache, if it exists, and
creates a new credential cache. The new credentials are stored in
the new cache and the user's ticket lifetime and renewable life
time values are reset.
PAM_REFRESH_CRED
Does not require a previous authentication pass, but if a success‐
ful one is made, the new credentials are stored in the credential
cache. If a previous authentication pass was not made or was unsuc‐
cessful, an attempt to renew the existing credentials is made. This
function fails if the user's renewable ticket lifetime is expired.
The following options can be passed to the Kerberos V5 authentication
module:
debug Provides syslog(3C) debugging information at
LOG_DEBUG level.
nowarn Turns off warning messages.
pkinit Indicates that the Kerberos V5 authentication mod‐
ule should try Kerberos PKINIT authentication
instead of the default password-based Kerberos.
realm=realm_name Indicates the realm name used to authenticate the
user rather than the system's default_realm as
defined in /etc/krb5/krb5.conf.
Note -
There could be possibilities that principals
names have collisions across multiple realms.
This could have a negative affect in environments
that have n-strikes for authentication attempts.
Given that the system may not have host creden‐
tials for every realm configured to perform ini‐
tial authentication with, they will not have the
ability to prevent KDC spoofing.
Kerberos V5 Account Management Module
The Kerberos account management component provides a function to per‐
form account management, pam_sm_acct_mgmt(). This function checks to
see if the pam_krb5 authentication module has noted that the user's
password has not expired. The following options can be passed in to the
Kerberos V5 account management module:
debug Provides syslog(3C) debugging information at LOG_DEBUG level
nowarn Turns off warning messages. Also, does not query KDC for
impending password expiration information used to warn the
user.
Kerberos V5 Session Management Module
The Kerberos V5 session management component provides functions to ini‐
tiate pam_sm_open_session() and terminate pam_sm_close_session() Ker‐
beros sessions. For Kerberos V5, both pam_sm_open_session and
pam_sm_close_session() are null functions, returning PAM_IGNORE.
Kerberos V5 Password Management Module
The Kerberos V5 password management component provides a function to
change passwords, pam_sm_chauthtok(), in the Key Distribution Center
(KDC) database.
If the Kerberos V5 authentication module used PKINIT authentication in
the auth stack then the Kerberos V5 password management module returns
PAM_IGNORE in the following cases:
o The new password is NULL.
o The old password is NULL.
o Verification of the old password fails.
The rationale behind this is that the KDC can not allow a PKINIT user
to change/set a password since the user can be expected to use PKINIT
only. If all of the cases above are false the Kerberos V5 password man‐
agement module tries to change the user's password in the KDC database.
If the KDC only supports PKINIT authentication then the Kerberos V5
password management module should not be present in any password
stacks.
Related to PKINIT the Kerberos V5 password management module does not
support changing the key store PIN used to access a user's private key
and certificate.
Local policy for password strength enforced by pam_authtok_check(7) is
bypassed, because kerberos passwords follow policy set by KDC (a.k.a.
remote server policy). See examples section for more details.
The following flags can be passed to pam_sm_chauthtok(3PAM):
PAM_CHANGE_EXPIRED_AUTHTOK
The password service should only update the user's Kerberos pass‐
word if it is expired. Otherwise, this function returns PAM_IGNORE.
The default behaviour is to always change the user's Kerberos pass‐
word.
PAM_PRELIM_CHECK
This is a null function that always returns PAM_IGNORE.
PAM_UPDATE_AUTHTOK
This flag is necessary to change the user's Kerberos password. If
this flag is not set, pam_krb5 returns PAM_SYSTEM_ERR.
The following option can be passed to the Kerberos V5 password module:
debug Provides syslog(3C) debugging information at LOG_DEBUG level.
ERRORS
The following error codes are returned for pam_sm_authenticate():
PAM_AUTH_ERR Authentication failure
PAM_BUF_ERR Memory buffer error.
PAM_IGNORE The user is "root" and the root key exists in the
default keytab.
PAM_SUCCESS Successfully obtained Kerberos credentials .
PAM_SYSTEM_ERR System error.
PAM_USER_UNKNOWN An unknown Kerberos principal was requested.
The following error codes are returned for pam_sm_setcred():
PAM_AUTH_ERR Authentication failure.
PAM_BUF_ERR Memory buffer error.
PAM_IGNORE The user is "root" and the root key exists in the
default keytab.
PAM_SYSTEM_ERR System error.
PAM_SUCCESS Successfully modified the Kerberos credential cache.
The following error codes are returned for pam_sm_acct_mgmt():
PAM_AUTH_ERR Authentication failure.
PAM_IGNORE Kerberos service module pam_sm_authenticate()
was never called, or the user is "root" and the
root key exists in the default keytab.
PAM_NEW_AUTHTOK_REQD Obtain new authentication token from the user.
PAM_SERVICE_ERR Error in underlying service module.
PAM_SUCCESS Kerberos principal account is valid.
PAM_SYSTEM_ERR System error.
PAM_USER_UNKNOWN An unknown Kerberos principal was requested.
The following error code is returned for pam_sm_open_session() and
pam_sm_close_session():
PAM_IGNORE These two functions are null functions in pam_krb5:
The following error codes are returned for pam_sm_chauthtok():
PAM_AUTH_ERR Authentication failure.
PAM_IGNORE The user has not been authenticated by Kerberos
service module pam_sm_authenticate(), or the
user is "root" and the root key exists in the
default keytab.
PAM_NEW_AUTHTOK_REQD User's Kerberos password has expired.
PAM_SERVICE_ERR Error in module. At least one input parameter
is missing.
PAM_SYSTEM_ERR System error.
PAM_USER_UNKNOWN An unknown Kerberos principal was requested.
PAM_SUCCESS Successfully changed the user's Kerberos pass‐
word.
EXAMPLES
Example 1 Authenticating Users Through Kerberos as First Choice Using
Password-based Authentication
The PAM policy file krb5_first uses Kerberos first and then falls back
to UNIX for authentication, account management, and password manage‐
ment. This configuration is helpful for mixed environments where some
users authenticate using Kerberos while other non-Kerberos accounts,
such as root, authenticate using UNIX. The krb5_first PAM policy can be
assigned to a user as follows:
# usermod -K pam_policy=krb5_first maria
Alternatively, to make this the default PAM policy for all users on the
system, the PAM_POLICY= key in policy.conf can be edited to specify
krb5_first. This is functionally equivalent to editing the PAM configu‐
ration on the system, /etc/pam.conf or /etc/pam.d/<service>, for all
non-Kerberized services to insert pam_krb5 before the equivalent PAM
modules which handle UNIX authentication with a control flag of 'suffi‐
cient'. For example, the gdm-password service is configured as follows:
For /etc/pam.conf:
gdm-password auth requisite pam_authtok_get.so.1
gdm-password auth required pam_unix_cred.so.1
gdm-password auth sufficient pam_krb5.so.1
gdm-password auth required pam_unix_auth.so.1
gdm-password account requisite pam_roles.so.1
gdm-password account required pam_unix_account.so.1
gdm-password account required pam_krb5.so.1
gdm-password password include pam_authtok_common
gdm-password password sufficient pam_krb5.so.1
gdm-password password required pam_authtok_store.so.1
For /etc/pam.d/gdm-password:
auth requisite pam_authtok_get.so.1
auth required pam_unix_cred.so.1
auth sufficient pam_krb5.so.1
auth required pam_unix_auth.so.1
account requisite pam_roles.so.1
account required pam_unix_account.so.1
account required pam_krb5.so.1
password include pam_authtok_common
password sufficient pam_krb5.so.1
password required pam_authtok_store.so.1
Also note there might be users with both credentials in such mixed
environment. For example user maria can have both passwords (local and
kerberos) set. In such case PAM policy attempts to authenticate the
user using kerberos. If kerberos fails,then PAM uses the same creden‐
tial the user has entered and retries with local password database
using pam_unix_auth pam_unix_auth(7). The same principle applies to
password change, PAM attempts to change kerberos password first, if it
fails, then it tries to update local password.
Example 2 Authenticating Users Through Kerberos Only Using Password-
based Authentication
The following example allows authentication only to users that have
Kerberos-based accounts.
The PAM policy file krb5_only uses only Kerberos for authentication,
account management, and password management. The krb5_only PAM policy
can be assigned to a user as follows:
# usermod -K pam_policy=krb5_only maria
Alternatively, to make this the default PAM policy for all users on the
system, the PAM_POLICY= key in policy.conf can be edited to specify
krb5_only. This is functionally equivalent to editing the PAM configu‐
ration on the system, /etc/pam.conf or /etc/pam.d/<service>, for all
non-Kerberized services to replacing the PAM modules which handle UNIX
authentication, account management, and password management with
pam_krb5. For example, the gdm-password service is configured as fol‐
lows:
For /etc/pam.conf:
gdm-password auth requisite pam_authtok_get.so.1
gdm-password auth required pam_unix_cred.so.1
gdm-password auth required pam_krb5.so.1
gdm-password account requisite pam_roles.so.1
gdm-password account required pam_krb5.so.1
gdm-password password include pam_authtok_common
gdm-password password required pam_krb5.so.1
For /etc/pam.d/gdm-password:
auth requisite pam_authtok_get.so.1
auth required pam_unix_cred.so.1
auth required pam_krb5.so.1
account requisite pam_roles.so.1
account required pam_krb5.so.1
password include pam_authtok_common
password required pam_krb5.so.1
In a Kerberos-only environment, some provision needs to be made to
allow local user accounts such as system administrator or database
administrator accounts to be able to login to the system. The easiest
way to do this is to assign the 'unix' PAM policy to these users as in
the following example:
# usermod -K pam_policy=unix sysop
If the desire is for local accounts to only be able to log into the
console, then the login PAM service will be configured to specify
authentication, account management, and password management using UNIX.
Example 3 Authenticating Through Kerberos Optionally Using Password-
based Authentication
This configuration is helpful when the majority of users are non-Ker‐
beros users and would like to authenticate through Kerberos if they
happened to exist in the Kerberos database. The effect of this is simi‐
lar to users voluntarily executing kinit(1) after they have success‐
fully logged in.
The PAM policy file krb5_optional uses UNIX for authentication, account
management, and password management, and optionally uses Kerberos for
authentication, account management, and password management for Ker‐
beros users. The krb5_optional PAM policy can be assigned to a user as
follows:
# usermod -K pam_policy=krb5_optional maria
Alternatively, to make this the default PAM policy for all users on the
system, the PAM_POLICY= key in policy.conf can be edited to specify
krb5_optional. This is functionally equivalent to editing the PAM con‐
figuration on the system, /etc/pam.conf or /etc/pam.d/<service>, for
all non-Kerberized services to append pam_krb5 after the equivalent PAM
modules which handle UNIX authentication with a control flag of
'optional'. For example, the gdm-password service is configured as fol‐
lows:
For /etc/pam.conf:
gdm-password auth requisite pam_authtok_get.so.1
gdm-password auth required pam_unix_auth.so.1
gdm-password auth required pam_unix_cred.so.1
gdm-password auth optional pam_krb5.so.1
gdm-password account requisite pam_roles.so.1
gdm-password account required pam_unix_account.so.1
gdm-password account optional pam_krb5.so.1
gdm-password password include pam_authtok_common
gdm-password password required pam_authtok_store.so.1
gdm-password password optional pam_krb5.so.1
For /etc/pam.d/gdm-password:
auth requisite pam_authtok_get.so.1
auth required pam_unix_auth.so.1
auth required pam_unix_cred.so.1
auth optional pam_krb5.so.1
account requisite pam_roles.so.1
account required pam_unix_account.so.1
account optional pam_krb5.so.1
password include pam_authtok_common
password required pam_authtok_store.so.1
password optional pam_krb5.so.1
Local users should specify the files repository using the -r option,
when changing their password with the passwd command.
Unlike krb5_first, user is always authenticated using local password.
The PAM stack then uses the same password to obtain a kerberos tgt
ticket so user does not need to do explicit kint(1)after obtaining a
login shell. The same principle applies to password change. passwd(1)
changes local password first, if it is successful it tries to change
kerberos password.
Example 4 Authenticating Users Through Kerberos PKINIT as First Choice
The following PAM configuration file authenticates users through the
Kerberos authentication service. It authenticates through the UNIX
login only if the Kerberos authentication (using PKINIT) fails. This
arrangement is helpful when a majority of the users are networked by
means of Kerberos and when there are only a few non-Kerberos type user
accounts, such as root. The service illustrated below is for login. The
user is prompted once for the PIN by pam_krb5.
login auth required pam_unix_cred.so.1
login auth sufficient pam_krb5.so.1 pkinit
login auth requisite pam_authtok_get.so.1
login auth required pam_unix_auth.so.1
Example 5 Authenticating Users Through Kerberos PKINIT Only
The following example allows authentication only to users that have
Kerberos-based accounts that require PKINIT authentication:
login auth required pam_unix_cred.so.1
login auth required pam_krb5.so.1 pkinit
Example 6 Authenticating Users Through Kerberos PKINIT Optionally
The following example allows users to acquire a Kerberos credential
using PKINIT authentication if they have a Kerberos account. Whether
pam_krb5 succeeds or fails the user must provide their UNIX password to
login.
login auth required pam_unix_cred.so.1
login auth optional pam_krb5.so.1 pkinit
login auth requisite pam_authtok_get.so.1
login auth required pam_unix_auth.so.1
Example 7 Authenticating Users Through Kerberos PKINIT as a Requirement
The following example allows users to login if pam_krb5 is able to
acquire a Kerberos credential using PKINT authentication and in addi‐
tion must provide their UNIX password to pam_unix_auth.
login auth required pam_unix_cred.so.1
login auth required pam_krb5.so.1 pkinit
login auth requisite pam_authtok_get.so.1
login auth required pam_unix_auth.so.1
Example 8 Authenticating Users Through Kerberos PKINIT as a Requirement
The following example allows users to login using their PAM_AUTHTOK
password acquired by pam_authtok_get. This password is used by pam_krb5
to try PKINIT authentication and is also used by pam_unix_auth to
authenticate the user using the user's UNIX account. If PKINIT requires
a password/PIN that differs from the user's UNIX password then pam_krb5
must be stacked above pam_authtok_get.
login auth required pam_unix_cred.so.1
login auth requisite pam_authtok_get.so.1
login auth required pam_krb5.so.1 pkinit
login auth required pam_unix_auth.so.1
Example 9 Authenticating Users Through Kerberos PKINIT with a Fallback
to Password-based Kerberos Authentication
The following example allows users to acquire a Kerberos credential
using PKINIT authentication or using password based authentication if
PKINIT fails. If PKINIT succeeds the user is not prompted for their
password. If pam_krb5 PKINIT succeeds, the second instance of pam_krb5
does not try password authentication and returns success. If PKINIT
fails the user is prompted for their Kerberos password.
login auth required pam_unix_cred.so.1
login auth sufficient pam_krb5.so.1 pkinit
login auth requisite pam_authtok_get.so.1
login auth required pam_krb5.so.1
Example 10 Authenticating Users Through Kerberos Requiring Users to
Authenticate Either Through Kerberos PKINIT or Fall Back to Password-
based Kerberos Authentication
The following example allows users to acquire a Kerberos credential
using PKINIT authentication or using password based authentication if
PKINIT fails. If pam_krb5 PKINIT succeeds, the second instance of
pam_krb5 does not try password authentication and returns ignore. If
pam_krb5 PKINIT fails, the second instance of pam_krb5 tries password
based authentication and returns success.
login auth required pam_unix_cred.so.1
login auth optional pam_krb5.so.1 pkinit
login auth requisite pam_authtok_get.so.1
login auth required pam_krb5.so.1
login auth required pam_unix_auth.so.1
Example 11 Authenticating Users Through Kerberos Requiring Users to
Authenticate Either Through Kerberos PKINIT or Fallback to pam_pkcs11
The following example allows users to acquire a Kerberos credential
using PKINIT authentication or if that fails use pam_pkcs11 to validate
the user's PIN using their certificate and private key.
login auth required pam_unix_cred.so.1
login auth sufficient pam_krb5.so.1 pkinit
login auth sufficient pam_pkcs11.so
Example 12 Authenticating Users Through Multiple Realms as First Choice
Using Password-based Authentication
This configuration can be used in combination with multiple pam_krb5 in
which different realms can be specified for one authentication pass.
For example:
gdm-password auth definitive pam_user_policy.so.1
gdm-password auth required pam_unix_cred.so.1
gdm-password auth sufficient pam_krb5.so.1
gdm-password auth sufficient pam_krb5.so.1 realm=EXAMPLE1.COM
gdm-password auth required pam_unix_auth.so.1
This will cause an initial authentication attempt for default_realm, as
configured in the /etc/krb5/krb5.conf file, realm first. If this fails
then an initial authentication attempt for the EXAMPLE1.COM is
attempted.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted
SEE ALSO
kdestroy(1), kinit(1), passwd(1), syslog(3C), libpam(3LIB), pam(3PAM),
pam_sm(3PAM), pam_sm_acct_mgmt(3PAM), pam_sm_authenticate(3PAM),
pam_sm_chauthtok(3PAM), pam_sm_close_session(3PAM), pam_sm_open_ses‐
sion(3PAM), pam_sm_setcred(3PAM), pam_user_policy(7), pam.conf(5),
attributes(7), pam_krb5_migrate(7), ktkt_warnd(8)
NOTES
The interfaces in libpam(3LIB) are MT-Safe only if each thread within
the multi-threaded application uses its own PAM handle.
On successful acquisition of initial credentials (ticket-granting
ticket), ktkt_warnd(8) is notified, to alert the user when the initial
credentials are about to expire.
Oracle Solaris 11.4 6 Feb 2020 pam_krb5(7)