Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

30.4. Creating Domains

SSSD recognizes domains, which are associated with the different identity servers. Domains are a combination of an identity provider and an authentication method. SSSD works with LDAP identity providers (including OpenLDAP, Red Hat Directory Server, and Microsoft Active Directory) and can use native LDAP authentication or Kerberos authentication.
As long as they belong to different domains, SSSD can recognize different users with the same username. For example, SSSD can successfully authenticate both jsmith in the ldap.example.com domain and jsmith in the ldap.otherexample.com domain. SSSD allows requests using fully-qualified domain names, so requesting information for jsmith@ldap.example.com returns the proper user account. Specifying only the username returns the user for whichever domain comes first in the lookup order.

Note

SSSD has a filter_users option, which excludes the specified users from being returned in a search.
Configuring a domain defines both where user information is stored and how those users are allowed to authenticate to the system. The possible combinations are listed in Table 30.3, “Identity Store and Authentication Type Combinations”.

Table 30.3. Identity Store and Authentication Type Combinations

Identification Provider Authentication Provider
LDAP LDAP
LDAP Kerberos
proxy LDAP
proxy Kerberos
proxy proxy

30.4.1. General Rules and Options for Configuring a Domain

A domain configuration defines the identity provider, the authentication provider, and any specific configuration to access the information in those providers. There are two types of identity providers — LDAP and proxy —three types of authentication providers — LDAP, Kerberos, and proxy. The identity and authentication providers can be configured in any combination in a domain entry.
Along with the domain entry itself, the domain name must be added to the list of domains that SSSD will query. For example:
domains = LOCAL,Name

[domain/Name]
id_provider = type
auth_provider = type
provider_specific = value
global = value
global attributes are available to any type of domain, such as cache and time out settings. Each identity and authentication provider has its own set of required and optional configuration parameters.

Table 30.4. General [domain] Configuration Parameters

Parameter Value Format Description
id_provider string Specifies the data provider identity backend to use for this domain. The supported identity backends are:
  • ldap
  • ipa, compatible with FreeIPA version 2.x
  • proxy for a legacy NSS provider, such as nss_nis. Using a proxy ID provider also requires specifying the legacy NSS library to load to start successfully, set in the proxy_lib_name option.
  • local, the SSSD internal local provider
auth_provider string Sets the authentication provider used for the domain. The default value for this option is the value of id_provider. The supported authentication providers are ldap, ipa, krb5 (Kerberos), proxy, and none.
min_id,max_id integer Optional. Specifies the UID and GID range for the domain. If a domain contains entries that are outside that range, they are ignored. The default value for min_id is 1; the default value for max_id is 0, which is unlimited.

Important

The default min_id value is the same for all types of identity provider. If LDAP directories are using UID numbers that start at one, it could cause conflicts with users in the local /etc/passwd file. To avoid these conflicts, set min_id to 1000 or higher as possible.
enumerate Boolean Optional. Specifies whether to 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.

Warning

When enumeration is enabled, reinitializing a client results in a complete refresh of the entire set of available users and groups from the remote source. Similarly, when SSSD is connected to a new server, the entire set of available users and groups from the remote source is pulled and cached on the local machine. In a domain with a large number of clients connected to a remote source, this refresh process can harm the network performance because of frequent queries from the clients. If the set of available users and groups is large enough, it degrades client performance as well.
The default value for this parameter is false, which disables enumeration.
cache_credentials Boolean Optional. Specifies whether to store user credentials in the local SSSD domain database cache. The default value for this parameter is false. Set this value to true for domains other than the LOCAL domain to enable offline authentication.
entry_cache_timeout integer Optional. Specifies how long, in seconds, SSSD should cache positive cache hits. A positive cache hit is a successful query.
use_fully_qualified_names Boolean Optional. Specifies whether 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. Restricting requests to fully-qualified user names allows SSSD to differentiate between domains with users with conflicting usernames.
If use_fully_qualified_names is set to false, it is possible to use the fully-qualified name in the requests, but only the simplified version is displayed in the output.
SSSD can only parse names based on the domain name, not the realm name. The same name can be used for both domains and realms, however.

