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

   1 .TH SLAPO-NSSOV 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 1998-2011 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 /var/run/nslcd/). 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 To use this code, you will need the client-side stuf library from
  52 nss-pam-ldapd.  You can get it from:
  53 http://arthurdejong.org/nss-pam-ldapd
  54 You will not need the nslcd daemon; this overlay replaces that part.
  55 To disable building of the nslcd daemon in nss-pam-ldapd, add the
  56 --disable-nslcd option to the nss-pam-ldapd configure script. You
  57 should already be familiar with the RFC2307 and RFC2307bis schema
  58 to use this overlay.  See the nss-pam-ldapd README for more information
  59 on the schema and which features are supported.
  60 .LP
  61 You will also need to include the nis.schema in your slapd configuration
  62 for RFC2307 support. If you wish to use RFC2307bis you will need a slightly
  63 different schema. You will also need the ldapns.schema for PAM authorization
  64 management.
  65 .LP
  66 You must select
  67 .B ldap
  68 in the appropriate services in
  69 .I /etc/nsswitch.conf
  70 in order for these NSS features to take effect. Likewise, you must
  71 enable
  72 .B pam_ldap
  73 for the authenticate, account, session, and password services in
  74 .I /etc/pam.conf
  75 or
  76 .I /etc/pam.d
  77 for these PAM features to take effect.
  78
  79 .TP
  80 .B overlay nssov
  81 This directive adds the nssov overlay to the current backend.
  82 .TP
  83 .B nssov-ssd <service> <url>
  84 This directive configures a Service Search Descriptor (SSD) for each NSS
  85 service that will be used.  The <service> may be one of
  86 .RS
  87 .nf
  88     aliases
  89     ethers
  90     group
  91     hosts
  92     netgroup
  93     networks
  94     passwd
  95     protocols
  96     rpc
  97     services
  98     shadow
  99 .fi
 100 .RE
 101 and the <url> must be of the form
 102 .RS
 103 .TP
 104 .B ldap:///[<basedn>][??[<scope>][?<filter>]]
 105 .RE
 106 The
 107 .B <basedn>
 108 will default to the first suffix of the current database.
 109 The
 110 .B <scope>
 111 defaults to "subtree". The default
 112 .B <filter>
 113 depends on which service is being used.
 114 .TP
 115 .B nssov-map <service> <orig> <new>
 116 If the local database is actually a proxy to a foreign LDAP server, some
 117 mapping of schema may be needed. This directive allows some simple attribute
 118 substitutions to be performed. See the
 119 .B nss-ldapd/README
 120 for the original attribute names used in this code.
 121 .TP
 122 .B nssov-pam <option> [...]
 123 This directive determines a number of PAM behaviors. Multiple options may
 124 be used at once, and available levels are:
 125 .RS
 126 .RS
 127 .PD 0
 128 .TP
 129 .B userhost
 130 check host attribute in user entry for authorization
 131 .TP
 132 .B userservice
 133 check authorizedService attribute in user entry for authorization
 134 .TP
 135 .B usergroup
 136 check that user is a member of specific group for authorization
 137 .TP
 138 .B hostservice
 139 check authorizedService attribute in host entry for authorization
 140 .TP
 141 .B authz2dn
 142 use authz-regexp mapping to map uid to LDAP DN
 143 .TP
 144 .B uid2dn
 145 use NSS passwd SSD to map uid to LDAP DN
 146 .PD
 147 .RE
 148
 149 Setting the
 150 .BR userhost ,
 151 .BR userservice ,
 152 and
 153 .B usergroup
 154 options duplicates the original pam_ldap authorization behavior.
 155
 156 The recommended approach is to use
 157 .B hostservice
 158 instead. In this case, ipHost entries must be created for all hosts
 159 being managed, and they must also have the authorizedServiceObject
 160 class to allow authorizedService attributes to be used. Also the
 161 NSS host SSD must be configured so that ipHost entries can be found.
 162 Authorization is checked by performing an LDAP Compare operation
 163 looking for the PAM service name in the authorizedService attribute.
 164 .B slapd
 165 ACLs should be set to grant or deny
 166 .B Compare
 167 privilege to the appropriate users or groups as desired.
 168
 169 If the
 170 .B authz2dn
 171 option is set then authz-regexp mappings will be used to map the
 172 PAM username to an LDAP DN. The authentication DN will be of the
 173 form
 174 .RS
 175 .B cn=<service>+uid=<user>,cn=<hostname>,cn=pam,cn=auth
 176 .RE
 177
 178 If no mapping is found for this authentication DN, then this
 179 mapping will be ignored.
 180
 181 If the
 182 .B uid2dn
 183 option is set then the NSS passwd SSD will be used to map the
 184 PAM username to an LDAP DN. The passwd SSD must have already been
 185 configured for this mapping to succeed.
 186
 187 If neither the authz2dn nor the uid2dn mapping succeeds, the module
 188 will return a PAM_USER_UNKNOWN failure code. If both options are set,
 189 the authz mapping is attempted first; if it succeeds the uid2dn mapping
 190 will be skipped.
 191
 192 By default only the
 193 .B uid2dn
 194 option is set.
 195 .RE
 196 .TP
 197 .B nssov-pam-defhost <hostname>
 198 Specify a default hostname to check if an ipHost entry for the current
 199 hostname cannot be found. This setting is only relevant if the
 200 .B hostservice
 201 option has been set.
 202 .TP
 203 .B nssov-pam-group-dn <DN>
 204 Specify the DN of an LDAP group to check for authorization. The LDAP user
 205 must be a member of this group for the login to be allowed. There is no
 206 default value. This setting is only relevant if the
 207 .B usergroup
 208 option has been set.
 209 .TP
 210 .B nssov-pam-group-ad <attribute>
 211 Specify the attribute to use for group membership checks.
 212 There is no default value.  This setting is only relevant if the
 213 .B usergroup
 214 option has been set.
 215 .TP
 216 .B nssov-pam-minuid <integer>
 217 Specify a minimum uid that is allowed to login. Users with a uidNumber
 218 lower than this value will be denied access. The default is zero, which
 219 disables this setting.
 220 .TP
 221 .B nssov-pam-maxuid <integer>
 222 Specify a maximum uid that is allowed to login. Users with a uidNumber
 223 higher than this value will be denied access. The default is zero, which
 224 disables this setting.
 225 .TP
 226 .B nssov-pam-template-ad <attribute>
 227 Specify an attribute to check in a user's entry for a template login name.
 228 The template login feature is used by FreeBSD's PAM framework. It can be
 229 viewed as a form of proxying, where a user can authenticate with one
 230 username/password pair, but is assigned the identity and credentials of
 231 the template user. This setting is disabled by default.
 232 .TP
 233 .B nssov-pam-template <name>
 234 Specify a default username to be used if no template attribute is found
 235 in the user's entry. The
 236 .B nssov-pam-template-ad
 237 directive must be configured for this setting to have any effect.
 238 .TP
 239 .B nssov-pam-session <service>
 240 Specify a PAM service name whose sessions will be recorded. For the
 241 configured services, logins will be recorded in the
 242 .B loginStatus
 243 operational attribute of the user's entry. The attribute's values are
 244 of the form
 245 .RS
 246 .RS
 247 .B <generalizedTime> <host> <service> <tty> (<ruser@rhost>)
 248 .RE
 249 .RE
 250 Upon logout the corresponding value will be deleted. This feature allows
 251 a single LDAP Search to be used to check which users are logged in across
 252 all the hosts of a network. The rootdn of the database is used to perform
 253 the updates of the loginStatus attribute, so a rootdn must already be
 254 configured for this feature to work. By default no services are configured.
 255 .LP
 256 The PAM functions support LDAP Password Policy as well. If the password
 257 policy overlay is in use (see
 258 .BR slapo-ppolicy (5)),
 259 policy
 260 information (e.g. password expiration, password quality, etc.)
 261 may be returned to the PAM client as a result of authentication,
 262 account management, and password modification requests.
 263
 264 The overlay also supports dynamic configuration in cn=config. An example
 265 of the config entry is
 266 .LP
 267 .RS
 268 .nf
 269     dn: olcOverlay={0}nssov,ocDatabase={1}hdb,cn=config
 270     objectClass: olcOverlayConfig
 271     objectClass: olcNssOvConfig
 272     olcOverlay: {0}nssov
 273     olcNssSsd: passwd ldap:///ou=users,dc=example,dc=com??one
 274     olcNssMap: passwd uid accountName
 275     olcNssPam: hostservice uid2dn
 276     olcNssPamDefHost: defaulthost
 277     olcNssPamMinUid: 500
 278     olcNssPamMaxUid: 32000
 279     olcNssPamSession: login
 280     olcNssPamSession: sshd
 281 .fi
 282 .RE
 283 .LP
 284 which enables the passwd service, and uses the accountName attribute to
 285 fetch what is usually retrieved from the uid attribute. It also enables
 286 some PAM authorization controls, and specifies that the PAM
 287 .B login
 288 and
 289 .B sshd
 290 services should have their logins recorded.
 291 .SH FILES
 292 .TP
 293 ETCDIR/slapd.conf
 294 default slapd configuration file
 295 .SH SEE ALSO
 296 .BR slapd.conf (5),
 297 .BR slapd\-config (5),
 298 .BR slapd\-ldap (5),
 299 .BR slapo\-pcache (5),
 300 .BR slapo\-ppolicy (5),
 301 .BR slapd (8).
 302 .SH AUTHOR
 303 Howard Chu, inspired by nss-ldapd by Arthur de Jong and pam_ldap by Luke Howard