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

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