<< Back to man.ChinaUnix.net

Chapter 13. Identity Mapping (IDMAP)

John H. Terpstra

Samba Team

Table of Contents

Samba Server Deployment Types and IDMAP
Stand-Alone Samba Server
Domain Member Server or Domain Member Client
Primary Domain Controller
Backup Domain Controller
Examples of IDMAP Backend Usage
Default Winbind TDB
IDMAP_RID with Winbind
IDMAP Storage in LDAP using Winbind
IDMAP and NSS Using LDAP From ADS with RFC2307bis Schema Extension

The Microsoft Windows operating system has a number of features that impose specific challenges to interoperability with operating system on which Samba is implemented. This chapter deals explicitly with the mechanisms Samba-3 (version 3.0.8 and later) uses to overcome one of the key challenges in the integration of Samba servers into an MS Windows networking environment. This chapter deals with Identify Mapping (IDMAP) of Windows Security Identifers (SIDs) to UNIX UIDs and GIDs.

To ensure good sufficient coverage each possible Samba deployment type will be discussed. This is followed by an overview of how the IDMAP facility may be implemented.

The IDMAP facility is usually of concern where more than one Samba server (or Samba network client) is installed in the one Domain. Where there is a single Samba server do not be too concerned regarding the IDMAP infrastructure - the default behavior of Samba is nearly always sufficient.

The use of IDMAP is important where the Samba server will be accessed by workstations or servers from more than one domain, in which case it is important to run winbind so it can handle the resolution (ID mapping) of foreign SIDs to local UNIX UIDs and GIDs.

The use of the IDMAP facility requires that the winbindd be executed on Samba start-up.

Samba Server Deployment Types and IDMAP

There are four (4) basic server deployment types, as documented in the chapter on Server Types and Security Modes.

Stand-Alone Samba Server

A stand-alone Samba server is an implementation that is not a member of a Windows NT4 Domain, a Windows 200X Active Directory Domain, or of a Samba Domain.

By definition, this means that users and groups will be created and controlled locally and the identity of a network user must match a local UNIX/Linux user login. The IDMAP facility is therefore of little to no interest, winbind will not be necessary, and the IDMAP facility will not be relevant or of interest.

Domain Member Server or Domain Member Client

Samba-3 can act as a Windows NT4 PDC or BDC thereby providing domain control protocols that are compatible with Windows NT4. Samba-3 file and print sharing protocols are compatible with all version of Microsoft Windows products. Windows NT4, as with Microsoft Active Directory, extensively makes use of Windows security identifiers (SIDs).

Samba-3 Domain Member servers and clients must interact correctly with MS Windows SIDs. Incoming Windows SIDs must be translated to local UNIX UIDs and GIDs. Outgoing information from the Samba server must provide to MS Windows clients and servers appropriate SIDs.

A Samba member of a Windows networking domain (NT4-style or ADS) can be configured to handle identity mapping in a variety of ways. The mechanism is will use depends on whether or not the winbindd daemon is used, and how the winbind functionality is configured. The configuration options are briefly described here:

Winbind is not used, users and groups are local:

Where winbindd is not used Samba (smbd) uses the underlying UNIX/Linux mechanisms to resolve the identity of incoming network traffic. This will be done using the LoginID (account name) in the session setup request and passing it to the getpwnam() system function call. This call is implemented using the name service switch (NSS) mechanism on modern UNIX/Linux systems. By saying “users and groups are local” we are implying that they are stored only on the local system, in the /etc/passwd and /etc/group respectively.

For example, if an incoming SessionSetupAndX request is owned by the user BERYLIUM\WambatW, a system call will be made to look up the user WambatW in the /etc/passwd file.

This configuration may be used with stand-alone Samba servers, Domain Member servers (NT4 or ADS), and may be used for a PDC that uses either an smbpasswd or a tdbsam based Samba passdb backend.

