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

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