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, CentOS 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 the proper user account. Specifying only the username returns the user for whichever domain comes first in the lookup order.

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 28.3. Identity Store and Authentication Type Combinations

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

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 28.4. General [domain] Configuration Parameters

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 providerThe default value for this parameter is false, which disables enumeration.

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.

    ipa, compatible with FreeIPA version 2.x and Identity Management in Community Enterprise Linux

Parameter Value Format Description
id_provider string Specifies the data provider identity backend to use for this domain. The supported identity backends are:
  • ldap
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.

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.

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.

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.


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:

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

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. 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 . All of the options listed in are also available for LDAP domains.

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

Table 28.5. LDAP Domain Configuration Parameters

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.

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.

    allow requests a certificate, but proceeds normally even if no certificate is given or a bad certificate is given.

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.
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; by default, referrals are enabled.
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.

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.

LDAP Domain Examples

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

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 28.1. A Basic LDAP Domain Configuration

An LDAP domain requires three things:

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

To configure any Active Directory server as an LDAP domain requires two things:

Services for Unix is not supported on 64-bit operating systems.

Example 28.2. An Active Directory 2003 Domain

As with an OpenLDAP or Directory Server domain, Active Directory requires the search base and the LDAP URI of the Active Directory server, but SSSD requires more information about directory entries and the user account to use to connect because of the differences between an Active Directory-style database and an OpenLDAP/Directory Server-style database.

These options are described in the man page for LDAP domain configuration, sssd-ldap(5). 

# Example LDAP domain where the LDAP server is an Active Directory 2003 server.
[domain/AD]
description = LDAP domain with AD server
enumerate = false
;
id_provider = ldap
auth_provider = ldap
ldap_uri = ldap://your.ad.server.com
ldap_schema = rfc2307bis
ldap_search_base = dc=example,dc=com
ldap_default_bind_dn = cn=Administrator,cn=Users,dc=example,dc=com
ldap_default_authtok_type = password
ldap_default_authtok = secret
ldap_user_object_class = person
ldap_user_name = msSFU30Name
ldap_user_uid_number = msSFU30UidNumber
ldap_user_gid_number = msSFU30GidNumber
ldap_user_home_directory = msSFU30HomeDirectory
ldap_user_shell = msSFU30LoginShell
ldap_user_principal = userPrincipalName
ldap_group_object_class = group
ldap_group_name = msSFU30Name
ldap_group_gid_number = msSFU30GidNumber

Example 28.3. A Basic Active Directory 2003 R2 or 2008 Domain

Configuring a Microsoft Active Directory 2003 R2 or 2008 domain is similar, but not identical, to configuring an Active Directory 2003 domain. Using later Active Directory servers requires less group configuration information.

These options are described in the man page for LDAP domain configuration, sssd-ldap(5). 

# Example LDAP domain where the LDAP server is an Active Directory 2003 R2 or an Active Directory 2008 server.
[domain/AD]
description = LDAP domain with AD server
; debug_level = 9
enumerate = false
id_provider = ldap
auth_provider = ldap
chpass_provider = ldap
ldap_uri = ldap://your.ad.server.com
ldap_tls_cacertdir = /etc/openldap/cacerts
ldap_tls_cacert = /etc/openldap/cacerts/test.cer
ldap_search_base = dc=example,dc=com
ldap_default_bind_dn = cn=Administrator,cn=Users,dc=example,dc=com
ldap_default_authtok_type = password
ldap_default_authtok = secret
ldap_pwd_policy = none
ldap_user_object_class = user
ldap_group_object_class = group

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

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.

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 . The sssd-krb5(5) man page has more information about Kerberos configuration options.

Example 28.4. 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 = kerveros.admin.example.com
krb5_auth_timeout = 15

Table 28.6. Kerberos Authentication Configuration Parameters

%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 safelyFor example: 

krb5_ccname_template = FILE:%d/krb5cc_%U_XXXXXX

    %U, the user's login UID

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

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 28.7. Proxy Domain Configuration Parameters

Ensure that the proxy PAM stack does not recursively include pam_sss.so.

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.

proxy_lib_name Specifies which existing NSS library to proxy identity requests through.

This is used to proxy an identity provider.


Example 28.5. 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 28.6. 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, 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 28.7. 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 a /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