Winbind is not used, users and groups resolved via NSS:

In this situation user and group accounts are treated as if they are local accounts, the only way in which this differs from having local accounts is that the accounts are stored in a repository that can be shared. In practice this means that they will reside in either a NIS type database or else in LDAP.

This configuration may be used with stand-alone Samba servers, Domain Member servers (NT4 or ADS), and may be used for a PDC that uses either an smbpasswd or a tdbsam based Samba passdb backend.

Winbind/NSS with the default local IDMAP table:

There are many sites that require only a simple Samba server, or a single Samba server that is a member of a Windows NT4 Domain or an ADS Domain. A typical example is an appliance like file server on which no local accounts are configured and winbind is used to obtain account credentials from the domain controllers for the domain. The domain control can be provided by Samba-3, MS Windows NT4 or MS Windows Active Directory.

Winbind is a great convenience in this situation. All that is needed is a range of UID numbers and GID numbers that can be defined in the smb.conf file, the /etc/nsswitch.conf file is configured to use winbind which does all the difficult work of mapping incoming SIDs to appropriate UIDs and GIDs. The SIDs are allocated a UID/GID in the order in which winbind receives them.

This configuration is not convenient or practical in sites that have more than one Samba server and that require the same UID or GID for the same user or group across all servers. One of the hazards of this method is that in the event that the winbind IDMAP file may become corrupted or lost, the repaired or rebuilt IDMAP file may allocate UIDs and GIDs to differing users and groups from what was there previously with the result that MS Windows files that are stored on the Samba server may now not belong to to rightful owner.

Winbind/NSS uses RID based IDMAP:

The IDMAP_RID facility is new to Samba version 3.0.8. It was added to make life easier for a number of sites that are committed to use of MS ADS, who do not want to apply an ADS schema extension, and who do not wish to install an LDAP directory server just for the purpose of maintaining an IDMAP table. If you have a single ADS domain (not a forest of domains, and not multiple domain trees) and you want a simple cookie-cutter solution to the IDMAP table problem, then IDMAP_RID is an obvious choice.

This facility requires the allocation of the idmap uid and the idmap gid ranges, and within the idmap uid it is possible to allocate a sub-set of this range for automatic mapping of the relative identifier (RID) portion of the SID directly to the base of the UID plus the RID value. For example, if the idmap uid range is 1000-100000000 and the idmap backend = idmap_rid:DOMAIN_NAME=1000-50000000, and a SID is encountered that has the value S-1-5-21-34567898-12529001-32973135-1234, the resulting UID will be 1000 + 1234 = 2234.

Winbind with an NSS/LDAP backend based IDMAP facility:

In this configuration winbind resolved SIDs to UIDs and GIDs from the idmap uid and idmap gid ranges specified in the smb.conf file, but instead of using a local winbind IDMAP table it is stored in an LDAP directory so that all Domain Member machines (clients and servers) can share a common IDMAP table.

It is important that all LDAP IDMAP clients use only the master LDAP server as the idmap backend facility in the smb.conf file does not correctly handle LDAP redirects.

Winbind with NSS to resolve UNIX/Linux user and group IDs:

The use of LDAP as the passdb backend is a smart solution for PDC, BDC as well as for Domain Member servers. It is a neat method for assuring that UIDs, GIDs and the matching SIDs will be consistent across all servers.

The use of the LDAP based passdb backend requires use of the PADL nss_ldap utility, or an equivalent. In this situation winbind is used to handle foreign SIDs; ie: SIDs from stand-alone Windows clients (i.e.: not a member of our domain) as well as SIDs from another domain. The foreign UID/GID is mapped from allocated ranges (idmap uid and idmap gid) in precisely the same manner as when using winbind with a local IDMAP table.

