git.sur5r.net Git - openldap/blob - contrib/slapd-modules/nssov/slapo-nssov.5

   1 .TH SLAPO-NSSOV 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 1998-2013 The OpenLDAP Foundation, All Rights Reserved.
   3 .\" Copying restrictions apply.  See the COPYRIGHT file.
   4 .\" $OpenLDAP$
   5 .SH NAME
   6 slapo-nssov \- NSS and PAM requests through a local Unix Domain socket
   7 .SH SYNOPSIS
   8 ETCDIR/slapd.conf
   9 .SH DESCRIPTION
  10 The
  11 .B nssov
  12 overlay to
  13 .BR slapd (8)
  14 services NSS and PAM requests through a local Unix Domain socket.
  15 It uses the same IPC protocol as Arthur de Jong's nss-ldapd, and
  16 a complete copy of the nss-ldapd source is included along with the
  17 nssov source code.
  18 .LP
  19 Using a separate IPC protocol for NSS and PAM requests eliminates the
  20 libldap dependencies/clashes that the current pam_ldap/nss_ldap solutions
  21 all suffer from. Both the original nss-ldapd and this nssov solution
  22 are free from these library issues.
  23 .LP
  24 Unlike nss-pam-ldapd, since this overlay executes inside slapd it allows for
  25 the possibility of sophisticated caching, without any of the weaknesses of
  26 nscd and other related caching solutions. E.g., a remote LDAP database can
  27 be accessed using back-ldap with proxy caching (see
  28 .BR slapd-ldap (5)
  29 and
  30 .BR slapo-pcache (5)
  31 ) to leverage back-ldap's
  32 connection pooling as well as pcache's persistent caching, to provide
  33 high performance and a measure of support for disconnected operation.
  34 Alternatively, cache considerations can be completely eliminated by running
  35 a regular database with syncrepl to maintain synchronization with a remote
  36 LDAP database.
  37 .LP
  38 Another major benefit of nssov is that it allows all security policy to be
  39 administered centrally via LDAP, instead of having fragile rules scattered
  40 across multiple flat files. As such, there is no client-side configuration at
  41 all for the NSS/PAM stub libraries. (The stubs talk to the server via a Unix
  42 domain socket whose path is hardcoded to NSLCDPATH). As a side benefit,
  43 this can finally eliminate the perpetual confusion between OpenLDAP's
  44 ldap.conf file in ETCDIR/ldap.conf and the similarly named files typically
  45 used by pam_ldap and nss_ldap.
  46 .LP
  47 User authentication is performed by internal simple Binds. User authorization
  48 leverages the slapd ACL engine, which offers much more power and flexibility
  49 than the simple group/hostname checks in the old pam_ldap code.
  50 .LP
  51 You will need to include the nis.schema in your slapd configuration
  52 for RFC2307 support. If you wish to use RFC2307bis you will need a slightly
  53 different schema. You will also need the ldapns.schema for PAM authorization
  54 management.
  55 .LP
  56 You must select
  57 .B ldap
  58 in the appropriate services in
  59 .I /etc/nsswitch.conf
  60 in order for these NSS features to take effect. Likewise, you must
  61 enable
  62 .B pam_ldap
  63 for the authenticate, account, session, and password services in
  64 .I /etc/pam.conf
  65 or
  66 .I /etc/pam.d
  67 for these PAM features to take effect.
  68
  69 .TP
  70 .B overlay nssov
  71 This directive adds the nssov overlay to the current backend.
  72 .TP
  73 .B nssov-ssd <service> <url>
  74 This directive configures a Service Search Descriptor (SSD) for each NSS
  75 service that will be used.  The <service> may be one of
  76 .RS
  77 .nf
  78     aliases
  79     ethers
  80     group
  81     hosts
  82     netgroup
  83     networks
  84     passwd
  85     protocols
  86     rpc
  87     services
  88     shadow
  89 .fi
  90 .RE
  91 and the <url> must be of the form
  92 .RS
  93 .TP
  94 .B ldap:///[<basedn>][??[<scope>][?<filter>]]
  95 .RE
  96 The
  97 .B <basedn>
  98 will default to the first suffix of the current database.
  99 The
 100 .B <scope>
 101 defaults to "subtree". The default
 102 .B <filter>
 103 depends on which service is being used.
 104 .TP
 105 .B nssov-map <service> <orig> <new>
 106 If the local database is actually a proxy to a foreign LDAP server, some
 107 mapping of schema may be needed. This directive allows some simple attribute
 108 substitutions to be performed. See the
 109 .B nss-ldapd/README
 110 for the original attribute names used in this code.
 111 .TP
 112 .B nssov-pam <option> [...]
 113 This directive determines a number of PAM behaviors. Multiple options may
 114 be used at once, and available levels are:
 115 .RS
 116 .RS
 117 .PD 0
 118 .TP
 119 .B userhost
 120 check host attribute in user entry for authorization
 121 .TP
 122 .B userservice
 123 check authorizedService attribute in user entry for authorization
 124 .TP
 125 .B usergroup
 126 check that user is a member of specific group for authorization
 127 .TP
 128 .B hostservice
 129 check authorizedService attribute in host entry for authorization
 130 .TP
 131 .B authz2dn
 132 use authz-regexp mapping to map uid to LDAP DN
 133 .TP
 134 .B uid2dn
 135 use NSS passwd SSD to map uid to LDAP DN
 136 .PD
 137 .RE
 138
 139 Setting the
 140 .BR userhost ,
 141 .BR userservice ,
 142 and
 143 .B usergroup
 144 options duplicates the original pam_ldap authorization behavior.
 145
 146 The recommended approach is to use
 147 .B hostservice
 148 instead. In this case, ipHost entries must be created for all hosts
 149 being managed, and they must also have the authorizedServiceObject
 150 class to allow authorizedService attributes to be used. Also the
 151 NSS host SSD must be configured so that ipHost entries can be found.
 152 Authorization is checked by performing an LDAP Compare operation
 153 looking for the PAM service name in the authorizedService attribute.
 154 .B slapd
 155 ACLs should be set to grant or deny
 156 .B Compare
 157 privilege to the appropriate users or groups as desired.
 158
 159 If the
 160 .B authz2dn
 161 option is set then authz-regexp mappings will be used to map the
 162 PAM username to an LDAP DN. The authentication DN will be of the
 163 form
 164 .RS
 165 .B cn=<service>+uid=<user>,cn=<hostname>,cn=pam,cn=auth
 166 .RE
 167
 168 If no mapping is found for this authentication DN, then this
 169 mapping will be ignored.
 170
 171 If the
 172 .B uid2dn
 173 option is set then the NSS passwd SSD will be used to map the
 174 PAM username to an LDAP DN. The passwd SSD must have already been
 175 configured for this mapping to succeed.
 176
 177 If neither the authz2dn nor the uid2dn mapping succeeds, the module
 178 will return a PAM_USER_UNKNOWN failure code. If both options are set,
 179 the authz mapping is attempted first; if it succeeds the uid2dn mapping
 180 will be skipped.
 181
 182 By default only the
 183 .B uid2dn
 184 option is set.
 185 .RE
 186 .TP
 187 .B nssov-pam-defhost <hostname>
 188 Specify a default hostname to check if an ipHost entry for the current
 189 hostname cannot be found. This setting is only relevant if the
 190 .B hostservice
 191 option has been set.
 192 .TP
 193 .B nssov-pam-group-dn <DN>
 194 Specify the DN of an LDAP group to check for authorization. The LDAP user
 195 must be a member of this group for the login to be allowed. There is no
 196 default value. This setting is only relevant if the
 197 .B usergroup
 198 option has been set.
 199 .TP
 200 .B nssov-pam-group-ad <attribute>
 201 Specify the attribute to use for group membership checks.
 202 There is no default value.  This setting is only relevant if the
 203 .B usergroup
 204 option has been set.
 205 .TP
 206 .B nssov-pam-min-uid <integer>
 207 Specify a minimum uid that is allowed to login. Users with a uidNumber
 208 lower than this value will be denied access. The default is zero, which
 209 disables this setting.
 210 .TP
 211 .B nssov-pam-max-uid <integer>
 212 Specify a maximum uid that is allowed to login. Users with a uidNumber
 213 higher than this value will be denied access. The default is zero, which
 214 disables this setting.
 215 .TP
 216 .B nssov-pam-template-ad <attribute>
 217 Specify an attribute to check in a user's entry for a template login name.
 218 The template login feature is used by FreeBSD's PAM framework. It can be
 219 viewed as a form of proxying, where a user can authenticate with one
 220 username/password pair, but is assigned the identity and credentials of
 221 the template user. This setting is disabled by default.
 222 .TP
 223 .B nssov-pam-template <name>
 224 Specify a default username to be used if no template attribute is found
 225 in the user's entry. The
 226 .B nssov-pam-template-ad
 227 directive must be configured for this setting to have any effect.
 228 .TP
 229 .B nssov-pam-session <service>
 230 Specify a PAM service name whose sessions will be recorded. For the
 231 configured services, logins will be recorded in the
 232 .TP
 233 .B nssov-pam-password-prohibit-message <message>
 234 Diable password change service and return the specified message to
 235 users.
 236 .TP
 237 .B nssov-pam-pwdmgr-dn <dn>
 238 Specify the dn of the password manager.
 239 .TP
 240 .B nssov-pam-pwdmgr-pwd <pwd>
 241 Specify the pwd of the password manager.
 242 .TP
 243 .B loginStatus
 244 operational attribute of the user's entry. The attribute's values are
 245 of the form
 246 .RS
 247 .RS
 248 .B <generalizedTime> <host> <service> <tty> (<ruser@rhost>)
 249 .RE
 250 .RE
 251 Upon logout the corresponding value will be deleted. This feature allows
 252 a single LDAP Search to be used to check which users are logged in across
 253 all the hosts of a network. The rootdn of the database is used to perform
 254 the updates of the loginStatus attribute, so a rootdn must already be
 255 configured for this feature to work. By default no services are configured.
 256 .LP
 257 The PAM functions support LDAP Password Policy as well. If the password
 258 policy overlay is in use (see
 259 .BR slapo-ppolicy (5)),
 260 policy
 261 information (e.g. password expiration, password quality, etc.)
 262 may be returned to the PAM client as a result of authentication,
 263 account management, and password modification requests.
 264
 265 The overlay also supports dynamic configuration in cn=config. An example
 266 of the config entry is
 267 .LP
 268 .RS
 269 .nf
 270     dn: olcOverlay={0}nssov,ocDatabase={1}hdb,cn=config
 271     objectClass: olcOverlayConfig
 272     objectClass: olcNssOvConfig
 273     olcOverlay: {0}nssov
 274     olcNssSsd: passwd ldap:///ou=users,dc=example,dc=com??one
 275     olcNssMap: passwd uid accountName
 276     olcNssPam: hostservice uid2dn
 277     olcNssPamDefHost: defaulthost
 278     olcNssPamMinUid: 500
 279     olcNssPamMaxUid: 32000
 280     olcNssPamSession: login
 281     olcNssPamSession: sshd
 282 .fi
 283 .RE
 284 .LP
 285 which enables the passwd service, and uses the accountName attribute to
 286 fetch what is usually retrieved from the uid attribute. It also enables
 287 some PAM authorization controls, and specifies that the PAM
 288 .B login
 289 and
 290 .B sshd
 291 services should have their logins recorded.
 292 .SH FILES
 293 .TP
 294 ETCDIR/slapd.conf
 295 default slapd configuration file
 296 .SH SEE ALSO
 297 .BR slapd.conf (5),
 298 .BR slapd\-config (5),
 299 .BR slapd\-ldap (5),
 300 .BR slapo\-pcache (5),
 301 .BR slapo\-ppolicy (5),
 302 .BR slapd (8).
 303 .SH AUTHOR
 304 Howard Chu, inspired by nss-ldapd by Arthur de Jong and pam_ldap by Luke Howard
 305 Enhancements by Ted C. Cheng, Symas Corp.