Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to openSUSE Leap 15.1

5 LDAP—A Directory Service

Abstract

The Lightweight Directory Access Protocol (LDAP) is a protocol designed to access and maintain information directories. LDAP can be used for user and group management, system configuration management, address management, and more. This chapter provides a basic understanding of how LDAP works.

Ideally, a central server stores the data in a directory and distributes it to all clients using a well-defined protocol. The structured data allow a wide range of applications to access them. A central repository reduces the necessary administrative effort. The use of an open and standardized protocol like LDAP ensures that as many client applications as possible can access such information.

A directory in this context is a type of database optimized for quick and effective reading and searching. The type of data stored in a directory tends to be long lived and changes infrequently. This allows the LDAP service to be optimized for high performance concurrent reads, whereas conventional databases are optimized for accepting a large number of writes to data in a short time.

5.1 Structure of an LDAP Directory Tree

This section introduces the layout of an LDAP directory tree and provides the basic terminology used with regard to LDAP. If you are familiar with LDAP, read on at Section 5.3, “Manually Configuring a 389 Directory Server”.

An LDAP directory has a tree structure. All entries (called objects) of the directory have a defined position within this hierarchy. This hierarchy is called the directory information tree (DIT). The complete path to the desired entry, which unambiguously identifies it, is called the distinguished name or DN. An object in the tree is identified by its relative distinguished name (RDN). The distinguished name is built from the RDN’s of all entries on the path to the entry.

The relations within an LDAP directory tree become more evident in the following example, shown in Figure 5.1, “Structure of an LDAP Directory”.

Structure of an LDAP Directory
Figure 5.1: Structure of an LDAP Directory

The complete diagram is a fictional directory information tree. The entries on three levels are depicted. Each entry corresponds to one box in the image. The complete, valid distinguished name for the fictional employee Geeko Linux, in this case, is cn=Geeko Linux,ou=doc,dc=example,dc=com. It is composed by adding the RDN cn=Geeko Linux to the DN of the preceding entry ou=doc,dc=example,dc=com.

The types of objects that can be stored in the DIT are globally determined following a Schema. The type of an object is determined by the object class. The object class determines what attributes the relevant object must or may be assigned. The Schema contains all object classes and attributes which can be used by the LDAP server. Attributes are a structured data type. Their syntax, ordering and other behavior is defined by the Schema. LDAP servers supply a core set of Schemas which can work in a broad variety of environments. If a custom Schema is required, you can load it to an LDAP server.

Table 5.1, “Commonly Used Object Classes and Attributes” offers a small overview of the object classes from 00core.ldif and 06inetorgperson.ldif used in the example, including required attributes (Req. Attr.) and valid attribute values. After installing 389-ds, these can be found in usr/share/dirsrv/schema.

Table 5.1: Commonly Used Object Classes and Attributes

Object Class

Meaning

Example Entry

Req. Attr.

domain

name components of the domain

example

displayName

organizationalUnit

organizational unit

doc

ou

nsPerson

person-related data for the intranet or Internet

Geeko Linux

cn

Example 5.1, “Excerpt from CN=schema” shows an excerpt from a Schema directive with explanations.

Example 5.1: Excerpt from CN=schema
attributetype (1.2.840.113556.1.2.102 NAME 'memberOf' 1
       DESC 'Group that the entry belongs to' 2
       SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 3
       X-ORIGIN 'Netscape Delegated Administrator') 4

