Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

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 management, 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 Kerberos credentials cache, pam_sm_setcred().

pam_sm_authenticate() authenticates a user principal through the Kerberos authentication service. If PAM_AUSER and PAM_USER are both specified 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-granting 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 succeed, 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 authentication, assuming that both the system and the KDC are configured to support this type of authentication. This form of authentication uses a user's certificate and private key to acquire the user's initial Kerberos 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 authentication (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 certificate 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_authenticate() 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 Kerberos 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 kdestroy(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 successful one is made, the new credentials are stored in the credential cache. If a previous authentication pass was not made or was unsuccessful, 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 module 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 credentials for every realm configured to perform initial 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 perform 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 initiate pam_sm_open_session() and terminate pam_sm_close_session() Kerberos 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:

  • The new password is NULL.

  • The old password is NULL.

  • 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 management 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 password if it is expired. Otherwise, this function returns PAM_IGNORE. The default behaviour is to always change the user's Kerberos password.

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

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 management. 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 configuration 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 'sufficient'. 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 credential 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 configuration 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 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 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-Kerberos users and would like to authenticate through Kerberos if they happened to exist in the Kerberos database. The effect of this is similar to users voluntarily executing kinit(1) after they have successfully 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 Kerberos 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 configuration 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 follows:

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 kinit(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 addition 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:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed

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_session(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.