xref: /illumos-gate/usr/src/man/man7/pam_krb5_migrate.7 (revision b8052df9f609edb713f6828c9eecc3d7be19dfb3) 
 te
 Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 PAM_KRB5_MIGRATE 7 "November 22, 2021"
 NAME
pam_krb5_migrate - authentication PAM module for the KerberosV5 auto-migration
of users feature

 SYNOPSIS
/usr/lib/security/pam_krb5_migrate.so.1




 DESCRIPTION
The KerberosV5 auto-migrate service module for PAM provides functionality for
the PAM authentication component. The service module helps in the automatic
migration of PAM_USER to the client's local Kerberos realm, using
PAM_AUTHTOK (the PAM authentication token associated with PAM_USER)
as the new Kerberos principal's password.

 "KerberosV5 Auto-migrate Authentication Module"
The KerberosV5 auto-migrate authentication component provides the
pam_sm_authenticate(3PAM) function to migrate a user who does not have a
corresponding krb5 principal account to the default Kerberos realm of the
client.


pam_sm_authenticate(3PAM) uses a host-based client service principal,
present in the local keytab (/etc/krb5/krb5.keytab) to authenticate
to kadmind(8) (defaults to the host/nodename.fqdn service
principal), for the principal creation operation. Also, for successful creation
of the krb5 user principal account, the host-based client service
principal being used needs to be assigned the appropriate privilege on the
master KDC's kadm5.acl(5) file. kadmind(8) checks for the
appropriate privilege and validates the user password using PAM by calling
pam_authenticate(3PAM) and pam_acct_mgmt(3PAM) for the
k5migrate service.


If migration of the user to the KerberosV5 infrastructure is successful, the
module will inform users about it by means of a PAM_TEXT_INFO message,
unless instructed otherwise by the presence of the quiet option.


The authentication component always returns PAM_IGNORE and is meant to be
stacked in pam.conf with a requirement that it be listed below
pam_authtok_get(7) in the authentication stack. Also, if pam_krb5_migrate
is used in the authentication stack of a particular service, it is mandatory
that pam_krb5(7) be listed in the PAM account stack of that service for
proper operation (see EXAMPLES).

 OPTIONS
The following options can be passed to the KerberosV5 auto-migrate
authentication module:
debug


Provides syslog(3C) debugging information at LOG_DEBUG level.



client_service=<service name>


Name of the service used to authenticate to kadmind(8) defaults to
host. This means that the module uses host/<nodename.fqdn> as
its client service principal name, KerberosV5 user principal creation operation
or <service>/<nodename.fqdn> if this option is provided.



quiet


Do not explain KerberosV5 migration to the user.
This has the same effect as passing the PAM_SILENT flag to
pam_sm_authenticate(3PAM) and is useful where applications cannot handle
PAM_TEXT_INFO messages.
If not set, the authentication component will issue a PAM_TEXT_INFO
message after creation of the Kerberos V5 principal, indicating that it has
done so.



expire_pw


Causes the creation of KerberosV5 user principals with password expiration set
to now (current time).




 EXAMPLES
Example 1 Sample Entries from pam.conf


The following entries from pam.conf(5) demonstrate the use of the
pam_krb5_migrate.so.1 module:


login auth requisite pam_authtok_get.so.1
login auth required pam_dhkeys.so.1
login auth required pam_unix_cred.so.1
login auth sufficient pam_krb5.so.1
login auth requisite pam_unix_auth.so.1
login auth optional pam_krb5_migrate.so.1 expire_pw
login auth required pam_dial_auth.so.1

other account requisite pam_roles.so.1
other account required pam_krb5.so.1
other account required pam_unix_account.so.1





The pam_krb5_migrate module can generally be present on the
authentication stack of any service where the application calls
pam_sm_authenticate(3PAM) and an authentication token (in the preceding
example, the authentication token would be the user's Unix password) is
available for use as a Kerberos V5 password.



Example 2 Sample Entries from kadm5.acl


The following entries from kadm5.acl(5) permit or deny privileges to the
host client service principal:


host/*@EXAMPLE.COM U root
host/*@EXAMPLE.COM ui *





The preceding entries permit the pam_krb5_migrate add privilege to
the host client service principal of any machine in the EXAMPLE.COM
KerberosV5 realm, but denies the add privilege to all host service
principals for addition of the root user account.



Example 3 Sample Entries in pam.conf of the Master KDC


The entries below enable kadmind(8) on the master KDC to use the
k5migrate PAM service in order to validate Unix user passwords for
accounts that require migration to the Kerberos realm.


k5migrate auth required pam_unix_auth.so.1
k5migrate account required pam_unix_account.so.1




 ATTRIBUTES
See attributes(7) for a description of the following attribute:






ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Evolving



 SEE ALSO
 syslog (3C),  pam_acct_mgmt (3PAM),  pam_authenticate (3PAM),  pam_sm_authenticate (3PAM),  kadm5.acl (5),  pam.conf (5),  attributes (7),  pam_authtok_get (7),  pam_krb5 (7),  kadmind (8)