30.4.2. Configuring an LDAP Domain

An LDAP domain simply means that SSSD uses an LDAP directory as the identity provider (and, optionally, also as an authentication provider). SSSD supports several major directory services:
  • Red Hat Directory Server
  • OpenLDAP
  • Microsoft Active Directory 2008, with Subsystem for UNIX-based Applications

Note

DNS service discovery allows the LDAP backend to find the appropriate DNS servers to connect to automatically using a special DNS query.

30.4.2.1. Parameters for Configuring an LDAP Domain

An LDAP directory can function as both an identity provider and an authentication provider. The configuration requires enough information to identify and connect to the user directory in the LDAP server, but the way that those connection parameters are defined is flexible.
Other options are available to provide more fine-grained control, like specifying a user account to use to connect to the LDAP server or using different LDAP servers for password operations. The most common options are listed in Table 30.5, “LDAP Domain Configuration Parameters”. All of the options listed in Section 30.4.1, “General Rules and Options for Configuring a Domain” are also available for LDAP domains.

Note

Many other options are listed in the man page for LDAP domain configuration, sssd-ldap(5).

Table 30.5. LDAP Domain Configuration Parameters

Parameter Description
ldap_uri Gives a comma-separated list of the URIs of the LDAP servers to which SSSD will connect. The list is given in order of preference, so the first server in the list is tried first. Listing additional servers provides failover protection. This can be detected from the DNS SRV records if it is not given.
ldap_search_base Gives the base DN to use for performing LDAP user operations.
ldap_tls_reqcert Specifies how to check for SSL server certificates in a TLS session. There are four options:
  • never disables requests for certificates.
  • allow requests a certificate, but proceeds normally even if no certificate is given or a bad certificate is given.
  • try requests a certificate and proceeds normally if no certificate is given, If a bad certificate is given, the session terminates.
  • demand and hard are the same option. This requires a valid certificate or the session is terminated.
The default is hard.
ldap_tls_cacert Gives the full path and file name to the file that contains the CA certificates for all of the CAs that SSSD recognizes. SSSD will accept any certificate issued by these CAs.
This uses the OpenLDAP system defaults if it is not given explicitly.
ldap_referrals Sets whether SSSD will use LDAP referrals, meaning forwarding queries from one LDAP database to another. SSSD supports database-level and subtree referrals. For referrals within the same LDAP server, SSSD will adjust the DN of the entry being queried. For referrals that go to different LDAP servers, SSSD does an exact match on the DN. Setting this value to true enables referrals. This is the default.
ldap_schema Sets what version of schema to use when searching for user entries. This can be either rfc2307 or rfc2307bis. The default is rfc2307.
In RFC 2307, group objects use a multi-valued attribute, memberuid, which lists the names of the users that belong to that group. In RFC 2307bis, group objects use the member attribute, which contains the full distinguished name (DN) of a user or group entry. RFC 2307bis allows nested groups usning the member attribute. Because these different schema use different definitions for group membership, using the wrong LDAP schema with SSSD can affect both viewing and managing network resources, even if the appropriate permissions are in place.
For example, with RFC 2307bis, all groups are returned when using nested groups or primary/secondary groups.
$ id
uid=500(myserver) gid=500(myserver) groups=500(myserver),510(myothergroup)
If SSSD is using RFC 2307 schema, only the primary group is returned.
This setting only affects how SSSD determines the group members. It does not change the actual user data.
ldap_search_timeout Sets the time, in seconds, that LDAP searches are allowed to run before they are canceled and cached results are returned. This defaults to five when the enumerate value is false and defaults to 30 when enumerate is true.
When an LDAP search times out, SSSD automatically switches to offline mode.
ldap_network_timeout Sets the time, in seconds, SSSD attempts to poll an LDAP server after a connection attempt fails. The default is six seconds.
ldap_opt_timeout Sets the time, in seconds, to wait before aborting synchronous LDAP operations if no response is received from the server. This option also controls the timeout when communicating with the KDC in case of a SASL bind. The default is five seconds.