The nss_ldap tool set can be used to access UIDs and GIDs via LDAP as well as via Active Directory. In order to use Active Directory it is necessary to modify the ADS schema by installing either the AD4UNIX schema extension or else use the Microsoft Services for UNIX version 3.5 of later to extend the ADS schema so it maintains UNIX account credentials. Where the ADS schema is extended a Microsoft Management Console (MMC) snap-in in also installed to permit the UNIX credentials to be set and managed from the ADS User and Computer management tool. Each account must be separately UNIX enabled before the UID and GID data can be used by Samba.

Primary Domain Controller

Microsoft Windows domain security systems generate the user and group security identifier (SID) as part of the process of creation of an account. Windows does not have a concept of the UNIX UID or a GID, rather it has its own type of security descriptor. When Samba is used as a Domain Controller, it provides a method of producing a unique SID for each user and group. Samba generates a machine and a domain SID to which it adds a relative identifier (RID) that is calculated algorithmically from a base value that can be specified in the smb.conf file, plus twice (2X) the UID or GID. This method is called “algorithmic mapping”.

For example, a user has a UID of 4321, and the algorithmic RID base has a value of 1000, the RID will be 1000 + (2 x 4321) = 9642. Thus, if the domain SID is S-1-5-21-89238497-92787123-12341112, the resulting SID is S-1-5-21-89238497-92787123-12341112-9642.

