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

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

8.2.3.1.1. Upgrading from a Previous Version

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

8.2.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 8.2.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. There are two ways to change this behavior; if you use the Authentication Configuration tool to configure SSSD, it will reconfigure the default behavior so that SSSD starts when the machine boots. Alternatively, you can use the chkconfig command, as follows:

# chkconfig sssd on

8.2.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 (no quotes required), 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.

The format of the configuration file is described in Section 8.2.8, “SSSD Configuration File Format”

Refer to the sssd.conf(5) manual page for more information on global SSSD configuration options.

8.2.3.2.1. Configuring NSS

SSSD provides a new NSS module, sssd_nss, 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

8.2.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 Red Hat Enterprise Linux—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

8.2.3.2.2.1. Using Custom Home Directories with SSSD

If your LDAP users have home directories that are not in /home, and if your system is configured to create home directories the first time your users log in, then these directories will be created with the wrong permissions. For example, instead of a typical home directory such as /home/<username>, your users might have home directories that include their locale, such as /home/<locale>/<username>. If this is true for your system, the following steps need to be taken (preemptively):

Apply the correct SELinux context and permissions from the /home directory to the home directory that you use on your system. In the example above, the following command would achieve this result (replace the directory names with those that apply to your system):
```
# semanage fcontext -a -e /home /home/locale
```
Ensure the oddjob-mkhomedir package is installed on your system and then re-run the Authentication Configuration tool.
This package provides the pam_oddjob_mkhomedir.so library, which the Authentication Configuration tool will then use to create your custom home directories. You need to use this library to create your home directories, and not the default pam_mkhomedir.so library, because the latter cannot create SELinux labels.
Note
The Authentication Configuration tool will automatically use the pam_oddjob_mkhomedir.so library if it is available. Otherwise, it will default to using pam_mkhomedir.so.

If the preceding steps were not performed before the custom home directories were created, you can use the following commands to correct the permissions and SELinux contexts (again, replace the directory names with those that apply to your system):

# semanage fcontext -a -e /home /home/locale
# restorecon -R -v /home/locale

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

8.2.3.2.3. Configuring Access Control

SSSD provides a rudimentary access control mechanism, offering two solutions based on the value of the access_provider option in the [domain/<NAME>] section in the /etc/sssd/sssd.conf file.

8.2.3.2.3.1. The Simple Access Provider

The first of these solutions is known as the Simple Access Provider, and is based on the implementation of access or deny lists of usernames. To enable the Simple Access Provider, you need to set the access_provider option to simple, and then add usernames as a comma-separated list to either the simple_allow_users or simple_deny_users options.

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

Note

The Local ID provider does not support simple as an access provider.

Access Control Rules

The Simple Access Provider adheres to the following three rules to determine which users should or should not be granted access:

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.

Important

Defining both simple_allow_users and simple_deny_users is a configuration error. If this occurs, SSSD will output an error to the /var/log/sssd/sssd_default.log log file when loading the back end, but continue to start normally. Future versions of SSSD will output an error and fail to start.

8.2.3.2.3.2. The LDAP Access Provider

The second access control solution uses the LDAP server itself as the access provider (access_provider=ldap) and the associated filter option (ldap_access_filter) to specify which users are granted access to the specified host. Note that these two options are codependent; if you use LDAP as your access provider then you must specify a value for the ldap_access_filter option, otherwise all users will be denied access. If you are not using LDAP as your access provider, then the ldap_access_filter option has no effect.

Using the LDAP Access Provider

The following example demonstrates the use of the LDAP Access Provider to grant access to members of the "allowedusers" group in LDAP. 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 LDAP Access Provider-specific options.

[domain/example.com]
access_provider = ldap
ldap_access_filter = memberOf=cn=allowedusers,ou=Groups,dc=example,dc=com

Note

Offline caching for this feature is limited to determining whether or not the user's last online login attempt was successful. If they were granted access during their last login, they will continue to be granted access while offline, and vice-versa.

Refer to the sssd-ldap manual page for more information about using the LDAP Access Provider.

8.2.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 server is unavailable, it then attempts to connect to ldap2.mydomain.org.

If the parameter that specifies which server to connect to for the specific domain (for example, ldap_uri, krb5_kdcip, …) is not specified, the back end defaults to using Use service discovery. Refer to Section 8.2.3.2.4.1, “Using SRV Records with Failover” for more information on service discovery.

Important

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.

Future versions of SSSD will throw an error upon receiving additional ldap_uri entries.

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

For more information on SRV records, refer to RFC 2782.

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

The failover mechanism does not handle DNS A records with multiple IP addresses; instead it only uses the first address. DNS round-robin cannot be used for failover. Further, providing multiple A records does not provide failover. Only the first A record is used, and if a lookup attempt on the first record fails then the system attempts no further lookups. To find multiple servers with a single request, and thus implementing failover, SSSD relies on SRV resource records, as explained in Section 8.2.3.2.4.1, “Using SRV Records with Failover”.

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.