30.4.2.2. LDAP Domain Example

The LDAP configuration is very flexible, depending on your specific environment and the SSSD behavior. These are some common examples of an LDAP domain, but the SSSD configuration is not limited to these examples.

Note

Along with creating the domain entry, add the new domain to the list of domains for SSSD to query in the sssd.conf file. For example:
domains = LOCAL,LDAP1,AD,PROXYNIS

Example 30.1. A Basic LDAP Domain Configuration

An LDAP domain requires three things:
  • An LDAP server
  • The search base
  • A way to establish a secure connection
The last item depends on the LDAP environment. SSSD requires a secure connection since it handles sensitive information. This connection can be a dedicated TLS/SSL connection or it can use Start TLS.
Using a dedicated TLS/SSL connection simply uses an LDAPS connection to connect to the server and is therefore set as part of the ldap_uri option:
# An LDAP domain
[domain/LDAP]
enumerate = false
cache_credentials = true

id_provider = ldap
auth_provider = ldap

ldap_uri = ldaps://ldap.example.com:636
ldap_search_base = dc=example,dc=com
Using Start TLS requires a way to input the certificate information to establish a secure connection dynamically over an insecure port. This is done using the ldap_id_use_start_tls option to use Start TLS and then ldap_tls_cacert to identify the CA certificate which issued the SSL server certificates.
# An LDAP domain
[domain/LDAP]
enumerate = false
cache_credentials = true

id_provider = ldap
auth_provider = ldap

ldap_uri = ldap://ldap.example.com
ldap_search_base = dc=example,dc=com
ldap_id_use_start_tls = true
ldap_tls_reqcert = demand
ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt

30.4.2.3. Active Directory Domain Example

For SSSD to work with an Active Directory domain, both the Active Directory domain and the local system have to be configured specially to communicate with one another.

Note

