usr/src/man/man5/pam_krb5_migrate.5

   1 '\" te
   2 .\"  Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PAM_KRB5_MIGRATE 5 "Jul 29, 2004"
   7 .SH NAME
   8 pam_krb5_migrate \- authentication PAM module for the KerberosV5 auto-migration
   9 of users feature
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB/usr/lib/security/pam_krb5_migrate.so.1\fR
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The KerberosV5 auto-migrate service module for PAM provides functionality for
  20 the PAM authentication component. The service module helps in the automatic
  21 migration of \fBPAM_USER\fR to the client's local Kerberos realm, using
  22 \fBPAM_AUTHTOK\fR (the PAM authentication token associated with \fBPAM_USER\fR)
  23 as the new Kerberos principal's password.
  24 .SS "KerberosV5 Auto-migrate Authentication Module"
  25 .sp
  26 .LP
  27 The KerberosV5 auto-migrate authentication component provides the
  28 \fBpam_sm_authenticate\fR(3PAM) function to migrate a user who does not have a
  29 corresponding \fBkrb5\fR principal account to the default Kerberos realm of the
  30 client.
  31 .sp
  32 .LP
  33 \fBpam_sm_authenticate\fR(3PAM) uses a host-based client service principal,
  34 present in the local \fBkeytab\fR (\fB/etc/krb5/krb5.keytab\fR) to authenticate
  35 to \fBkadmind\fR(1M) (defaults to the \fBhost/nodename.fqdn\fR service
  36 principal), for the principal creation operation. Also, for successful creation
  37 of the \fBkrb5\fR user principal account, the host-based client service
  38 principal being used needs to be assigned the appropriate privilege on the
  39 master KDC's \fBkadm5.acl\fR(4) file. \fBkadmind\fR(1M) checks for the
  40 appropriate privilege and validates the user password using PAM by calling
  41 \fBpam_authenticate\fR(3PAM) and \fBpam_acct_mgmt\fR(3PAM) for the
  42 \fBk5migrate\fR service.
  43 .sp
  44 .LP
  45 If migration of the user to the KerberosV5 infrastructure is successful, the
  46 module will inform users about it by means of a \fBPAM_TEXT_INFO\fR message,
  47 unless instructed otherwise by the presence of the \fBquiet\fR option.
  48 .sp
  49 .LP
  50 The authentication component always returns \fBPAM_IGNORE\fR and is meant to be
  51 stacked in \fBpam.conf\fR with a requirement that it be listed below
  52 pam_authtok_get(5) in the authentication stack. Also, if \fBpam_krb5_migrate\fR
  53 is used in the authentication stack of a particular service, it is mandatory
  54 that \fBpam_krb5\fR(5) be listed in the PAM account stack of that service for
  55 proper operation (see EXAMPLES).
  56 .SH OPTIONS
  57 .sp
  58 .LP
  59 The following options can be passed to the KerberosV5 auto-migrate
  60 authentication module:
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBdebug\fR\fR
  65 .ad
  66 .sp .6
  67 .RS 4n
  68 Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBclient_service=\fR\fI<service name>\fR\fR
  75 .ad
  76 .sp .6
  77 .RS 4n
  78 Name of the service used to authenticate to \fBkadmind\fR(1M) defaults to
  79 \fBhost\fR. This means that the module uses \fBhost/\fR\fI<nodename.fqdn>\fR as
  80 its client service principal name, KerberosV5 user principal creation operation
  81 or \fI<service>\fR/\fI<nodename.fqdn>\fR if this option is provided.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBquiet\fR\fR
  88 .ad
  89 .sp .6
  90 .RS 4n
  91 Do not explain KerberosV5 migration to the user.
  92 .sp
  93 This has the same effect as passing the \fBPAM_SILENT\fR flag to
  94 \fBpam_sm_authenticate\fR(3PAM) and is useful where applications cannot handle
  95 \fBPAM_TEXT_INFO\fR messages.
  96 .sp
  97 If not set, the authentication component will issue a \fBPAM_TEXT_INFO\fR
  98 message after creation of the Kerberos V5 principal, indicating that it has
  99 done so.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBexpire_pw\fR\fR
 106 .ad
 107 .sp .6
 108 .RS 4n
 109 Causes the creation of KerberosV5 user principals with password expiration set
 110 to \fBnow\fR (current time).
 111 .RE
 112
 113 .SH EXAMPLES
 114 .LP
 115 \fBExample 1 \fRSample Entries from \fBpam.conf\fR
 116 .sp
 117 .LP
 118 The following entries from \fBpam.conf\fR(4) demonstrate the use of the
 119 \fBpam_krb5_migrate.so.1\fR module:
 120
 121 .sp
 122 .in +2
 123 .nf
 124 login       auth requisite          pam_authtok_get.so.1
 125 login       auth required           pam_dhkeys.so.1
 126 login       auth required           pam_unix_cred.so.1
 127 login       auth sufficient         pam_krb5.so.1
 128 login       auth requisite          pam_unix_auth.so.1
 129 login       auth optional           pam_krb5_migrate.so.1 expire_pw
 130 login       auth required           pam_dial_auth.so.1
 131
 132 other   account requisite       pam_roles.so.1
 133 other   account required        pam_krb5.so.1
 134 other   account required        pam_unix_account.so.1
 135 .fi
 136 .in -2
 137
 138 .sp
 139 .LP
 140 The \fBpam_krb5_migrate\fR module can generally be present on the
 141 authentication stack of any service where the application calls
 142 \fBpam_sm_authenticate\fR(3PAM) and an authentication token (in the preceding
 143 example, the authentication token would be the user's Unix password) is
 144 available for use as a Kerberos V5 password.
 145
 146 .LP
 147 \fBExample 2 \fRSample Entries from \fBkadm5.acl\fR
 148 .sp
 149 .LP
 150 The following entries from \fBkadm5.acl\fR(4) permit or deny privileges to the
 151 host client service principal:
 152
 153 .sp
 154 .in +2
 155 .nf
 156 host/*@ACME.COM U root
 157 host/*@ACME.COM ui *
 158 .fi
 159 .in -2
 160
 161 .sp
 162 .LP
 163 The preceding entries permit the \fBpam_krb5_migrate\fR \fBadd\fR privilege to
 164 the host client service principal of any machine in the \fBACME.COM\fR
 165 KerberosV5 realm, but denies the \fBadd\fR privilege to all host service
 166 principals for addition of the root user account.
 167
 168 .LP
 169 \fBExample 3 \fRSample Entries in \fBpam.conf\fR of the Master KDC
 170 .sp
 171 .LP
 172 The entries below enable \fBkadmind\fR(1M) on the master KDC to use the
 173 \fBk5migrate\fR PAM service in order to validate Unix user passwords for
 174 accounts that require migration to the Kerberos realm.
 175
 176 .sp
 177 .in +2
 178 .nf
 179 k5migrate        auth    required        pam_unix_auth.so.1
 180 k5migrate        account required        pam_unix_account.so.1
 181 .fi
 182 .in -2
 183
 184 .SH ATTRIBUTES
 185 .sp
 186 .LP
 187 See \fBattributes\fR(5) for a description of the following attribute:
 188 .sp
 189
 190 .sp
 191 .TS
 192 box;
 193 c | c
 194 l | l .
 195 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 196 _
 197 Interface Stability     Evolving
 198 .TE
 199
 200 .SH SEE ALSO
 201 .sp
 202 .LP
 203 \fBkadmind\fR(1M), \fBsyslog\fR(3C), \fBpam_authenticate\fR(3PAM),
 204 \fBpam_acct_mgmt\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), \fBkadm5.acl\fR(4),
 205 \fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_get\fR(5),
 206 \fBpam_krb5\fR(5)