usr/src/man/man5/pam_ldap.5

   1 '\" te
   2 .\" Copyright (C) 2005, 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_LDAP 5 "Dec 21, 2005"
   7 .SH NAME
   8 pam_ldap \- authentication and account management PAM module for LDAP
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/lib/security/pam_ldap.so.1\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .LP
  17 The \fBpam_ldap\fR module implements \fBpam_sm_authenticate\fR(3PAM) and
  18 \fBpam_sm_acct_mgmt\fR(3PAM), the functions that provide functionality for the
  19 PAM authentication and account management stacks. The \fBpam_ldap\fR module
  20 ties the authentication and account management functionality to the
  21 functionality of the supporting LDAP server. For authentication, \fBpam_ldap\fR
  22 can authenticate the user directly to any LDAP directory server by using any
  23 supported authentication mechanism, such as \fBDIGEST-MD5\fR. However, the
  24 account management component of \fBpam_ldap\fR will work only with the Sun Java
  25 System Directory Server. The server's user account management must be properly
  26 configured before it can be used by \fBpam_ldap\fR. Refer to the \fISun Java
  27 System Directory Server Administration Guide\fR for information on how to
  28 configure user account management, including password and account lockout
  29 policy.
  30 .sp
  31 .LP
  32 \fBpam_ldap\fR must be used in conjunction with the modules that support the
  33 UNIX authentication, password, and account management, which are
  34 \fBpam_authtok_get\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5),
  35 and \fBpam_unix_auth\fR(5). \fBpam_ldap\fR is designed to be stacked directly
  36 below these modules. If other modules are designed to be stacked in this
  37 manner, the modules can be stacked below the \fBpam_ldap\fR module. The
  38 Examples section shows how the UNIX modules are stacked with \fBpam_ldap\fR.
  39 When stacked together, the UNIX modules are used to control local accounts,
  40 such as \fBroot\fR. \fBpam_ldap\fR is used to control network accounts, that
  41 is, LDAP users. For the stacks to work, \fBpam_unix_auth\fR,
  42 \fBpam_unix_account\fR, and \fBpam_passwd_auth\fR must be configured with the
  43 \fBbinding\fR control flag and the \fBserver_policy\fR option. This
  44 configuration allows local account override of a network account.
  45 .SS "LDAP Authentication Module"
  46 .LP
  47 The LDAP authentication module verifies the identity of a user. The
  48 \fBpam_sm_authenticate\fR(3PAM) function uses the password entered by the user
  49 to attempt to authenticate to the LDAP server. If successful, the user is
  50 authenticated. See NOTES for information on password prompting.
  51 .sp
  52 .LP
  53 The authentication method used is either defined in the client profile , or the
  54 authentication method is configured by using the \fBldapclient\fR(1M) command.
  55 To determine the authentication method to use, this module first attempts to
  56 use the authentication method that is defined, for service \fBpam_ldap\fR, for
  57 example, \fBserviceAuthenticationMethod:pam_ldap:sasl/DIGEST-MD5\fR. If no
  58 authentication method is defined, \fBpam_ldap\fR uses the default
  59 authentication method. If neither are set, the authentication fails. This
  60 module skips the configured authentication method if the authentication method
  61 is set to \fBnone\fR.
  62 .sp
  63 .LP
  64 The following options can be passed to the LDAP service module:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBdebug\fR\fR
  69 .ad
  70 .RS 10n
  71 \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBnowarn\fR\fR
  78 .ad
  79 .RS 10n
  80 Turn off warning messages.
  81 .RE
  82
  83 .sp
  84 .LP
  85 These options are case sensitive and must be used exactly as presented here.
  86 .SS "LDAP Account Management Module"
  87 .LP
  88 The LDAP account management module validates the user's account. The
  89 \fBpam_sm_acct_mgmt\fR(3PAM) function authenticates to the LDAP server to
  90 verify that the user's password has not expired, or that the user's account has
  91 not been locked. In the event that there is no user authentication token
  92 (\fBPAM_AUTHTOK\fR) available, the \fBpam_sm_acct_mgmt\fR(3PAM) function
  93 attempts to retrieve the user's account status without authenticating to the
  94 LDAP server as the user logging in. This procedure will succeed only if the
  95 LDAP server is Sun Java System Directory server 5.2 patch 4 or newer. The
  96 following options can be passed to the LDAP service module:
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBdebug\fR\fR
 101 .ad
 102 .RS 10n
 103 \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBnowarn\fR\fR
 110 .ad
 111 .RS 10n
 112 Turn off warning messages.
 113 .RE
 114
 115 .sp
 116 .LP
 117 These options are case sensitive, and the options must be used exactly as
 118 presented here.
 119 .SS "LDAP Password Management Module"
 120 .LP
 121 LDAP password management is no longer supported by \fBpam_ldap\fR. Use
 122 \fBpam_authtok_store\fR(5) instead of \fBpam_ldap\fR for password change.
 123 \fBpam_authtok_store\fR(5) handles both the local and LDAP accounts and updates
 124 the passwords in all the repositories configured by \fBnsswitch.conf\fR(4).
 125 .SH ERRORS
 126 .LP
 127 The authentication service returns the following error codes:
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBPAM_SUCCESS\fR\fR
 132 .ad
 133 .RS 20n
 134 The authentication was successful.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBPAM_MAXTRIES\fR\fR
 141 .ad
 142 .RS 20n
 143 The maximum number of authentication attempts was exceeded.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBPAM_AUTH_ERR\fR\fR
 150 .ad
 151 .RS 20n
 152 The authentication failed.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBPAM_USER_UNKNOWN\fR\fR
 159 .ad
 160 .RS 20n
 161 No account is present for the user.
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBPAM_BUF_ERR\fR\fR
 168 .ad
 169 .RS 20n
 170 A memory buffer error occurred.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBPAM_SYSTEM_ERR\fR\fR
 177 .ad
 178 .RS 20n
 179 A system error occurred.
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .na
 185 \fB\fBPAM_IGNORE\fR\fR
 186 .ad
 187 .RS 20n
 188 The user's account was inactivated.
 189 .RE
 190
 191 .sp
 192 .LP
 193 The account management service returns the following error codes:
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fBPAM_SUCCESS\fR\fR
 198 .ad
 199 .RS 24n
 200 The user was allowed access to the account.
 201 .RE
 202
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR
 207 .ad
 208 .RS 24n
 209 A new authentication token is required.
 210 .RE
 211
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBPAM_ACCT_EXPIRED\fR\fR
 216 .ad
 217 .RS 24n
 218 The user account has expired.
 219 .RE
 220
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBPAM_PERM_DENIED\fR\fR
 225 .ad
 226 .RS 24n
 227 The user was denied access to the account at this time.
 228 .RE
 229
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBPAM_USER_UNKNOWN\fR\fR
 234 .ad
 235 .RS 24n
 236 No account is present for the user.
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fBPAM_BUF_ERROR\fR\fR
 243 .ad
 244 .RS 24n
 245 A memory buffer error occurred.
 246 .RE
 247
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fBPAM_SYSTEM_ERR\fR\fR
 252 .ad
 253 .RS 24n
 254 A system error occurred.
 255 .RE
 256
 257 .SH EXAMPLES
 258 .LP
 259 \fBExample 1 \fRUsing \fBpam_ldap\fR With Authentication\fB\fR
 260 .sp
 261 .LP
 262 The following is a configuration for the login service when using
 263 \fBpam_ldap\fR. The service name \fBlogin\fR can be substituted for any other
 264 authentication service such as \fBdtlogin\fR or \fBsu\fR. Lines that begin with
 265 the # symbol are comments and are ignored.
 266
 267 .sp
 268 .in +2
 269 .nf
 270 # Authentication management for login service is stacked.
 271 # If pam_unix_auth succeeds, pam_ldap is not invoked.
 272 # The control flag "binding" provides a local overriding
 273 # remote (LDAP) control. The "server_policy" option is used
 274 # to tell pam_unix_auth.so.1 to ignore the LDAP users.
 275
 276 login   auth requisite  pam_authtok_get.so.1
 277 login   auth required   pam_dhkeys.so.1
 278 login   auth required   pam_unix_cred.so.1
 279 login   auth binding    pam_unix_auth.so.1 server_policy
 280 login   auth required   pam_ldap.so.1
 281 .fi
 282 .in -2
 283
 284 .LP
 285 \fBExample 2 \fRUsing \fBpam_ldap\fR With Account Management
 286 .sp
 287 .LP
 288 The following is a configuration for account management when using
 289 \fBpam_ldap\fR. Lines that begin with the # symbol are comments and are
 290 ignored.
 291
 292 .sp
 293 .in +2
 294 .nf
 295 # Account management for all services is stacked
 296 # If pam_unix_account succeeds, pam_ldap is not invoked.
 297 # The control flag "binding" provides a local overriding
 298 # remote (LDAP) control. The "server_policy" option is used
 299 # to tell pam_unix_account.so.1 to ignore the LDAP users.
 300
 301 other   account  requisite      pam_roles.so.1
 302 other   account  binding        pam_unix_account.so.1 server_policy
 303 other   account  required       pam_ldap.so.1
 304 .fi
 305 .in -2
 306
 307 .LP
 308 \fBExample 3 \fRUsing \fBpam_authtok_store\fR With Password Management For Both
 309 Local and LDAP Accounts
 310 .sp
 311 .LP
 312 The following is a configuration for password management when using
 313 \fBpam_authtok_store\fR. Lines that begin with the # symbol are comments and
 314 are ignored.
 315
 316 .sp
 317 .in +2
 318 .nf
 319 # Password management (authentication)
 320 # The control flag "binding" provides a local overriding
 321 # remote (LDAP) control. The server_policy option is used
 322 # to tell pam_passwd_auth.so.1 to ignore the LDAP users.
 323
 324 passwd  auth binding  pam_passwd_auth.so.1 server_policy
 325 passwd  auth required pam_ldap.so.1
 326
 327 # Password management (updates)
 328 # This updates passwords stored both in the local /etc
 329 # files and in the LDAP directory. The "server_policy"
 330 # option is used to tell pam_authtok_store to
 331 # follow the LDAP server's policy when updating
 332 # passwords stored in the LDAP directory
 333
 334 other password required   pam_dhkeys.so.1
 335 other password requisite  pam_authtok_get.so.1
 336 other password requisite  pam_authtok_check.so.1
 337 other password required   pam_authtok_store.so.1 server_policy
 338 .fi
 339 .in -2
 340
 341 .SH FILES
 342 .ne 2
 343 .na
 344 \fB\fB/var/ldap/ldap_client_file\fR\fR
 345 .ad
 346 .br
 347 .na
 348 \fB\fB/var/ldap/ldap_client_cred\fR\fR
 349 .ad
 350 .RS 30n
 351 The LDAP configuration files of the client. Do not manually modify these files,
 352 as these files might not be human readable. Use \fBldapclient\fR(1M) to update
 353 these files.
 354 .RE
 355
 356 .sp
 357 .ne 2
 358 .na
 359 \fB\fB/etc/pam.conf\fR\fR
 360 .ad
 361 .RS 30n
 362 PAM configuration file.
 363 .RE
 364
 365 .SH ATTRIBUTES
 366 .LP
 367 See \fBattributes\fR(5) for descriptions of the following attributes:
 368 .sp
 369
 370 .sp
 371 .TS
 372 box;
 373 c | c
 374 l | l .
 375 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 376 _
 377 Interface Stability     Evolving
 378 _
 379 MT-Level        MT-Safe with exceptions
 380 .TE
 381
 382 .SH SEE ALSO
 383 .LP
 384 \fBldap\fR(1), \fBidsconfig\fR(1M), \fBldap_cachemgr\fR(1M),
 385 \fBldapclient\fR(1M), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM),
 386 \fBpam_sm_acct_mgmt\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM),
 387 \fBpam_sm_chauthtok\fR(3PAM), \fBpam_sm_close_session\fR(3PAM),
 388 \fBpam_sm_open_session\fR(3PAM), \fBpam_sm_setcred\fR(3PAM), \fBsyslog\fR(3C),
 389 \fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5),
 390 \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_passwd_auth\fR(5),
 391 \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5)
 392 .SH NOTES
 393 .LP
 394 The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
 395 multi-threaded application uses its own \fBPAM\fR handle.
 396 .sp
 397 .LP
 398 The previously supported \fBuse_first_pass\fR and \fBtry_first_pass\fR options
 399 are obsolete in this version, are no longer needed, can safely be removed from
 400 \fBpam.conf\fR(4), and are silently ignored. They might be removed in a future
 401 release. Password prompting must be provided for by stacking
 402 \fBpam_authtok_get\fR(5) before \fBpam_ldap\fR in the \fBauth\fR and
 403 \fBpassword\fR module stacks and \fBpam_passwd_auth\fR(5) in the \fBpasswd\fR
 404 service \fBauth\fR stack (as described in the EXAMPLES section). The previously
 405 supported password update function is replaced in this release by the
 406 previously recommended use of \fBpam_authtok_store\fR with the
 407 \fBserver_policy\fR option (as described in the EXAMPLES section).
 408 .sp
 409 .LP
 410 The functions: \fBpam_sm_setcred\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM),
 411 \fBpam_sm_open_session\fR(3PAM), and \fBpam_sm_close_session\fR(3PAM) do
 412 nothing and return \fBPAM_IGNORE\fR in \fBpam_ldap\fR.