objectclass (2.16.840.1.113730.3.2.333 NAME 'nsPerson' 5
       DESC 'A representation of a person in a directory server' 6
       SUP top STRUCTURAL 7
       MUST ( displayName $ cn ) 8
       MAY ( userPassword $ seeAlso $ description $ legalName $ mail \
             $ preferredLanguage ) 9
       X-ORIGIN '389 Directory Server Project’
  ...

1

The name of the attribute, its unique object identifier (OID, numerical), and the abbreviation of the attribute.

2

A brief description of the attribute with DESC. The corresponding RFC, on which the definition is based, may also mentioned here.

3

The type of data that can be held in the attribute. In this case, it is a case-insensitive directory string.

4

The source of the schema element (for example, the name of the project).

5

The definition of the object class nsPerson begins with an OID and the name of the object class (like the definition of the attribute).

6

A brief description of the object class.

7

The SUP top entry indicates that this object class is not subordinate to another object class.

8

With MUST list all attribute types that must be used with an object of the type nsPerson.

9

With MAY list all attribute types that are optionally permitted with this object class.

5.2 Installing the Software for 389 Directory Server

The 389-ds package contains the 389 Directory Server and the administration tools. If the package is not installed yet, install it with the following command:

tux > sudo zypper install 389-ds

After installation, you can set up the server either manually or with YaST. Also, you can manage LDAP users and groups and configure an LDAP client with YaST:

5.3 Manually Configuring a 389 Directory Server

Setting up the 389 Directory Server takes the following basic steps:

The 389 Directory Server is controlled by 3 primary commands:

dsctl

Manages a local instance and requires root permissions. Requires you to be connected to a terminal which is running the directory server instance. Used for starting, stopping, backing up the database and more.

dsconf

The primary tool used for administration and configuration of the server. Manages an instance's configuration via its external interfaces. This allows you to make configuration changes remotely on the instance.

dsidm

Used for identity management (manage users, groups, passwords etc.). The permissions are granted by access controls, so users can reset their own password or change details of their own account, for example.

5.3.1 Creating the 389 Directory Server Instance

You create the instance with the dscreate command. It can take a configuration file (*.inf) which defines the instance configuration settings. Alternatively, the command can be run in an interactive mode.

Note
Note: Instance Name

If not specified otherwise, the default instance name is localhost. The instance name cannot be changed after the instance has been created.

Example 5.2 shows an example configuration file that you can use as a starting point. Alternatively, use dscreate create-template to create a template *.inf file. The template is commented and pre-filled, so you can adjust its variables to your needs. For more details, see the man page of dscreate.

  1. If you want to set up a trial instance, start an editor and save the following as /tmp/instance.inf:

    Example 5.2: Basic Instance Configuration File
    # /tmp/instance.inf
    [general]
    config_version = 2
    
    [slapd]
    root_password = YOUR_PASSWORD_FOR_CN=DIRECTORY_MANAGER1
    
    [backend-userroot]
    sample_entries = yes
    suffix = dc=example,dc=com

    1

    Set the root_password to the password for the directory server root user. The password is used for LDAP server administration only.

  2. To create the 389 Directory Server instance from Example 5.2, run:

    tux > sudo dscreate from-file /tmp/instance.inf

    This creates a working LDAP server.

  3. If dscreate should fail, the messages will tell you why. For more details, repeat the command with the -v option:

    tux > sudo dscreate -v from-file /tmp/instance.inf
  4. Check the status of the server with:

    tux > sudo dsctl localhost status
    instance 'Localhost' is running
  5. In case you want to delete the instance later on:

    tux > sudo dsctl localhost remove --do-it

    With this command, you can also remove partially installed or corrupted instances.

5.3.2 Configuring Admin Credentials for Remote/Local Access

For remote or local administration of the 389 Directory Server, you can create a .dsrc configuration file in your home directory. This saves you to type your user name and connection details with every command. Example 5.3 shows an example configuration file for remote administration, whereas Example 5.4 shows one for local administration.

Example 5.3: A .dsrc File for Remote Administration
# cat ~/.dsrc
[localhost]
uri = ldaps://localhost 1
basedn = dc=example,dc=com
binddn = cn=Directory Manager
tls_cacertdir = /etc/dirsrv/slapd-localhost/ 2

1

Needs to point to the LDAP server instance. If not specified otherwise, the default instance name is localhost.

2

If you have configured a certificate yourself, provide the path to the CA certificate here (for remote access with TLS). If you have not configured a certificate yourself, dscreate generates a self-signed certificate which you can trust. Find the certificate at /etc/dirsrv/slapd-localhost/ca.crt. Copy it to a readable location or to the client machine from which you use the ds* commands.

If you want to administer the instance on the same host where the 389 Directory Server runs, use the configuration file in Example 5.4.

Example 5.4: A .dsrc File for Local Administration
# cat ~/.dsrc
[localhost]
# Note that '/' is replaced with '%%2f'.
uri = ldapi://%%2fvar%%2frun%%2fslapd-localhost.socket 1
basedn = dc=example,dc=com
binddn = cn=Directory Manager

1

When using ldapi on the server where the 389 Directory Server instance is running, your UID/GID will be detected. If it is 0/0 (which means you are logged in as root user), the ldapi binds the local root as the directory server root dn (cn=Directory Manager) of the instance. This allows local administration of the server, but also allows you to set a machine-generated password for cn=Directory Manager) that no human knows. Whoever has administrator rights on the server hosting the 389 Directory Server instance, can access the instance as cn=Directory Manager.

