Product SiteDocumentation Site

Chapter 15. Authentication Configuration

15.1. The System Security Services Daemon (SSSD)
15.1.1. What is SSSD?
15.1.2. SSSD Features
15.1.3. Setting Up SSSD
15.1.4. Configuring Services
15.1.5. Configuring Domains

15.1. The System Security Services Daemon (SSSD)

This chapter describes how to install and configure the System Security Services Daemon (SSSD), and how to use the features that it provides. It also provides information on the types of services that it supports and how to configure them, and it introduces and describes the most important configuration options. Sample configuration files are also provided to help you optimize your deployment.

15.1.1. What is SSSD?

The System Security Services Daemon (SSSD) is a service which provides access to different identity and authentication providers. You can configure SSSD to use an LDAP identity provider with LDAP authentication, or an LDAP identity provider with Kerberos authentication. SSSD is also extensible; you can configure it to use new identity sources and authentication mechanisms should they arise.

15.1.2. SSSD Features

15.1.2.1. Performing Offline Authentication

One of the primary benefits of SSSD is offline authentication. This solves the case of users having a separate corporate account and a local machine account because of the common requirement to implement a Virtual Private Network (VPN).
SSSD can cache remote identities and authentication credentials. This means that you can still authenticate with these remote identities even when a machine is offline. In an SSSD system, you only need to manage one account.

15.1.2.2. Reducing Server Load

The use of SSSD also helps to reduce the load on identification servers. For example, using nss_ldap, every client application that needs to request user information opens its own connection to the LDAP server. Managing these multiple connections can lead to a heavy load on the LDAP server. In an SSSD system, only the SSSD Data Provider process actually communicates with the LDAP server, reducing the load to one connection per client system.

15.1.2.3. Specifying Multiple Domains

You can use SSSD to specify multiple domains of the same type. Compare this to an nsswitch.conf file configuration, with which you can only request user information from a single server of any particular type (LDAP, NIS, etc.). With SSSD, you can create multiple domains of the same, or of different types of identity provider.
Beginning with version 0.6.0, SSSD maintains a separate database file for each domain. This means that each domain has its own cache, and in the event that problems occur and maintenance is necessary, it is very easy to purge the cache for a single domain, by stopping sssd and deleting the corresponding cache file. These cache files are stored in the /var/lib/sss/db/ directory.
All cache files are named according to the domain that they represent, for example cache_DOMAINNAME.ldb.

15.1.2.4. Differentiating Like-named Users

SSSD supports the differentiation of like-named users in different domains. For example, you can differentiate the user kate in the ldap.example.com domain from the user kate in the ldap.myhome.com domain. You can use SSSD to make requests using fully-qualified usernames. If you request information for kate, you will receive the information from whichever domain is listed first in the look-up order. If you request information for kate@ldap.myhome.com, however, you will receive the correct user information.

15.1.2.5. Integrating with Other Products

Beyond the offline authentication, multiple domain management and other features already described, SSSD is also designed to integrate with and enhance the functionality of IPA clients. In an environment with the latest version of IPA installed, SSSD provides added functionality, including host-based access control, and password migration from an LDAP-only environment into the LDAP/Kerberos 5 environment employed by IPA.

15.1.3. Setting Up SSSD

This section describes how to install SSSD, how to run the service, and how to configure it for each type of supported information provider.

15.1.3.1. Installing SSSD

Run the following command to install SSSD and any dependencies, including the SSSD Client:
# yum install sssd
SSSD requires very few dependencies and should install very quickly, depending on the speed of your network connection.
15.1.3.1.1. Upgrading from a Previous Version
Beginning with version 0.6.0, SSSD uses a different and simplified configuration file format, referred to as "Version 2". Consequently, existing configuration files need to be migrated to the new format. SSSD provides a script to automate the migration process.
SSSD checks the value of the config_file_version parameter during the startup procedure. If this value is correct, the installation continues,otherwise it aborts.
The revised format of the configuration file is described in Section 15.1.5.6, “SSSD Configuration File Format”
Upgrading Using RPM Packages
If you are upgrading using RPM packages, the script will run automatically when you upgrade to the new version. This will upgrade the /etc/sssd/sssd.conf file to the new format, and copy the existing version to /etc/sssd/sssd.conf.bak.
Upgrading Manually
It may be necessary to run the upgrade script manually, either because you built SSSD from source files, or because you are using a platform that does not support the use of RPM packages. The synopsis for the script is as follows:

