Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE Linux Enterprise Server 15

6 LDAP—A Directory Service Edit source

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 such as 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.

6.1 Structure of an LDAP Directory Tree Edit source

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 6.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 RDNs 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 6.1, “Structure of an LDAP Directory”.

Structure of an LDAP Directory
Figure 6.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 upload it to an LDAP server.

Table 6.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 6.1: Commonly Used Object Classes and Attributes

Object Class


Example Entry

Req. Attr.


name components of the domain




organizational unit




person-related data for the intranet or Internet

Geeko Linux


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

Example 6.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 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’


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


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


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


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


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


A brief description of the object class.


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


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


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

6.2 Installing the Software for 389 Directory Server Edit source

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 (as described in Section 6.3) or create a very basic setup with YaST (as described in Section 6.4).

6.3 Manually Configuring a 389 Directory Server Edit source

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

The 389 Directory Server is controlled by three primary commands:


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.


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.


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

6.3.1 Creating the 389 Directory Server Instance Edit source

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 interactively.

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.

To check the name of an instance you have not created yourself, use the dsctl -l command.

Example 6.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 6.2: Basic Instance Configuration File
    # /tmp/instance.inf
    config_version = 2
    sample_entries = yes
    suffix = dc=example,dc=com


    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 6.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.

6.3.2 Using CA Certificates for TLS Edit source

You can manage the CA certificates for 389 Directory Server with the following command line tools: certutil, openssl, and pk12util.

For testing purposes, you can create a self-signed certificate with dscreate. Find the certificate at /etc/dirsrv/slapd-localhost/ca.crt. For remote administration, copy the certificate to a readable location. For production environments, contact a CA authority of your organization's choice and request a server certificate, a client certificate, and a root certificate.

Make sure to meet the following requirements before executing the procedure below:

  • You have a server certificate and a private key to use for the TLS connection.

  • You have set up an NSS (Network Security Services) database (for example, with the certutil command).

Before you can import an existing private key and certificate into the NSS (Network Security Services) database, you need to create a bundle of the private key and the server certificate. This results in a *.p12 file.

Important: *.p12 File and Friendly Name

When creating the PKCS12 bundle, you must encode a friendly name in the *.p12 file.

Make sure to use Server-Cert as friendly name. Otherwise the TLS connection will fail, because the 389 Directory Server searches for this exact string.

As soon as you have imported the *.p12 file in the NSS database, the friendly name cannot be changed any more.

  1. To create the PKCS12 bundle with the required friendly name:

    root # openssl pkcs12 -export -in SERVER.crt \
      -inkey SERVER.key -out SERVER.p12 \
      -name Server-Cert

    Replace SERVER.crt with the server certificate and SERVER.key with the private key to be bundled. With -out, specify the name of the *.p12 file. Use -name to set the friendly name to use, Server-Cert.

  2. After you have created the required SERVER.p12 file, import the file into your NSS database:

    pk12util -i SERVER.p12 -d PATH_TO_NSS_DB

6.3.3 Configuring Admin Credentials for Remote/Local Access Edit source

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

Example 6.3: A .dsrc File for Remote Administration
# cat ~/.dsrc
uri = ldaps://REMOTE_URI 1
basedn = dc=example,dc=com
binddn = cn=Directory Manager
tls_cacertdir = PATH_TO_CERTDIR 2


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


Path to the certificate, at a readable location or on 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 6.4.

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


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.

6.3.4 Configuring LDAP Users and Groups Edit source

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 6.1: Creating LDAP Users
  1. Create the user wilber:

    tux > sudo dsidm localhost user create --uid wilber \
      --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 6.3.3, “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 \

      The system prompts you for the directory server root user password (unless you configured remote or local access as described in Section 6.3.3, “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 6.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

6.3.5 Setting Up SSSD Edit source

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 6.2:


    The memberOf plugin needs to be enabled, so that clients can log in and authorise.

    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 https://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 6.2.

6.4 Setting Up a 389 Directory Server with YaST Edit source

You can use YaST to quickly create a very basic setup of the 389 Directory Server.

6.4.1 Creating an 389 Directory Server Instance with YaST Edit source

  1. In YaST, click Network Services › Create New Directory Server. Alternatively, start the module from command line with yast2 ldap-server.

    In the window that opens, you need to fill in all mandatory text fields.

  2. Enter the Fully qualified domain name of the 389 Directory Server. It must be resolvable from the host.

  3. In Directory server instance name, enter a local name for the LDAP server instance.

    Note: Instance Name

    The instance name cannot be changed after the instance has been created. If you plan for only one LDAP server, use the default instance name localhost. However, if you plan to host multiple LDAP servers, use meaningful names for the individual instances.

  4. In Directory suffix, enter the base domain name of the LDAP tree. It is your domain name split by component. For example, example.com becomes dc=example,dc=com.

  5. In the mandatory security options, enter the password for the directory manager (LDAP's root/admin account) and repeat the password in the next step. The password must be at least 8 characters long.

  6. To run 389 Directory Server with a CA certificate, specify both of the following options:

    1. Enter the path to the Server TLS certificate authority in PEM format, with which the server certificates have been signed.

    2. Enter the path to the Server TLS certificate and key in PKCS12 format with friendly name "Server-Cert". The *.p12 file contains the server's private key and certificate. These must have been signed by the CA in PEM format that you have specified above. The friendly name must be Server-Cert, see Section 6.3.2, “Using CA Certificates for TLS” for details.

      If you do not specify a CA certificate here, a self-signed certificate will be created automatically. After the instance has been created, find the related files in /etc/dirsrv/slapd-INSTANCENAME.

  7. If you are ready to create the instance, click OK.

    YaST displays a message whether the creation was successful and where to find the log files.

The setup with YaST provides only a very basic configuration of the 389 Directory Server. To fine-tune more settings, see Section 6.3, “Manually Configuring a 389 Directory Server” or the documentation mentioned in Section 6.6, “For More Information”.

6.4.2 Configuring an LDAP Client with YaST Edit source

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 5.1, “Configuring an Authentication Client with YaST”.

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

LDAP and Kerberos Client Window
Figure 6.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: Potential Security Risk with Caching

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


      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.


      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: 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.

6.5 Manually Administering LDAP Data Edit source

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.

6.6 For More Information Edit source

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

Print this page