5.3.3 Configuring LDAP Users and Groups

Users and groups can be created and managed with the dsidm command. It either runs interactively or you can use it with arguments from the command line.

In the following example, we add two users, wilber and geeko, by specifying their data via command line arguments.

Procedure 5.1: Creating LDAP Users
  1. Create the user wilber:

    tux > sudo dsidm localhost user create --uid \
      --cn wilber --displayName 'Wilber Fox' --uidNumber 1000 --gidNumber 1000 \
      --homeDirectory /home/wilber
  2. To look up a user's distinguished name (fully qualified name to the directory object, which is guaranteed unique):

    tux > sudo dsidm localhost user get wilber
    dn: uid=wilber,ou=people,dc=example,dc=com
    [...]

    The system prompts you for the directory server root user password (unless you configured remote or local access as described in Section 5.3.2, “Configuring Admin Credentials for Remote/Local Access”).

    You need the distinguished name for actions such as changing the password for a user.

  3. To set or change the password for wilber:

    1. tux > sudo dsidm localhost account reset_password \
        uid=wilber,ou=people,dc=example,dc=com

      The system prompts you for the directory server root user password (unless you configured remote or local access as described in Section 5.3.2, “Configuring Admin Credentials for Remote/Local Access”).

    2. Enter the new password for wilber twice.

      If the action was successful, you get the following message:

      reset password for uid=wilber,ou=people,dc=example,dc=com
  4. Create the user geeko:

    tux > sudo dsidm localhost user create --uid \
      --cn geeko --displayName 'Suzanne Geeko' \
      --uidNumber 1001 --gidNumber 1001 --homeDirectory /home/geeko
Procedure 5.2: Creating LDAP Groups and Assigning Users to Them

In the following, we create a group, server_admins, and assign the user wilber to this group.

  1. Create the group:

    tux > sudo dsidm localhost group create

    You will be prompted for a group name:

    Enter value for cn :
  2. Enter the name for the group, for example: server_admins.

  3. Add the user wilber to the group:

    tux > sudo dsidm localhost group add_member server_admins uid=wilber,ou=people,dc=example,dc=com
    added member: uid=wilber,ou=people,dc=example,dc=com
  4. Verify if authentication works:

    tux > sudo ldapwhoami -H ldaps://localhost -D \
      uid=wilber,ou=people,dc=example,dc=com -W -x

    If you are prompted for the LDAP password of wilber, authentication works.

    If the command fails with the following error, you are probably using a self-signed certificate:

    ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)

    In that case, edit /etc/openldap/ldap.conf and add the path to the certificate. For example:

    TLS_CACERT=/etc/dirsrv/slapd-localhost/ca.crt

    Alternatively, include the path to the certificate in the whoami command:

    tux > sudo LDAPTLS_CACERT=/etc/dirsrv/slapd-localhost/ca.crt \
      ldapwhoami -H ldaps://localhost -D \
      uid=wilber,ou=people,dc=example,dc=com -W -x

5.3.4 Setting Up SSSD

SSSD (System Security Services Daemon) is a daemon that communicates with remote identity providers and allows pam and nsswitch to consume that data. SSSD can have multiple back-ends, cache users and groups and provides features like SSH key distributions.

  1. On a separate server, install the sssd package:

    tux > sudo zypper in sssd
  2. Disable and stop the nscd daemon because it conflicts with sssd:

    tux > sudo systemctl disable nscd && systemctl stop nscd
  3. Create the SSSD configuration and restrict the login to the members of the group server_admins that we created in Procedure 5.2:

    tux > sudo dsidm localhost client_config sssd.conf server_admins
  4. Review the output and paste (or redirect) it to /etc/sssd/sssd.conf. If required, edit the configuration file according to your needs.

  5. To configure the certificates on your client, copy ca.crt from the LDAP server to your client:

    tux > sudo mkdir -p /etc/openldap/certs
    cp [...]>/ca.crt /etc/openldap/certs/
    /usr/bin/c_rehash /etc/openldap/certs
  6. Enable and start SSSD:

    tux > sudo systemctl enable sssd
    systemctl start sssd
  7. To make sure SSSD is part of PAM and NSS, follow the instructions in sections Configure PAM (SUSE) and Configure NSS (SUSE) at http://www.port389.org/docs/389ds/howto/howto-sssd.html.

  8. Verify if the client can provide the details for user wilber:

    tux > sudo id wilber
        uid=1000(wilber) gid=100(users) groups=100(users)

    If everything is set up correctly, wilber can access the 389 Directory Server instance via SSH to the machine where you have installed and configured SSSD. However, geeko will fail to do so, because geeko does not belong to the group server_admins that we have configured in Procedure 5.2.