The Microsoft Active Directory documentation has complete procedures for configuring the Active Directory domain.
  1. Using authconfig, set the Linux client to use Active Directory as its LDAP identity provider. For example:
    authconfig --enableldap --enableldapauth --ldapserver=ldap://ad.example.com:389 --enablekrb5 --krb5realm AD-REALM.EXAMPLE.COM --krb5kdc ad-kdc.example.com:88 --krb5adminserver ad-kdc.example.com:749 --update
    The authconfig command is described in Section 29.4, “Command Line Version”.
  2. Create the Active Directory Domain Services role.
  3. Add the Identity Management for UNIX service to the Active Directory Domain Services role. Use the Unix NIS domain as the domain name in the configuration.
  4. On the Active Directory server, create a new Computer object with the name of the Linux client.
    1. In the Administrative Tools menu, select the Active Directory Users and Computers application.
    2. Expand the Active Directory root object, such as ad.example.com.
    3. Right-click Computers, and select the New and the Computer item.
    4. Enter the name for the Linux client, such as rhel-server, and click OK.
    5. Expand the Computers object.
    6. Right-click the rhel-server object, and select Properties.
    7. In the UNIX Attributes, enter the name of the Linux NIS domain and the IP address of the Linux server.
      Click OK.
  5. From the command prompt on the Active Directory server, create a machine account, password, and UPN for the Linux host principal.
    C:\> setspn -A host/rhel-server.example.com@AD-REALM.EXAMPLE.COM rhel-server
    Registering ServicePrincipalNames for CN=rhel server,CN=Computers,DC=ad,DC=example,DC=com
            host/rhel server.example.com@AD-REALM.EXAMPLE.COM
    Updated object						
    	
    C:\> setspn -L rhel-server 
    Registered ServicePrincipalNames for CN=rhel server,CN=Computers,DC=ad,DC=example,DC=com:
            host/rhel server.example.com@AD-REALM.EXAMPLE.COM
    
    C:\> ktpass /princ host/rhel-server.example.com@AD-REALM.EXAMPLE.COM /out rhel-server.keytab /crypto all /ptype KRB5_NT_PRINCIPAL -desonly /mapuser AD\rhel-server$ +rndPass
    
    Targeting domain controller: 
        ad.example.com
    Using legacy password setting method
    Successfully mapped host/rhel server.redhat.com 
    ... 8< ...
  6. Copy the keytab from the Active Directory server to the Linux client, and save it as /etc/krb5.keytab.
  7. On the Linux system, reset the permissions and owner for the keytab file.
    [root@rhel-server ~]# chown root:root /etc/krb5.keytab 
    	
    [root@rhel-server ~]# chmod 0600 /etc/krb5.keytab
  8. Restore the SELinux file permissions for the keytab.
    [root@rhel-server ~]# restorecon /etc/krb5.keytab
  9. Verify that the host can connect to the Active Directory domain.
    [root@rhel-server ~]# kinit -k -t /etc/krb5.keytab host/rhel-server.example.com@AD-REALM.EXAMPLE.COM
  10. On the Active Directory server, create a a group for the Linux users.
    1. Create a new group named unixusers.
    2. Open the unixusers group and open the Unix Attributes tab.
    3. Configure the Unix settings:
      • The NIS domain
      • The UID
      • The login shell, to /bin/bash
      • The home directory, to /home/aduser
      • The primary group name, to unixusers
  11. Then, configure the SSSD domain on the Linux machine.

    Example 30.2. An Active Directory 2008 Domain

    [root@rhel-server ~]# vim /etc/sssd/sssd.conf
    
    [sssd]
    config_file_version = 2
    domains = ad.example.com
    services = nss, pam
    
    [nss]
    
    [pam]
    
    [domain/ad.example.com]
    cache_credentials = true
    enumerate = false
    
    id_provider = ldap
    auth_provider = krb5
    chpass_provider = krb5
    access_provider = ldap
    
    ldap_sasl_mech = GSSAPI
    ldap_sasl_authid = host/rhel-server.example.com@AD-REALM.EXAMPLE.COM 
    
    
    ldap_schema = rfc2307bis
    
    ldap_user_search_base = ou=user accounts,dc=ad,dc=example,dc=com
    ldap_user_object_class = user
    ldap_user_home_directory = unixHomeDirectory
    ldap_user_principal = userPrincipalName
    ldap_user_name = sAMAccountName
    
    ldap_group_search_base = ou=groups,dc=ad,dc=example,dc=com
    ldap_group_object_class = group
    
    ldap_access_order = expire
    ldap_account_expire_policy = ad
    ldap_force_upper_case_realm = true
    ldap_disable_referrals = true
    
    #krb5_server = server.ad.example.com
    krb5_realm = AD-REALM.EXAMPLE.COM
    These options are described in the man page for LDAP domain configuration, sssd-ldap(5).
  12. Restart SSSD.
    [root@rhel-server ~]# service sssd restart

30.4.2.4. Using IP Addresses in Certificate Subject Names

Using an IP address in the ldap_uri option instead of the server name may cause the TLS/SSL connection to fail. TLS/SSL certificates contain the server name, not the IP address. However, the subject alternative name field in the certificate can be used to include the IP address of the server, which allows a successful secure connection using an IP address.
  1. Convert an existing certificate into a certificate request. The signing key (-signkey) is the key of the issuer of whatever CA originally issued the certificate. If this is done by an external CA, it requires a separate PEM file; if the certificate is self-signed, then this is the certificate itself. For example:
    openssl x509 -x509toreq -in old_cert.pem -out req.pem -signkey key.pem
    With a self-signed certificate:
    openssl x509 -x509toreq -in old_cert.pem -out req.pem -signkey old_cert.pem
  2. Edit the /etc/pki/tls/openssl.cnf configuration file to include the server's IP address under the [ v3_ca ] section:
    subjectAltName = IP:10.0.0.10
  3. Use the generated certificate request to generate a new self-signed certificate with the specified IP address:
    openssl x509 -req -in req.pem -out new_cert.pem -extfile ./openssl.cnf -extensions v3_ca -signkey old_cert.pem
    The -extensions option sets which extensions to use with the certificate. For this, it should be v3_ca to load the appropriate section.
  4. Copy the private key block from the old_cert.pem file into the new_cert.pem file to keep all relevant information in one file.