The foregoing type SID is produced by Samba as an automatic function and is either produced on-the-fly (as in the case when using a passdb backend = [tdbsam | smbpasswd], or may be stored as a permanent part of an account in an LDAP based ldapsam.

MS Active Directory Server (ADS) uses a directory schema that can be extended to accommodate additional account attributes such as UIDs and GIDs. The installation of Microsoft Service for UNIX 3.5 will expand the normal ADS schema to include UNIX account attributes. These must of course be managed separately through a snap-in module to the normal ADS account management MMC interface.

Security identifiers used within a domain must be managed to avoid conflict and to preserve itegrity. In an NT4 domain context that PDC manages the distribution of all security credentials to the backup domain controllers. At this time the only passdb backend for a Samba domain controller that is suitable for such information is an LDAP backend.

Backup Domain Controller

Backup Domain Controllers (BDCs) have read-only access to security credentials that are stored in LDAP. Changes in user or group account information are passed by the BDC to the PDC. Only the PDC can write changes to the directory.

IDMAP information can however be written directly to the LDAP server so long as all domain controllers have access to the master (writable) LDAP server. Samba-3 at this time does not handle LDAP redirects in the IDMAP backend. This means that it is is unsafe to use a slave (replicate) LDAP server with the IDMAP facility.

Examples of IDMAP Backend Usage

Anyone who wishes to use winbind will find the following example configurations helpful. Remember that in the majority of cases winbind is of primary interest for use with Domain Member Servers (DMSs) and Domain Member Clients (DMCs).

Default Winbind TDB

Two common configurations are used:

  • Networks that have an NT4 PDC (with or without BDCs) or a Samba PDC (with or without BDCs).

  • Networks that use MS Windows 200X ADS.

NT4 Style Domains (includes Samba Domains)

The following is a simple example of an NT4 DMS smb.conf file that shows only the global section.

#Global parameters
[global]
        workgroup = MEGANET2
        security = DOMAIN
        idmap uid = 10000-20000
        idmap gid = 10000-20000
        template primary group = "Domain Users"
        template shell = /bin/bash

The use of winbind requires configuration of NSS. Edit the /etc/nsswitch.conf so it includes the following entries:

...
passwd: files winbind
shadow: files winbind
group:  files winbind
...
hosts:  files wins
...

The creation of the DMS requires the following steps:

  1. Create or install and smb.conf file with the above configuration.

  2. Execute:

    root#  net rpc join -UAdministrator%password
    Joined domain MEGANET2.
    

    The success or failure of the join can be confirmed with the following command:

    root#  net rpc testjoin
    Join to 'MIDEARTH' is OK
    

    A failed join would report an error message like the following:

    root#  net rpc testjoin
    [2004/11/05 16:34:12, 0] utils/net_rpc_join.c:net_rpc_join_ok(66)
    Join to domain 'MEGANET2' is not valid
    

  3. Start the nmbd, winbind, and smbd daemons in the order shown.

ADS Domains

The procedure for joining and ADS domain is similar to the NT4 domain join, except the smb.conf file will have the following contents:

# Global parameters
[global]
        workgroup = BUTTERNET
        netbios name = GARGOYLE
        realm = BUTTERNET.BIZ
        security = ADS
        template shell = /bin/bash
        idmap uid = 500-10000000
        idmap gid = 500-10000000
        winbind use default domain = Yes
        winbind nested groups = Yes
        printer admin = "BUTTERNET\Domain Admins"

ADS DMS operation requires use of kerberos (KRB). For this to work the krb5.conf must be configured. The exact requirements depends on which version of MIT or Heimdal kerberos is being used. It is sound advice to use only the latest version, which at this time are MIT kerberos version 1.3.5 and Heimdal 0.61.

The creation of the DMS requires the following steps:

  1. Create or install and smb.conf file with the above configuration.

  2. Edit the /etc/nsswitch.conf file as shown above.

  3. Execute:

    root#  net ads join -UAdministrator%password
    Joined domain BUTTERNET.
    

    The success or failure of the join can be confirmed with the following command:

    root#  net ads testjoin
    Using short domain name -- BUTTERNET
    Joined 'GARGOYLE' to realm 'BUTTERNET.BIZ'
    

    An invalid or failed join can be detected by executing:

    root#  net ads testjoin
    GARGOYLE$@'s password:
    [2004/11/05 16:53:03, 0] utils/net_ads.c:ads_startup(186)
      ads_connect: No results returned
    Join to domain is not valid
    

    The specific error message may differ from the above as it depends on the type of failure that may have occured. Increase the log level to 10, repeat the above test and then examine the log files produced to identify the nature of the failure.

  4. Start the nmbd, winbind, and smbd daemons in the order shown.

IDMAP_RID with Winbind

The idmap_rid facility is a new tool that, unlike native winbind, creates a predictable mapping of MS Windows SIDs to UNIX UIDs and GIDs. The key benefit of this method of implementing the Samba IDMAP facility is that it eliminates the need to store the IDMAP data in a central place. The down-side is that it can be used only within a single ADS Domain and is not compatible with trusted domain implementations.

This alternate method of SID to UID/GID mapping can be achieved uses the idmap_rid plug-in. This plug-in uses the RID of the user SID to derive the UID and GID by adding the RID to a base value specified. This utility requires that the parameter “allow trusted domains = No” must be specified, as it is not compatible with multiple domain environments. The idmap uid and idmap gid ranges must be specified.

The idmap_rid facility can be used both for NT4/Samba style domains as well as with Active Directory. To use this with an NT4 Domain the realm is not used, additionally the method used to join the domain uses the net rpc join process.

An example smb.conf file for and ADS domain environment is shown here:

# Global parameters
[global]
        workgroup = KPAK
        netbios name = BIGJOE
        realm = CORP.KPAK.COM
        server string = Office Server
        security = ADS
        allow trusted domains = No
        idmap backend = idmap_rid:KPAK=500-100000000
        idmap uid = 500-100000000
        idmap gid = 500-100000000
        template shell = /bin/bash
        winbind use default domain = Yes
        winbind enum users = No
        winbind enum groups = No
        winbind nested groups = Yes
        printer admin = "Domain Admins"

In a large domain with many users it is imperative to disable enumeration of users and groups. For examplem, at a site that has 22,000 users in Active Directory the winbind based user and group resolution is unavailable for nearly 12 minutes following first start-up of winbind. Disabling of such enumeration resulted in instantaneous response. The disabling of user and group enumeration means that it will not be possible to list users or groups using the getent passwd and getent group commands. It will be possible to perform the lookup for individual users, as shown in the procedure below.

The use of this tool requires configuration of NSS as per the native use of winbind. Edit the /etc/nsswitch.conf so it has the following parameters:

...
passwd: files winbind
shadow: files winbind
group:  files winbind
...
hosts:  files wins
...

The following procedure can be used to utilize the idmap_rid facility:

  1. Create or install and smb.conf file with the above configuration.

  2. Edit the /etc/nsswitch.conf file as shown above.

  3. Execute:

    root#  net ads join -UAdministrator%password
    Using short domain name -- KPAK
    Joined 'BIGJOE' to realm 'CORP.KPAK.COM'
    

    An invalid or failed join can be detected by executing:

    root#  net ads testjoin
    BIGJOE$@'s password:
    [2004/11/05 16:53:03, 0] utils/net_ads.c:ads_startup(186)
      ads_connect: No results returned
    Join to domain is not valid
    

    The specific error message may differ from the above as it depends on the type of failure that may have occured. Increase the log level to 10, repeat the above test and then examine the log files produced to identify the nature of the failure.

  4. Start the nmbd, winbind, and smbd daemons in the order shown.

  5. Validate the operation of this configuration by executing:

    root#  getent passwd administrator
    administrator:x:1000:1013:Administrator:/home/BE/administrator:/bin/bash
    

IDMAP Storage in LDAP using Winbind

The storage of IDMAP information in LDAP can be used with both NT4/Samba-3 style domains as well as with ADS domains. OpenLDAP is a commonly used LDAP server for this purpose, although any standards complying LDAP server can be used. It is therefore possible to deploy this IDMAP configuration using the Sun iPlanet LDAP server, Novell eDirectory, Microsoft ADS plus ADAM, and so on.

The following example is for an ADS style domain:

# Global parameters
[global]
        workgroup = SNOWSHOW
        netbios name = GOODELF
        realm = SNOWSHOW.COM
        server string = Samba Server
        security = ADS
        log level = 1 ads:10 auth:10 sam:10 rpc:10
        ldap admin dn = cn=Manager,dc=SNOWSHOW,dc=COM
        ldap idmap suffix = ou=Idmap
        ldap suffix = dc=SNOWSHOW,dc=COM
        idmap backend = ldap:ldap://ldap.snowshow.com
        idmap uid = 150000-550000
        idmap gid = 150000-550000
        template shell = /bin/bash
        winbind use default domain = Yes

In the case of an NT4 or Samba-3 style Domain the realm is not used and the command used to join the domain is: net rpc join. The above example also demonstrates advanced error reporting techniques that are documented in the chapter called Reporting Bugs.

Where MIT kerberos is installed (version 1.3.4 or later) edit the /etc/krb5.conf file so it has the following contents:

[logging]
 default = FILE:/var/log/krb5libs.log
 kdc = FILE:/var/log/krb5kdc.log
 admin_server = FILE:/var/log/kadmind.log

[libdefaults]
 default_realm = SNOWSHOW.COM
 dns_lookup_realm = false
 dns_lookup_kdc = true

[appdefaults]
 pam = {
   debug = false
   ticket_lifetime = 36000
   renew_lifetime = 36000
   forwardable = true
   krb4_convert = false
 }

Where Heimdal kerberos is installed edit the /etc/krb5.conf file so it is either empty (i.e.: no contents) or it has the following contents:

[libdefaults]
        default_realm = SNOWSHOW.COM
        clockskew = 300

[realms]
        SNOWSHOW.COM = {
                kdc = ADSDC.SHOWSHOW.COM
        }
        
[domain_realm]
        .snowshow.com = SNOWSHOW.COM

Note

Samba can not use the Heimdal libraries if there is no /etc/krb5.conf file. So long as there is an empty file the Heimdal kerberos libraries will be usable. There is no need to specify any settings as Samba using the Heimdal libraries can figure this out automatically.

Edit the NSS control file /etc/nsswitch.conf so it has the following entries:

...
passwd: files ldap
shadow: files ldap
group:  files ldap
...
hosts:  files wins
...

You will need the PADL nss_ldap tool set for this solution. Configure the /etc/ldap.conf file so it has the information needed. The following is an example of a working file:

host    192.168.2.1
base    dc=snowshow,dc=com
binddn  cn=Manager,dc=snowshow,dc=com
bindpw  not24get

pam_password exop

nss_base_passwd ou=People,dc=snowshow,dc=com?one
nss_base_shadow ou=People,dc=snowshow,dc=com?one
nss_base_group  ou=Groups,dc=snowshow,dc=com?one
ssl     no

The following procedure may be followed to affect a working configuration:

  1. Configure the smb.conf file as shown above.

  2. Create the /etc/krb5.conf file following the indications above.

  3. Configure the /etc/nsswitch.conf file as shown above.

  4. Download, build and install the PADL nss_ldap tool set. Configure the /etc/ldap.conf file as shown above.

  5. Configure an LDAP server, initialize the directory with the top level entries needed by IDMAP as shown in the following LDIF file:

    dn: dc=snowshow,dc=com
    objectClass: dcObject
    objectClass: organization
    dc: snowshow
    o: The Greatest Snow Show in Singapore.
    description: Posix and Samba LDAP Identity Database
    
    dn: cn=Manager,dc=snowshow,dc=com
    objectClass: organizationalRole
    cn: Manager
    description: Directory Manager
    
    dn: ou=Idmap,dc=snowshow,dc=com
    objectClass: organizationalUnit
    ou: idmap
    

  6. Execute the command to join the Samba Domain Member Server to the ADS domain as shown here:

    root#  net ads testjoin
    Using short domain name -- SNOWSHOW
    Joined 'GOODELF' to realm 'SNOWSHOW.COM'
    

  7. Store the LDAP server access password in the Samba secrets.tdb file as follows:

    root#  smbpasswd -w not24get
    

  8. Start the nmbd, winbind, and smbd daemons in the order shown.

Follow the diagnositic procedures shown earlier in this chapter to identify success or failure of the join. In many cases a failure is indicated by a silent return to the command prompt with no indication of the reason for failure.

IDMAP and NSS Using LDAP From ADS with RFC2307bis Schema Extension

The use of this method is messy. The information provided in the following is for guidance only and is very definitely not complete. This method does work; it is used in a number of large sites and has an acceptable level of performance.

The following is an example smb.conf file:

# Global parameters
[global]
        workgroup = BOBBY
        realm = BOBBY.COM
        security = ADS
        idmap uid = 150000-550000
        idmap gid = 150000-550000
        template shell = /bin/bash
        winbind cache time = 5
        winbind use default domain = Yes
        winbind trusted domains only = Yes
        winbind nested groups = Yes

The DMS must be joined to the domain using the usual procedure. Additionally, it is necessary to build and install the PADL nss_ldap tool set. Be sure to build this tool set with the following:

./configure --enable-rfc2307bis --enable-schema-mapping
make install

The following /etc/nsswitch.conf file contents are required:

...
passwd: files ldap
shadow: files ldap
group:  files ldap
...
hosts:  files wins
...

The /etc/ldap.conf file must be configured also. Refer to the PADL documentation and source code for nss_ldap to specific instructions.

The next step involves preparation on the ADS schema. This is briefly discussed in the remaining part of this chapter.

IDMAP, Active Directory and MS Services for UNIX 3.5

The Microsoft Windows Service for UNIX (SFU) version 3.5 is available for free download from the Microsoft Web site. You will need to download this tool and install it following Microsoft instructions.

IDMAP, Active Directory and AD4UNIX

Instructions for obtaining and installing the AD4UNIX tool set can be found from the Geekcomix web site.