5.4 Configuring LDAP Users and Groups in YaST

  1. Access the YaST user administration with Security and Users › User and Group Management.

  2. To view and manage LDAP users, click the Users tab.

  3. Select Set Filter › LDAP Users and enter the password for Root DN.

  4. Click Add to enter the user configuration. A dialog with four tabs opens:

    1. Specify the user's name, login name, and password in the User Data tab.

    2. Check the Details tab for the group membership, login shell, and home directory of the new user. If necessary, change the default to values that better suit your needs.

    3. Modify or accept the default Password Settings.

    4. Enter the Plug-Ins tab, select the LDAP plug-in, and click Launch to configure additional LDAP attributes assigned to the new user.

  5. Click OK to apply your settings and leave the user configuration.

You can administer groups in a similar way on the Groups tab.

The initial input form of user administration offers LDAP Options. This allows you to apply LDAP search filters to the set of available users. Alternatively open the module for configuring LDAP users and groups by selecting LDAP User and Group Configuration.

5.5 Configuring an LDAP Client with YaST

YaST includes the module LDAP and Kerberos Client that helps define authentication scenarios involving either LDAP or Kerberos.

It can also be used to join Kerberos and LDAP separately. However, in many such cases, using this module may not be the first choice, such as for joining Active Directory (which uses a combination of LDAP and Kerberos). For more information, see Section 4.2, “Configuring an Authentication Client with YaST”.

Start the module by selecting Network Services › LDAP and Kerberos Client.

LDAP and Kerberos Client Window
Figure 5.2: LDAP and Kerberos Client Window

To configure an LDAP client, follow the procedure below:

  1. In the window LDAP and Kerberos Client, click Change Settings.

    Make sure that the tab Use a Directory as Identity Provider (LDAP) is chosen.

  2. Specify one or more LDAP server URLs or host names under Enter LDAP server locations. For security reasons, we recommend to use LDAPS:// URLs only. When specifying multiple addresses, separate them with spaces.

  3. Specify the appropriate LDAP distinguished name (DN) under DN of Search Base. For example, a valid entry could be dc=example,dc=com.

  4. If your LDAP server supports TLS encryption, choose the appropriate security option under Secure LDAP Connection.

    To first ask the server whether it supports TLS encryption and be able to downgrade to an unencrypted connection if it does not, use Secure Communication via StartTLS.

  5. Activate other options as necessary:

    • You can Allow users to authenticate via LDAP and Automatically Create Home Directories on the local computer for them.

    • If you want to cache LDAP entries locally, use Cache LDAP Entries For Faster Response.

      Warning
      Warning: Potential Security Risk with Caching

      Using the cache bears security risks, depending on the used mechanism.

      nscd

      If you define an authorization rule (for example, members of group admin can log in), and you remove a user from that group, the client cache will not see that change until the cache expires or refreshes. So a user whose account has been revoked can still log in for a period of time later.

      sssd

      This caching mechanism constantly checks if group memberships are still valid. Thus the cache risk only exists if the sssd daemon is disconnected from the LDAP server for any reason.

    • Specify the types of data that should be used from the LDAP source, such as Users and Groups, Super-User Commands, and Network Disk Locations (network-shared drives that can be automatically mounted on request).

    • Specify the distinguished name (DN) and password of the user under whose name you want to bind to the LDAP directory in DN of Bind User and Password of the Bind User.

      Otherwise, if the server supports it, you can also leave both text boxes empty to bind anonymously to the server.

      Warning
      Warning: Authentication Without Encryption

      When using authentication without enabling transport encryption using TLS or StartTLS, the password will be transmitted in the clear.

    Under Extended Options, you can additionally configure timeouts for BIND operations.

  6. To check whether the LDAP connection works, click Test Connection.

  7. To leave the dialog, click OK. Then wait for the setup to complete.

    Finally, click Finish.

5.6 Manually Administering LDAP Data

The command line tools provided by the openldap2-client package (like ldapsearch or ldapmodify) can be used for administration of data in the LDAP directory. However, they are low-level tools and hard to use. For details about their use, refer to the respective man pages and documentation.

5.7 For More Information

For more information about 389 Directory Server, see the upstream documentation, available at http://www.port389.org/docs/389ds/documentation.html.