When creating a certificate through the certutil utility provided by the nss-tools package, note that certutil supports DNS subject alternative names for certificate creation only.

30.4.3. Configuring Kerberos Authentication with a Domain

Both LDAP and proxy identity providers can use a separate Kerberos domain to supply authentication. Configuring a Kerberos authentication provider requires the key distribution center (KDC) and the Kerberos domain. All of the principal names must be available in the specified identity provider; if they are not, SSSD constructs the principals using the format username@REALM.

Note

Kerberos can only provide authentication; it cannot provide an identity database.
SSSD assumes that the Kerberos KDC is also a Kerberos kadmin server. However, production environments commonly have multiple, read-only replicas of the KDC and only a single kadmin server. Use the krb5_kpasswd option to specify where the password changing service is running or if it is running on a non-default port. If the krb5_kpasswd option is not defined, SSSD tries to use the Kerberos KDC to change the password.
The basic Kerberos configuration options are listed in Table 30.6, “Kerberos Authentication Configuration Parameters”. The sssd-krb5(5) man page has more information about Kerberos configuration options.

Example 30.3. Basic Kerberos Authentication

# 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.example.com
ldap_search_base = dc=example,dc=com
ldap-tls_reqcert = demand
ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt

auth_provider = krb5
krb5_server = 192.168.1.1, kerberos.example.com
krb5_realm = EXAMPLE.COM
krb5_kpasswd = kerberos.admin.example.com
krb5_auth_timeout = 15

Table 30.6. Kerberos Authentication Configuration Parameters

Parameter Description
chpass_provider Specifies which service to use for password change operations. This is assumed to be the same as the authentication provider. To use Kerberos, set this to krb5.
krb5_server Gives a comma-separated list of IP addresses or hostnames of Kerberos servers to which SSSD will connect. The list is given in order of preference, so the first server in the list is tried first. Listing additional servers provides failover protection.
When using service discovery for KDC or kpasswd servers, SSSD first searches for DNS entries that specify UDP as the connection protocol, and then falls back to TCP.
krb5_realm Identifies the Kerberos realm served by the KDC.
krb5_lifetime Requests a Kerberos ticket with the specified lifetime in seconds (s), minutes (m), hours (h) or days (d).
krb5_renewable_lifetime Requests a renewable Kerberos ticket with a total lifetime that is specified in seconds (s), minutes (m), hours (h) or days (d).
krb5_renew_interval Sets the time, in seconds, for SSSD to check if tickets should be renewed. Tickets are renewed automatically once they exceed half their lifetime. If this option is missing or set to zero, then automatic ticket renewal is disabled.
krb5_store_password_if_offline Sets whether to store user passwords if the Kerberos authentication provider is offline, and then to use that cache to request tickets when the provider is back online. The default is false, which does not store passwords.
krb5_kpasswd Lists alternate Kerberos kadmin servers to use if the change password service is not running on the KDC.
krb5_ccname_template Gives the directory to use to store the user's credential cache. This can be templatized, and the following tokens are supported:
  • %u, the user's login name
  • %U, the user's login UID
  • %p, the user's principal name
  • %r, the realm name
  • %h, the user's home directory
  • %d, the value of the krb5ccache_dir parameter
  • %P, the process ID of the SSSD client.
  • %%, a literal percent sign (%)
  • XXXXXX, a string at the end of the template which instructs SSSD to create a unique filename safely