upgrade_config.py [ -f INFILE ] [ -o OUTFILE ] [ -verbose ] [ --no-backup ]

  • -f INFILE — the configuration file to upgrade. If not specified, this defaults to /etc/sssd/sssd.conf
  • -o OUTFILE — the name of the upgraded configuration file. If not specified, this defaults to /etc/sssd/sssd.conf
  • -verbose — produce more verbose output during the upgrade process
  • --no-backup — do not produce a back-up file. If not specified, this defaults to INFILE.bak
15.1.3.1.2. Starting and Stopping SSSD

Note

Before you start SSSD for the first time, you need to configure at least one domain. Refer to Section 15.1.5, “Configuring Domains” for information on how to configure an SSSD domain.
You can use either the service command or the /etc/init.d/sssd script to control SSSD. For example, run the following command to start sssd:
# service sssd start
By default, SSSD is configured not to start automatically. You can use the chkconfig command to change this behavior. For example, run the following command to configure SSSD to start when the machine boots:
# chkconfig sssd on

15.1.3.2. Configuring SSSD

The global configuration of SSSD is stored in the /etc/sssd/sssd.conf file. This file consists of various sections, each of which contains a number of key/value pairs. Some keys accept multiple values; use commas to separate multiple values for such keys. This configuration file uses data types of string, integer and Boolean (with values of TRUE or FALSE). Comments are indicated by either a hash sign (#) or a semicolon (;) in the first column. The following example illustrates some of this syntax: 
[section]
# Keys with single values
key1 = value
key2 = val2

# Keys with multiple values
key10 = val10,val11

Note

You can use the -c (or --config) parameter on the command line to specify a different configuration file for SSSD.
Refer to the sssd.conf(5) manual page for more information on global SSSD configuration options.
15.1.3.2.1. Configuring NSS
SSSD provides a new NSS module, nss_sss, so that you can configure your system to use SSSD to retrieve user information. Edit the /etc/nsswitch.conf file for your system to use the sss name database. For example: 
passwd: files sss
group: files sss
15.1.3.2.2. Configuring PAM

Warning

Use extreme care when changing your PAM configuration. A mistake in the PAM configuration file can lock you out of the system completely. Always back up your configuration files before performing any changes, and keep a session open so that you can revert any changes you make should the need arise.
To enable your system to use SSSD for PAM, you need to edit the default PAM configuration file. On Fedora—based systems, this is the /etc/pam.d/system-auth file. Edit this file to reflect the following example, and then restart sssd: 
#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth        required      pam_env.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        requisite     pam_succeed_if.so uid >= 500 quiet
auth        sufficient    pam_sss.so use_first_pass
auth        required      pam_deny.so

account     required      pam_unix.so broken_shadow
account     sufficient    pam_localuser.so
account     sufficient    pam_succeed_if.so uid < 500 quiet
account [default=bad success=ok user_unknown=ignore] pam_sss.so
account     required      pam_permit.so

password    requisite     pam_cracklib.so try_first_pass retry=3
password    sufficient    pam_unix.so sha512 shadow nullok try_first_pass use_authtok
password    sufficient    pam_sss.so use_authtok
password    required      pam_deny.so

session     required      pam_mkhomedir.so umask=0022 skel=/etc/skel/
session     optional      pam_keyinit.so revoke
session     required      pam_limits.so
session     [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
session     sufficient    pam_sss.so
session     required      pam_unix.so

Need to validate the following para.

You can also use authconfig to set up your PAM configuration to use SSSD. Select Use LDAP Authentication, and then replace pam_ldap.so with pam_sss.so in all files below /etc/pam.d or in the /etc/pam.conf file.
Using include Statements in PAM Configurations
Recent PAM implementations allow you to use include statements in PAM configurations. For example: 
...
session     include      system-auth
session     optional     pam_console.so
...

Note

In the preceding example, if a sufficient condition from system-auth returns PAM_SUCCESS, pam_console.so will not be executed.
15.1.3.2.3. Configuring Access Control
SSSD provides a rudimentary access control mechanism based on the implementation of access or deny lists of usernames. This mechanism is known as the Simple Access Provider, and is configured in the [domain/<NAME>] sections of the /etc/sssd/sssd.conf file. To enable the Simple Access Provider, you need to set the access_provider parameter to simple, and then add usernames as a comma-separated list to either the simple_allow_users or simple_deny_users parameters.
Using the Simple Access Provider
By using the Simple Access Provider, you can continue to support a number of network logins to maintain common network accounts on company or department laptops, but you might want to restrict the use of a particular laptop to one or two users. This means that even if a different user authenticated successfully against the same authentication provider, the Simple Access Provider would prevent that user from gaining access.
The following example demonstrates the use of the Simple Access Provider to grant access to two users. This example assumes that SSSD is correctly configured and example.com is one of the domains specified in the [sssd] section, and only shows the Simple Access Provider-specific options. 
[domain/example.com]
access_provider = simple
simple_allow_users = user1, user2
Access Control Rules
The Simple Access Provider adheres to three simple rules to determine which users should or should not be granted access, as follows:
  • If both lists are empty, access is granted
  • If simple_allow_users is set, only users from this list are allowed access. This setting supersedes the simple_deny_users list (which would be redundant).
  • If the simple_allow_users list is empty, users are allowed access unless they appear in the simple_deny_users list.

Note

It is a configuration error if both simple_allow_users and simple_deny_users are defined.
15.1.3.2.4. Configuring Failover
The failover feature allows back ends to automatically switch to a different server if the primary server fails. These servers are entered as a case-insensitive, comma-separated list in the [domain/<NAME>] sections of the /etc/sssd/sssd.conf file, and listed in order of preference. This list can contain any number of servers.
For example, if you have configured a native LDAP domain, you could specify the following as your ldap_uri values: 
ldap_uri = ldap://ldap0.mydomain.org, ldap://ldap1.mydomain.org, ldap://ldap2.mydomain.org
In this configuration, ldap://ldap0.mydomain.org functions as the primary server. If this server fails, the SSSD failover mechanism first attempts to connect to ldap1.mydomain.org, and if that is unavailable, it then attempts to connect to ldap2.mydomain.org. If the primary server is restored, the failover mechanism automatically restores operations to use that server instead of any failover servers.

Warning

Do not use multiple ldap_uri parameters to specify your failover servers. The failover servers must be entered as a comma-separated list of values for a single ldap_uri parameter. If you enter multiple ldap_uri parameters, SSSD only recognizes the last entry.
15.1.3.2.4.1. Using SRV Records with Failover
SSSD also supports the use of SRV records in its failover configuration. This means that you can specify a server that is later resolved into a list of specific servers using SRV requests. The priority and weight attributes of SRV records provide further opportunity for specifying which servers should be contacted first in the event that the primary server fails.
For every service with which you want to use service discovery, you need to add a special DNS record to your DNS server using the following form: 
_service._protocol._domain TTL priority weight port hostname
A typical configuration would contain multiple such records, each with a different priority (for failover) and different weights (for load balancing).
The client then makes an SRV DNS query to retrieve a list of host names, their priorities, and weights. These queries are of the form _service._protocol._domain, for example, _ldap._tcp._redhat.com. The client then sorts this list according to the priorities and weights, and connects to the first server in this sorted list.
15.1.3.2.4.2. How the Failover Mechanism Works
The failover mechanism distinguishes between machines and services. The back end first tries to resolve the hostname of a given machine; if this resolution attempt fails, the machine is considered offline. No further attempts are made to connect to this machine for any other service. If the resolution attempt succeeds, the back end tries to connect to a service on this machine. If the service connection attempt fails, then only this particular service is considered offline and the back end automatically switches over to the next service. The machine is still considered online and might still be tried for another service.
Further connection attempts are made to machines or services marked as offline after a specified period of time; this is currently hard coded to 30 seconds. If there are no more machines to try, the back end as a whole switches to offline mode, and then attempts to reconnect every 30 seconds.

15.1.4. Configuring Services

Individual pieces of SSSD functionality are provided by special SSSD services that are started and stopped together with SSSD. The services provided by SSSD have their own configuration sections. The [sssd] section also lists the services that are active and should be started when sssd starts within the services directive.
SSSD currently provides several services:
  • NSS — An NSS provider service that answers NSS requests from the nss_sss module.
  • PAM — A PAM provider service that manages a PAM conversation through the pam_sss PAM module.
  • monitor — A special service that monitors all other SSSD services, and starts or restarts them as needed. Its options are specified in the [sssd] section of the /etc/sssd/sssd.conf configuration file.

15.1.4.1. Configuration Options

The following sections cover the most important SSSD configuration options. Refer to the sssd.conf(5) manual page that ships with SSSD for information on all the available configuration options.
15.1.4.1.1. General Configuration Options
  • debug_level (integer)
    Sets the debug level for a particular service. This is a per-service setting (that is, it can appear in any of the [service/<NAME>] sections in the SSSD configuration file).
  • reconnection_retries (integer)
    In the event of a data provider crash or restart, this specifies the number of times that a service should attempt to reconnect.

    Note

    If a DNS lookup fails to return an IPv4 address for a hostname, SSSD attempts to look up an IPv6 address before returning a failure. Note that this only ensures that the async resolver identifies the correct address; there is currently a bug in the LDAP code that prevents SSSD from connecting to an LDAP server over IPv6. This is being investigated separately.
15.1.4.1.2. NSS Configuration Options
Use the following options to configure the Name Service Switch (NSS) service. Refer to the sssd.conf(5) manual page for full details about each option.
  • enum_cache_timeout (integer)
    Specifies for how long nss_sss should cache enumerations (requests for information about all users).
  • entry_cache_nowait_percentage (integer)
    Specifies for how long nss_sss should return cached entries before initiating an out-of-band cache refresh (0 disables this feature).
    You can configure the entry cache to automatically update entries in the background if they are requested beyond a percentage of the entry_cache_timeout value for the domain.
    Valid values for this option are 0-99 and represent a percentage of the entry_cache_timeout value for each domain.
  • entry_negative_timeout (integer)
    Specifies for how long nss_sss should cache negative cache hits (that is, queries for invalid database entries, like nonexistent ones) before asking the back end again.
  • filter_users, filter_groups (string)
    Exclude certain users from being fetched from the sss NSS database. This is particularly useful for system accounts such as root.
  • filter_users_in_groups (Boolean)
    Specifies that filtered users do not appear in group memberships. If not specified, defaults to TRUE.
15.1.4.1.3. PAM Configuration Options
Use these options to configure the Pluggable Authentication Module (PAM) service.
  • offline_credentials_expiration (integer)
    If the authentication provider is offline, specifies for how long we should allow cached log ins (in days). If not specified, defaults to 0 (no limit).

15.1.5. Configuring Domains

A domain is a database of user information. SSSD can use more than one domain at the same time, but at least one must be configured for SSSD to start. Using SSSD domains, it is possible to use several LDAP servers providing several unique namespaces. You can specify not only where users' identity information is stored, but how users authenticate against each of the specified domains.
SSSD supports the following identity and authentication combinations:
  • LDAP/LDAP
    This combination uses an LDAP back end as both the identity and authentication provider.
  • LDAP/KRB5
    This combination uses an LDAP back end as the identity provider, and uses Kerberos to provide authentication.
  • proxy
    Specifying a proxy identity or authentication provider uses an existing NSS library or customized PAM stack, but takes advantage of the SSSD caching mechanism.
The following example assumes that SSSD is correctly configured and FOO is one of the domains in the [sssd] section. This example shows only the configuration of Kerberos authentication; it does not include any identity provider. 
[domain/FOO]
auth_provider = krb5
krb5_kdcip = 192.168.1.1
krb5_realm = EXAMPLE.COM

15.1.5.1. Domain Configuration Options

You can add new domain configurations to the [domain/<NAME>] sections of the /etc/sssd/sssd.conf file, and then add the list of domains to the domains attribute of the [sssd] section, in the order you want them to be queried.
15.1.5.1.1. General Domain Configuration Options
You can use the following configuration options in a domain configuration section:
  • min_id,max_id (integer)
    Specifies the UID limits for the domain. If a domain contains entries that are outside these limits, they are ignored.

    Note

    If min_id is unspecified, it defaults to 1000 for any back end.
  • enumerate (Boolean)
    Specifies whether or not to enumerate (list) the users and groups of a domain.
    Enumeration means that the entire set of available users and groups on the remote source is cached on the local machine. When enumeration is disabled, users and groups are only cached as they are requested. For performance reasons, it is recommended that you disable enumeration for domains with many users and groups.
    The default value for this parameter is FALSE. Set this value to TRUE to enable enumeration of users and groups of a domain.
  • timeout (integer)
    Specifies the timeout in seconds for this particular domain.
    This is used to ensure that the backend process is alive and capable of answering requests. The default value for this parameter is 10 seconds. Raising this timeout might prove useful for slower back ends, such as distant LDAP servers.

    Note

    If you set timeout = 0, SSSD reverts to the default value; you cannot force a timeout value of zero, because this would force the sssd daemon into a loop.
  • cache_credentials (Boolean)
    Specifies whether or not to store user credentials in the local SSSD domain database cache.
    The default value for this parameter is FALSE. You should set this value to TRUE for domains other than local if you want to enable offline authentication.
  • id_provider (string)
    Specifies the data provider identity back end to use for this domain. Currently supported identity back ends are:
    • proxy — Support a legacy NSS provider (for example, nss_nis).

      Note

      SSSD needs to know which legacy NSS library to load in order to start successfully. If you set id_provider to proxy, ensure that you also specify a value for proxy_lib_name. Refer to Section 15.1.5.1.2, “Proxy Configuration Options” for information on this attribute.
    • local — SSSD internal local provider.
    • ldap — LDAP provider.
  • entry_cache_timeout (integer)
    Specifies for how long the domain's data provider should cache positive cache hits (that is, queries for valid database entries) before asking the database again.
  • use_fully_qualified_names (Boolean)
    Specifies whether or not requests to this domain require fully-qualified domain names.
    If set to TRUE, all requests to this domain must use fully-qualified domain names. It also means that the output from the request displays the fully-qualified name.
    The ability to restrict requests in this way means that if you know you have multiple domains with conflicting usernames, then there is no doubt about which username the query will resolve.
    Consider the following examples, in which the IPA domain database contains a user named ipauser01, and the use_fully_qualified_names attribute is set to TRUE: 
    # getent passwd ipauser01
[no output]
# getent passwd ipauser01@IPA
ipauser01@IPA:x:937315651:937315651:ipauser01:/home/ipauser01:/bin/sh
    In the following examples, using the same IPA domain and user, the use_fully_qualified_names attribute is set to FALSE: 
    # getent passwd ipauser01
ipauser01:x:937315651:937315651:ipauser01:/home/ipauser01:/bin/sh
# getent passwd ipauser01@IPA
ipauser01:x:937315651:937315651:ipauser01:/home/ipauser01:/bin/sh

    Note

    With use_fully_qualified_names set to FALSE, you can continue to use the fully-qualified name in your requests, but only the simplified version is displayed in the output.
    SSSD can only parse name@domain, not name@realm. You can, however, use the same name for both your domain and your realm.
  • auth_provider (string)
    The authentication provider used for the domain. Currently supported authentication providers are:
    • ldap — for native LDAP authentication. Refer to sssd-ldap(5) for more information on configuring LDAP.
    • krb5 — for Kerberos authentication. Refer to sssd-krb5(5) for more information on configuring Kerberos.
    • proxy — for relaying authentication to some other PAM target.
15.1.5.1.2. Proxy Configuration Options
  • proxy_pam_target (string)
    This option is only used when the auth_provider option is set to proxy, and specifies the proxy target that PAM proxies to.
    This option has no default value. If proxy authentication is required, you need to specify your own PAM target. This corresponds to a file containing PAM stack information in the system's default PAM configuration directory. On Fedora-based systems, this is the /etc/pam.d/ directory.
  • proxy_lib_name (string)
    This option is only used when the id_provider option is set to proxy, and specifies which existing NSS library to proxy identity requests through.
    This option has no default value. You need to manually specify an existing library to take advantage of this option. For example, set this value to nis to use the existing libnss_nis.so file.
The following sections contain examples of how to configure different types of domains.

15.1.5.2. Configuring a Native LDAP Domain

A native LDAP domain requires a running LDAP server against which to authenticate. The client configuration is stored in the /etc/sssd/sssd.conf file.
SSSD does not support authentication over an unencrypted channel. Consequently, if you want to authenticate against an LDAP server, TLS/SSL is required. If the LDAP server is used only as an identity provider, an encrypted channel is not needed.
How to Authenticate Against a Native LDAP Domain
Edit your /etc/sssd/sssd.conf file to reflect the following example: 
# A native LDAP domain
[domain/LDAP]
enumerate = true
cache_credentials = TRUE

id_provider = ldap
auth_provider = ldap
ldap_schema = rfc2307
chpass_provider = ldap

ldap_uri = ldap://ldap.mydomain.org
ldap_user_search_base = dc=mydomain,dc=org
tls_reqcert = demand
ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt

Note

The ldap_schema attribute can be set to either rfc2307, which uses the memberuid attribute for group membership, or to rfc2307bis, which uses the member attribute. Changes to this setting only affect how SSSD determines the groups to which a user belongs; there is no negative effect on the actual user data. If you do not know the correct value for this attribute, consult your System Administrator.
Refer to the sssd-ldap(5) manual page for a full description of all the parameters that apply to a native LDAP domain.

15.1.5.3. Setting Up Authentication Against a Kerberos Server

In order to set up Kerberos authentication, you need to know the address of your KDC and the Kerberos domain. The client configuration is stored in the /etc/sssd/sssd.conf file.
How to Authenticate Against a Kerberos Domain
Edit your /etc/sssd/sssd.conf file to reflect the following example: 
# A domain with identities provided by LDAP and authentication by Kerberos
[domain/KRBDOMAIN]
enumerate = false
id_provider = ldap
chpass_provider = krb5
ldap_uri = ldap://ldap.mydomain.org
ldap_user_search_base = dc=mydomain,dc=org
tls_reqcert = demand
ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt

auth_provider = krb5
krb5_kdcip = 192.168.1.1
krb5_realm = EXAMPLE.COM
krb5_changepw_principle = kadmin/changepw
krb5_ccachedir = /tmp
krb5_ccname_template = FILE:%d/krb5cc_%U_XXXXXX
krb5_auth_timeout = 15
Refer to the sssd-krb5(5) manual page for a full description of all the parameters that apply to configuring Kerberos authentication.

15.1.5.4. Using the SSSD Management Tools

The following sections explain the basics of using the SSSD management tools to create and manage users and groups in SSSD domains.

Note

You can only use the SSSD command-line tools to manage users and groups in the LOCAL domain. The tools for managing users and groups in other domains are provided by the shadow-utils package.
15.1.5.4.1. Working with Users
How to Add a New User
Use the following command to add a new user to the local domain:
# sss_useradd newUser01
Refer to the sss_useradd manual page for information on all the options that apply to this command. Also refer to the sss_userdel and sss_usermod manual pages for information on how to delete and modify existing SSSD users.
How to Request User Information
If you configured NSS to use the SSS domain, you can use the following command to request user information: 
# getent passwd newUser01@LOCAL
newUser01:x:508:508:newUser01:/home/newUser01:/bin/bash
How to Change a User's Password
Use the following procedure to change a user's password: 
# passwd newUser01
        Changing password for user newUser01.
New password:
Retype new password:
passwd: all authentication tokens updated successfully.
15.1.5.4.2. Working with Groups
You can use the SSSD tools to add groups to the local domain. These groups are compatible with POSIX groups, with the additional feature that they can contain other groups as members. Any users who are members of child groups are automatically members of all parent groups. The opposite relationship is also true; if you remove a child group, then the members of that group are automatically removed from all parent groups.
How to Add a New Group
Use the following command to add a new group to the local domain:
# sss_groupadd newGroup01
Refer to the sss_groupadd, sss_groupdel, and sss_groupmod manual pages for information on the options that apply to adding, deleting, and modifying SSSD groups.
How to Request Group Information
If you configured NSS to use the local sss domain, you can use a simple # getent group command to request information for all groups. The following is an abbreviated display of the output of such a request: 
# getent group
root:x:0:root
bin:x:1:root,bin,daemon
daemon:x:2:root,bin,daemon
.
.
.
testuser1:x:500:
testuser2:x:501:
testuser3:x:502:
15.1.5.4.2.1. Working with Nested Groups
This section provides a brief introduction to the use of nested groups, and how they can be used to reduce administrative overhead for system administrators.
The following is a simple example of setting up nested groups. You can use the getent command to view the existing groups and their members: 
GroupA:*:511:UserA
GroupB:*:512:UserB
GroupC:*:516:UserC
GroupD:*:517:UserD
GroupE:*:518:UserE
Each group contains a single user, and does not contain any other groups as members. You can use the sss_groupmod command to add GroupB to GroupA:
# sss_groupmod -a GroupA GroupB
This also has the effect of adding the members of GroupB to GroupA, as can be seen below: 
GroupA:*:511:UserA,UserB
GroupB:*:512:UserB
GroupC:*:516:UserC
GroupD:*:517:UserD
GroupE:*:518:UserE
This behavior is true for every group membership that you implement. If you continue this for each of the above groups, the following membership results: 
GroupA:*:511:UserA,UserB,UserC,UserD,UserE
GroupB:*:512:UserB,UserC,UserD,UserE
GroupC:*:516:UserC,UserD,UserE
GroupD:*:517:UserD,UserE
GroupE:*:518:UserE
If you remove a group from an environment that implements nested groups, you also affect the user membership that it has created. For example, if you remove GroupC from the previous example, the following group and user membership results: 
GroupA:*:511:UserA,UserB
GroupB:*:512:UserB
GroupD:*:517:UserD,UserE
GroupE:*:518:UserE

15.1.5.5. Troubleshooting

This section lists some of the issues you may encounter when implementing SSSD, the possible causes of these issues, and how to resolve them. If you find further issues that are not covered here, refer to the We Need Feedback section in the Preface for information on how to file a bug report.
15.1.5.5.1. Using SSSD Log Files
SSSD uses a number of log files to report information about its operation, and this information can help to resolve issues in the event of SSSD failure or unexpected behavior. The default location for these log files on Fedora—based systems is the /var/log/sssd/ directory.
SSSD produces a log file for each back end (that is, one log file for each domain specified in the /etc/sssd/sssd.conf file), as well as an sssd_pam.log and an sssd_nss.log file. This level of granularity can help you to quickly isolate and resolve any errors or issues you might experience with SSSD.
You should also examine the /var/log/secure file, which logs authentication failures and the reason for the failure. For example, if you see Reason 4: System Error reported against any failure, you should increase the debug level of the log files.
Producing More Verbose Log Files
If you are unable to identify and resolve any problems with SSSD after inspection of the default log files, you can configure SSSD to produce more verbose files. You can set the debug_level option in the /etc/sssd/sssd.conf for the domain that is causing concern, and then restart SSSD. Refer to the sssd.conf(5) manual page for more information on how to set the debug_level for a specfic domain.
All log files include timestamps on debug messages by default. This can make it easier to understand any errors that may occur, why they occurred, and how to address them. If necessary, you can disable these timestamps by setting the appropriate parameter to 0 in the /etc/sssd/sssd.conf file: 
--debug-timestamps=0
15.1.5.5.2. Problems with SSSD Configuration
  • SSSD fails to start
    • SSSD requires at least one properly configured domain before the service will start. Without such a domain, you might see the following error message when trying to start SSSD with the following command:
      # sssd -d4 
      [sssd] [ldb] (3): server_sort:Unable to register control with rootdse!

[sssd] [confdb_get_domains] (0): No domains configured, fatal error!
[sssd] [get_monitor_config] (0): No domains configured.
      You can ignore the "Unable to register control with rootdse!" message, as it is erroneous. The other messages, however, indicate that SSSD is unable to locate any properly configured domains.
      Edit your /etc/sssd/sssd.conf file and ensure you have at least one properly configured domain, and then try to start SSSD.
    • SSSD requires at least one available service provider before it will start. With no available service providers, you might see the following error message when trying to start SSSD with the following command:
      # sssd -d4 
      [sssd] [ldb] (3): server_sort:Unable to register control with rootdse!

[sssd] [get_monitor_config] (0): No services configured!
      You can ignore the "Unable to register control with rootdse!" message, as it is erroneous. The other message, however, indicates that SSSD is unable to locate any available service providers.
      Edit your /etc/sssd/sssd.conf file and ensure you have at least one available service providers, and then try to start SSSD.

      Important

      SSSD requires that service providers be configured as a comma-separated list in a single services entry in the /etc/sssd/sssd.conf file. If services are listed in multiple entries, only the last entry is recognized by SSSD.
    • Refer to the sssd.conf(5) manual page for more options that might assist in troubleshooting issues with SSSD.
15.1.5.5.3. Problems with SSSD Service Configuration
15.1.5.5.3.1. Problems with NSS
This section describes some common problems with NSS, their symptoms, and how to resolve them.
  • NSS fails to return user information
    • Ensure that NSS is running
      # service sssd status
      This command should return results similar to the following: 
      sssd (pid 21762) is running...
    • Ensure that you have correctly configured the [nss] section of the /etc/sssd/sssd.conf file. For example, ensure that you have not misconfigured the filter_users or filter_groups attributes. Refer to the NSS configuration options section of the sssd.conf(5) manual page for information on how to configure these attributes.
    • Ensure that you have included nss in the list of services that sssd should start
    • Ensure that you have correctly configured the /etc/nsswitch.conf file. Refer to the section Section 15.1.3.2.1, “Configuring NSS” for information on how to correctly configure this file.
15.1.5.5.3.2. Problems with PAM
This section describes some common problems with PAM, their symptoms, and how to resolve them.
  • Setting the password for the local SSSD user prompts twice for the password
    When attempting to change a local SSSD user's password, you might see output similar to the following: 
    [root@clientF11 tmp]# passwd user1000
Changing password for user user1000.
New password:
Retype new password:
New Password:
Reenter new Password:
passwd: all authentication tokens updated successfully.
    This is the result of an incorrect PAM configuration. Refer to Section 15.1.3.2.2, “Configuring PAM”, and ensure that the use_authtok option is correctly configured in your /etc/pam.d/system-auth file.
15.1.5.5.4. Problems with SSSD Domain Configuration
  • NSS returns incorrect user information
    • If your search for user information returns incorrect data, ensure that you do not have conflicting usernames in separate domains. If you use multiple domains, it is recommended that you set the use_fully_qualified_domains attribute to TRUE in the /etc/sssd/sssd.conf file.
15.1.5.5.5. Additional Resources
15.1.5.5.5.1. Manual Pages
SSSD ships with a number of manual pages, all of which provide additional information about specfic aspects of SSSD, such as configuration files, commands, and available options. SSSD currently provides the following manual pages:
  • sssd.conf(5)
  • sssd-ipa(5)
  • sssd-krb5(5)
  • sssd-ldap(5)
  • sssd(8)
  • sssd_krb5_locator_plugin(8)
  • sss_groupadd(8)
  • sss_groupdel(8)
  • sss_groupmod(8)
  • sss_useradd(8)
  • sss_userdel(8)
  • sss_usermod(8)
  • pam_sss(8)
You should refer to these manual pages for detailed information about all aspects of SSSD, its configuration, and associated tools and commands.
15.1.5.5.5.2. Mailing Lists
You can subscribe to the SSSD mailing list to follow and become involved in the development of SSSD, or to ask questions about any issues you may be experiencing with your SSSD deployment.
Visit https://fedorahosted.org/mailman/listinfo/sssd-devel to subscribe to this mailing list.

15.1.5.6. SSSD Configuration File Format

The following listing describes the current version (Version 2) of the SSSD configuration file format. 
[sssd]
config_file_version = 2
services = nss, pam
domains = mybox.example.com, ldap.example.com, ipa.example.com, nis.example.com
# sbus_timeout = 300

[nss]
nss_filter_groups = root
nss_filter_users = root
nss_entry_cache_timeout = 30
nss_enum_cache_timeout = 30

[domain/mybox.example.com]
domain_type = local
enumerate = true
min_id = 1000
# max_id = 2000

local_default_shell = /bin/bash
local_default_homedir = /home

# Possible overrides
# id_provider = local
# auth_provider = local
# authz_provider = local
# passwd_provider = local

[domain/ldap.example.com]
domain_type = ldap
server = ldap.example.com, ldap3.example.com, 10.0.0.2
# ldap_uri = ldaps://ldap.example.com:9093
# ldap_use_tls = ssl
ldap_user_search_base = ou=users,dc=ldap,dc=example,dc=com
enumerate = false

# Possible overrides
# id_provider = ldap
# id_server = ldap2.example.com
# auth_provider = krb5
# auth_server = krb5.example.com
# krb5_realm = KRB5.EXAMPLE.COM

[domain/ipa.example.com]
domain_type = ipa
server = ipa.example.com, ipa2.example.com
enumerate = false

# Possible overrides
# id_provider = ldap
# id_server = ldap2.example.com
# auth_provider = krb5
# auth_server = krb5.example.com
# krb5_realm = KRB5.EXAMPLE.COM

[domain/nis.example.com]
id_provider = proxy
proxy_lib = nis
auth_provider = proxy
proxy_auth_target = nis_pam_proxy