docs/docbook/projdoc/Samba-LDAP-HOWTO.sgml

   1 <chapter id="samba-ldap-howto">
   2
   3
   4 <chapterinfo>
   5         <author>
   6                 <firstname>Gerald (Jerry)></firstname><surname>Carter></surname>
   7                 <affiliation>
   8                         <orgname>Samba Team</orgname>
   9                         <address><email>jerry@samba.org</email></address>
  10                 </affiliation>
  11         </author>
  12
  13
  14         <pubdate> (29 Dec 2001) </pubdate>
  15 </chapterinfo>
  16
  17 <title>Storing Samba's User/Machine Account information in an LDAP Directory</title>
  18
  19 <sect1>
  20 <title>Purpose</title>
  21
  22 <para>
  23 This document describes how to use an LDAP directory for storing Samba user
  24 account information normally stored in the smbpasswd(5) file.  It is
  25 assumed that the reader already has a basic understanding of LDAP concepts
  26 and has a working directory server already installed.  For more information
  27 on LDAP architectures and Directories, please refer to the following sites.
  28 </para>
  29
  30 <itemizedlist>
  31         <listitem><para>OpenLDAP - <ulink url="http://www.openldap.org/">http://www.openldap.org/</ulink></para></listitem>
  32         <listitem><para>iPlanet Directory Server - <ulink url="http://iplanet.netscape.com/directory">http://iplanet.netscape.com/directory</ulink></para></listitem>
  33 </itemizedlist>
  34
  35 <para>
  36 Note that <ulink url="http://www.ora.com/">O'Reilly Publishing</ulink> is working on
  37 a guide to LDAP for System Administrators which has a planned release date of
  38 early summer, 2002.
  39 </para>
  40
  41 <para>It may also be helpful to suppplement the reading of the HOWTO with
  42 the <ulink url="http://www.unav.es/cti/ldap-smb/ldap-smb-2_2-howto.html">Samba-PDC-LDAP-HOWTO</ulink>
  43 maintained by Ignacio Coupeau.
  44 </para>
  45
  46 </sect1>
  47
  48
  49 <sect1>
  50 <title>Introduction</title>
  51
  52 <para>
  53 Traditionally, when configuring <ulink url="smb.conf.5.html#ENCRYPTPASSWORDS">"encrypt
  54 passwords = yes"</ulink> in Samba's <filename>smb.conf</filename> file, user account
  55 information such as username, LM/NT password hashes, password change times, and account
  56 flags have been stored in the <filename>smbpasswd(5)</filename> file.  There are several
  57 disadvantages to this approach for sites with very large numbers of users (counted
  58 in the thousands).
  59 </para>
  60
  61 <para>
  62 The first is that all lookups must be performed sequentially.  Given that
  63 there are approximately two lookups per domain logon (one for a normal
  64 session connection such as when mapping a network drive or printer), this
  65 is non-optimal.  What is needed is an indexed approach such as is used in
  66 databases.
  67 </para>
  68
  69 <para>
  70 The second problem is that administrators which desired to replicate an
  71 smbpasswd file to more than one Samba server were left to use external
  72 tools such as <command>rsync(1)</command> and <command>ssh(1)</command>
  73 and write custom, in-house scripts.
  74 </para>
  75
  76 <para>
  77 And finally, the amount of information which is stored in an
  78 smbpasswd entry leaves no room for additional attributes such as
  79 a home directory, password expiration time, or even a Relative
  80 Identified (RID).
  81 </para>
  82
  83 <para>
  84 As a result of these defeciencies, a more robust means of storing user attributes
  85 used by smbd was developed.  The API which defines access to user accounts
  86 is referred to as the samdb interface (previously this was called the passdb
  87 API, and is still so named in the CVS trees).  In Samba 2.2.3, enabling support
  88 for a samdb backend (e.g. <parameter>--with-ldapsam</parameter> or
  89 <parameter>--with-tdbsam</parameter>) requires compile time support.
  90 </para>
  91
  92 <para>
  93 When compiling Samba to include the <parameter>--with-ldapsam</parameter> autoconf
  94 option, smbd (and associated tools) will store and lookup user accounts in
  95 an LDAP directory.  In reality, this is very easy to understand.  If you are
  96 comfortable with using an smbpasswd file, simply replace "smbpasswd" with
  97 "LDAP directory" in all the documentation.
  98 </para>
  99
 100 <para>
 101 There are a few points to stress about what the <parameter>--with-ldapsam</parameter>
 102 does not provide.  The LDAP support referred to in the this documentat does not
 103 include:
 104 </para>
 105
 106 <itemizedlist>
 107         <listitem><para>A means of retrieving user account information from
 108         an Windows 2000 Active Directory server.</para></listitem>
 109         <listitem><para>A means of replacing /etc/passwd.</para></listitem>
 110 </itemizedlist>
 111
 112 <para>
 113 The second item can be accomplished by using LDAP NSS and PAM modules.  LGPL
 114 versions of these libraries can be obtained from PADL Software
 115 (<ulink url="http://www.padl.com/">http://www.padl.com/</ulink>).  However,
 116 the details of configuring these packages i beyond the scope of this document.
 117 </para>
 118
 119 </sect1>
 120
 121 <sect1>
 122 <title>Supported LDAP Servers</title>
 123
 124 <para>
 125 The LDAP samdb code in 2.2.3 has been developed and tested using the OpenLDAP
 126 2.0 server and client libraries.  The same code should be able to work with
 127 Netscape's Directory Server and client SDK. However, due to lack of testing
 128 so far, there are bounds to be compile errors and bugs.  These should not be
 129 hard to fix. If you are so inclined, please be sure to forward all pacthes to
 130 <ulink url="samba-patches@samba.org">samba-patches@samba.org</ulink> and
 131 <ulink url="jerry@samba.org">jerry@samba.org</ulink>.
 132 </para>
 133
 134 </sect1>
 135
 136
 137
 138
 139 <sect1>
 140 <title>Schema and Relationship to the RFC 2307 posixAccount</title>
 141
 142
 143 <para>
 144 Samba 2.2.3 includes the necessary schema file for OpenLDAP 2.0 in
 145 <filename>examples/LDAP/samba.schema</filename>.  (Note that this schema
 146 file has been modified since the experimental support initially included
 147 in 2.2.2).  The sambaAccount objectclass is given here:
 148 </para>
 149
 150 <para><programlisting>
 151 objectclass ( 1.3.1.5.1.4.1.7165.2.2.2 NAME 'sambaAccount' SUP top STRUCTURAL
 152      DESC 'Samba Account'
 153      MUST ( uid $ rid )
 154      MAY  ( cn $ lmPassword $ ntPassword $ pwdLastSet $ logonTime $
 155             logoffTime $ kickoffTime $ pwdCanChange $ pwdMustChange $ acctFlags $
 156             displayName $ smbHome $ homeDrive $ scriptPath $ profilePath $
 157             description $ userWorkstations $ primaryGroupID ))
 158 </programlisting></para>
 159
 160 <para>
 161 The samba.schema file has been formatted for OpenLDAP 2.0.  The OID's are
 162 owned by the Samba Team and as such as legal to be openly published.
 163 If you translate the schema to be used with Netscape DS, please
 164 submit the modified schema file as a patch to <ulink
 165 url="jerry@samba.org">jerry@samba.org</ulink>
 166 </para>
 167
 168 <para>
 169 Just as the smbpasswd file is mean to store information which supplements a
 170 user's <filename>/etc/passwd</filename> entry, so is the sambaAccount object
 171 meant to supplement the UNIX user account information.  A sambaAccount is a
 172 <constant>STRUCTURAL</constant> objectclass so it can be stored individually
 173 in the directory.  However, there are several fields (e.g. uid) which overlap
 174 with the posixAccount objectclass outlined in RFC2307.  This is by design.
 175 </para>
 176
 177 <para>
 178 In order to store all user account information (UNIX and Samba) in the directory,
 179 it is necessary to use the sambaAccount and posixAccount objectclasses in
 180 combination.  However, smbd will still obtain the user's UNIX account
 181 information via the standard C library calls (e.g. getpwnam(), et. al.).
 182 This means that the Samba server must also have the LDAP NSS library installed
 183 and functioning correctly.  This division of information mkes it posible to
 184 store all Samba account information in LDAP, but still maintain UNIX account
 185 information in NIS while the network is transitioning to a full LDAP infratrsucture.
 186 </para>
 187
 188 <para>
 189 To include support for the sambaAccount object in an OpenLDAP directory
 190 server, first copy the samba.schema file to slapd's configuration directory.
 191 </para>
 192
 193 <para>
 194 <prompt>root# </prompt><command>cp samba.schema /etc/openldap/schema/</command>
 195 </para>
 196
 197 <para>
 198 Next, include the <filename>samba.schema</filename> file in <filename>slapd.conf</filename>.
 199 The sambaAccount object contains two attributes which depend upon other schema
 200 files.  The 'uid' attribute is defined in <filename>cosine.schema</filename> and
 201 the 'displayName' attribute is defined in the <filename>inetorgperson.schema</filename>
 202 file.  Bother of these must be included before the <filename>samba.schema</filename> file.
 203 </para>
 204
 205 <para><programlisting>
 206 ## /etc/openldap/slapd.conf
 207
 208 ## schema files (core.schema is required by default)
 209 include            /etc/openldap/schema/core.schema
 210
 211 ## needed for sambaAccount
 212 include            /etc/openldap/schema/cosine.schema
 213 include            /etc/openldap/schema/inetorgperson.schema
 214 include            /etc/openldap/schema/samba.schema
 215
 216 ## uncomment this line if you want to support the RFC2307 (NIS) schema
 217 ## include         /etc/openldap/schema/nis.schema
 218
 219 ....
 220 </programlisting></para>
 221
 222
 223 </sect1>
 224
 225
 226
 227 <sect1>
 228 <title>smb.conf LDAP parameters</title>
 229
 230
 231 <para>
 232 The following parameters are available in smb.conf only with <parameter>--with-ldapsam</parameter>
 233 was included with compiling Samba.
 234 </para>
 235
 236 <itemizedlist>
 237         <listitem><para><ulink url="smb.conf.5.html#LDAPSSL">ldap ssl</ulink></para></listitem>
 238         <listitem><para><ulink url="smb.conf.5.html#LDAPSERVER">ldap server</ulink></para></listitem>
 239         <listitem><para><ulink url="smb.conf.5.html#LDAPADMINDN">ldap admin dn</ulink></para></listitem>
 240         <listitem><para><ulink url="smb.conf.5.html#LDAPSUFFIX">ldap suffix</ulink></para></listitem>
 241         <listitem><para><ulink url="smb.conf.5.html#LDAPFILTER">ldap filter</ulink></para></listitem>
 242         <listitem><para><ulink url="smb.conf.5.html#LDAPPORT">ldap port</ulink></para></listitem>
 243 </itemizedlist>
 244
 245 <para>
 246 These are described in the <ulink url="smb.conf.5.html">smb.conf(5)</ulink> man
 247 page and so will not be repeated here.  However, a sample smb.conf file for
 248 use with an LDAP directory could appear as
 249 </para>
 250
 251 <para><programlisting>
 252 ## /usr/local/samba/lib/smb.conf
 253 [global]
 254      security = user
 255      encrypt passwords = yes
 256
 257      netbios name = TASHTEGO
 258      workgroup = NARNIA
 259
 260      # ldap related parameters
 261
 262      # define the DN to use when binding to the directory servers
 263      # The password for this DN is not stored in smb.conf.  Rather it
 264      # must be set by using 'smbpasswd -w <replaceable>secretpw</replaceable>' to store the
 265      # passphrase in the secrets.tdb file.  If the "ldap admin dn" values
 266      # changes, this password will need to be reset.
 267      ldap admin dn = "cn=Manager,dc=samba,dc=org"
 268
 269      #  specify the LDAP server's hostname (defaults to locahost)
 270      ldap server = ahab.samba.org
 271
 272      # Define the SSL option when connecting to the directory
 273      # ('off', 'start tls', or 'on' (default))
 274      ldap ssl = start tls
 275
 276      # define the port to use in the LDAP session (defaults to 636 when
 277      # "ldap ssl = on")
 278      ldap port = 389
 279
 280      # specify the base DN to use when searching the directory
 281      ldap suffix = "ou=people,dc=samba,dc=org"
 282
 283      # generally the default ldap search filter is ok
 284      # ldap filter = "(&(uid=%u)(objectclass=sambaAccount))"
 285 </programlisting></para>
 286
 287
 288
 289 </sect1>
 290
 291
 292
 293
 294 <sect1>
 295 <title>Security and sambaAccount</title>
 296
 297
 298 <para>
 299 There are two important points to remember when discussing the security
 300 of sambaAccount entries in the directory.
 301 </para>
 302
 303 <itemizedlist>
 304         <listitem><para><emphasis>Never</emphasis> retrieve the lmPassword or
 305         ntPassword attribute values over and unencrypted LDAP session.</para></listitem>
 306         <listitem><para><emphasis>Never</emphasis> allow non-admin users to
 307         view the lmPassword or ntPassword attribute values.</para></listitem>
 308 </itemizedlist>
 309
 310 <para>
 311 These password hashes are clear text equivalents and can be used to impersonate
 312 the user without deriving the original clear text strings.
 313 </para>
 314
 315 <para>
 316 To remedy the first security issue, the "ldap ssl" smb.conf parameter defaults
 317 to require an encrypted session (<command>ldap ssl = on</command>) using
 318 the default port of 636
 319 when contacting the directory server.  When using an OpenLDAP 2.0 server, it
 320 is possible to use the use the StartTLS LDAP extended  operation in the place of
 321 LDAPS.  In either case, you are strongly discouraged to disable this security
 322 (<command>ldap ssl = off</command>).
 323 </para>
 324
 325 <para>
 326 The second security precaution is to prevent non-administrative users from
 327 harvesting password hashes from the directory.  This can be done using the
 328 following ACL in <filename>slapd.conf</filename>:
 329 </para>
 330
 331 <para><programlisting>
 332 ## allow users to update their own password, but not to browse others
 333 access to attrs=userPassword,lmPassword,ntPassword
 334      by self write
 335      by * auth
 336 </programlisting></para>
 337
 338 <para>
 339 You may of course, add in write access to administrative DN's as necessary.
 340 </para>
 341
 342 </sect1>
 343
 344
 345
 346 <sect1>
 347 <title></title>
 348
 349
 350 <para>
 351 There are currently four sambaAccount attributes which map directly onto
 352 <filename>smb.conf</filename> parameters.
 353 </para>
 354
 355 <itemizedlist>
 356         <listitem><para>smbHome -&gt; "logon home"</para></listitem>
 357         <listitem><para>profilePath -&gt; "logon path"</para></listitem>
 358         <listitem><para>homeDrive -&gt; "logon drive"</para></listitem>
 359         <listitem><para>scriptPath -&gt; "logon script"</para></listitem>
 360 </itemizedlist>
 361
 362 <para>
 363 First of all, these parameters are only used when Samba is acting as a
 364 PDC or a domain (refer to the <ulink url="Samba-PDC-HOWTO.html">Samba-PDC-HOWTO</ulink>
 365 for details on how to configure Samba as a Primary Domain Controller).
 366 Furthermore, these attributes are only stored with the sambaAccount entry if
 367 the values are non-default values.  For example, assume TASHTEGO has now been
 368 configured as a PDC and that <command>logon home = \\%L\%u</command> was defined in
 369 its <filename>smb.conf</filename> file.  Assuming <filename>smb.conf</filename>
 370 also contains , when a user named "becky" logons to the domain, the <parameter>logon
 371 home</parameter> string is expanded to \\TASHTEGO\becky.
 372 </para>
 373
 374 <para>
 375 If the smbHome attribute exists in the entry "uid=becky,ou=people,dc=samba,dc=org",
 376 this value is used.  However, if this attribute does not exist, then the value
 377 of the <parameter>logon home</parameter> parameter is used in its place.  Samba
 378 will only write the attribute value to the directory entry is the value is
 379 something other than the default (e.g. \\MOBY\becky).
 380 </para>
 381
 382
 383 </sect1>
 384
 385
 386
 387
 388 <sect1>
 389 <title>Example LDIF Entries for a sambaAccount</title>
 390
 391
 392 <para>
 393 The following is a working LDIF with the inclusion of the posixAccount objectclass:
 394 </para>
 395
 396 <para><programlisting>
 397 dn: uid=guest2, ou=people,dc=plainjoe,dc=org
 398 ntPassword: 878D8014606CDA29677A44EFA1353FC7
 399 pwdMustChange: 2147483647
 400 primaryGroupID: 1201
 401 lmPassword: 552902031BEDE9EFAAD3B435B51404EE
 402 pwdLastSet: 1010179124
 403 logonTime: 0
 404 objectClass: sambaAccount
 405 uid: guest2
 406 kickoffTime: 2147483647
 407 acctFlags: [UX         ]
 408 logoffTime: 2147483647
 409 rid: 19006
 410 pwdCanChange: 0
 411 </programlisting></para>
 412
 413 <para>
 414 The following is an LDIF entry for using both the sambaAccount and
 415 posixAccount objectclasses:
 416 </para>
 417
 418 <para><programlisting>
 419 dn: uid=gcarter, ou=people,dc=plainjoe,dc=org
 420 logonTime: 0
 421 displayName: Gerald Carter
 422 lmPassword: 552902031BEDE9EFAAD3B435B51404EE
 423 primaryGroupID: 1201
 424 objectClass: posixAccount
 425 objectClass: sambaAccount
 426 acctFlags: [UX         ]
 427 userPassword: {crypt}BpM2ej8Rkzogo
 428 uid: gcarter
 429 uidNumber: 9000
 430 cn: Gerald Carter
 431 loginShell: /bin/bash
 432 logoffTime: 2147483647
 433 gidNumber: 100
 434 kickoffTime: 2147483647
 435 pwdLastSet: 1010179230
 436 rid: 19000
 437 homeDirectory: /home/tashtego/gcarter
 438 pwdCanChange: 0
 439 pwdMustChange: 2147483647
 440 ntPassword: 878D8014606CDA29677A44EFA1353FC7
 441 </programlisting></para>
 442
 443
 444 </sect1>
 445
 446
 447
 448 <sect1>
 449 <title>Comments</title>
 450
 451
 452 <para>
 453 Please mail all comments regarding this HOWTO to <ulink
 454 url="mailto:jerry@samba.org">jerry@samba.org</ulink>.  This documents was
 455 last updated to reflect the Samba 2.2.3 release.
 456
 457 </para>
 458
 459
 460 </sect1>
 461
 462
 463 </chapter>