For example:
krb5_ccname_template = FILE:%d/krb5cc_%U_XXXXXX
krb5_ccachedir Specifies the directory to store credential caches. This can be templatized, using the same tokens as krb5_ccname_template, except for %d and %P. If %u, %U, %p, or %h are used, then SSSD creates a private directory for each user; otherwise, it creates a public directory.
krb5_auth_timeout Gives the time, in seconds, before an online authentication or change password request is aborted. If possible, the authentication request is continued offline. The default is 15 seconds.

30.4.4. Configuring a Proxy Domain

A proxy with SSSD is just a relay, an intermediary configuration. SSSD connects to its proxy service, and then that proxy loads the specified libraries. This allows SSSD to use some resources that it otherwise would not be able to use. For example, SSSD only supports LDAP and Kerberos as authentication providers, but using a proxy allows SSSD to use alternative authentication methods like a fingerprint scanner or smart card.

Table 30.7. Proxy Domain Configuration Parameters

Parameter Description
proxy_pam_target Specifies the target to which PAM must proxy as an authentication provider. The PAM target is a file containing PAM stack information in the default PAM directory, /etc/pam.d/.
This is used to proxy an authentication provider.

Important

Ensure that the proxy PAM stack does not recursively include pam_sss.so.
proxy_lib_name Specifies which existing NSS library to proxy identity requests through.
This is used to proxy an identity provider.

Example 30.4. Proxy Identity and Kerberos Authentication

The proxy library is loaded using the proxy_lib_name parameter. This library can be anything as long as it is compatible with the given authentication service. For a Kerberos authentication provider, it must be a Kerberos-compatible library, like NIS.
[domain/PROXY_KRB5]
auth_provider = krb5
krb5_server = 192.168.1.1
krb5_realm = EXAMPLE.COM

id_provider = proxy
proxy_lib_name = nis
enumerate = true
cache_credentials = true

Example 30.5. LDAP Identity and Proxy Authentication

The proxy library is loaded using the proxy_pam_target parameter. This library must be a PAM module that is compatible with the given identity provider. For example, this uses a PAM fingerprint module with LDAP:
[domain/LDAP_PROXY]
id_provider = ldap
ldap_uri = ldap://example.com
ldap_search_base = dc=example,dc=com

auth_provider = proxy
proxy_pam_target = sssdpamproxy
enumerate = true
cache_credentials = true
After the SSSD domain is configured, make sure that the specified PAM files are configured. In this example, the target is sssdpamproxy, so create a /etc/pam.d/sssdpamproxy file and load the PAM/LDAP modules:
auth          required      pam_frprint.so
account       required      pam_frprint.so
password      required      pam_frprint.so
session       required      pam_frprint.so

Example 30.6. Proxy Identity and Authentication

SSSD can have a domain with both identity and authentication proxies. The only configuration given then are the proxy settings, proxy_pam_target for the authentication PAM module and proxy_lib_name for the service, like NIS or LDAP.
This example illustrates a possible configuration, but this is not a realistic configuration. If LDAP is used for identity and authentication, then both the identity and authentication providers should be set to the LDAP configuration, not a proxy.
[domain/PROXY_PROXY]
auth_provider = proxy
id_provider = proxy
proxy_lib_name = ldap
proxy_pam_target = sssdproxyldap
enumerate = true 
cache_credentials = true
Once the SSSD domain is added, then update the system settings to configure the proxy service:
  1. Create an /etc/pam.d/sssdproxyldap file which requires the pam_ldap.so module:
    auth          required      pam_ldap.so
    account       required      pam_ldap.so
    password      required      pam_ldap.so
    session       required      pam_ldap.so
  2. Make sure the nss-pam-ldap package is installed.
    [root@server ~]# yum install nss-pam-ldap
  3. Edit the /etc/nslcd.conf file, the configuration file for the LDAP name service daemon, to contain the information for the LDAP directory:
    uid nslcd
    gid ldap
    uri ldaps://ldap.example.com:636
    base dc=example,dc=com
    ssl on
    tls_cacertdir /etc/openldap/cacerts