| SSSD.CONF(5) | File Formats and Conventions | SSSD.CONF(5) |
NAME¶
sssd.conf - the configuration file for SSSD
FILE FORMAT¶
The file has an ini-style syntax and consists of sections and parameters. A section begins with the name of the section in square brackets and continues until the next section begins. An example of section with single and multi-valued parameters:
[section] key = value key2 = value2,value3
The data types used are string (no quotes needed), integer and bool (with values of “TRUE/FALSE”).
A comment line starts with a hash sign (“#”) or a semicolon (“;”). Inline comments are not supported.
All sections can have an optional description parameter. Its function is only as a label for the section.
sssd.conf must be a regular file, owned by root and only root may read from or write to the file.
CONFIGURATION SNIPPETS FROM INCLUDE DIRECTORY¶
The configuration file sssd.conf will include configuration snippets using the include directory conf.d. This feature is available if SSSD was compiled with libini version 1.3.0 or later.
Any file placed in conf.d that ends in “.conf” and does not begin with a dot (“.”) will be used together with sssd.conf to configure SSSD.
The configuration snippets from conf.d have higher priority than sssd.conf and will override sssd.conf when conflicts occur. If several snippets are present in conf.d, then they are included in alphabetical order (based on locale). Files included later have higher priority. Numerical prefixes (01_snippet.conf, 02_snippet.conf etc.) can help visualize the priority (higher number means higher priority).
The snippet files require the same owner and permissions as sssd.conf. Which are by default root:root and 0600.
GENERAL OPTIONS¶
Following options are usable in more than one configuration sections.
Options usable in all sections¶
debug_level (integer)
Please note that each SSSD service logs into its own log file. Also please note that enabling “debug_level” in the “[sssd]” section only enables debugging just for the sssd process itself, not for the responder or provider processes. The “debug_level” parameter should be added to all sections that you wish to produce debug logs from.
In addition to changing the log level in the config file using the “debug_level” parameter, which is persistent, but requires SSSD restart, it is also possible to change the debug level on the fly using the sss_debuglevel(8) tool.
Currently supported debug levels:
0, 0x0010: Fatal failures. Anything that would prevent SSSD from starting up or causes it to cease running.
1, 0x0020: Critical failures. An error that doesn't kill SSSD, but one that indicates that at least one major feature is not going to work properly.
2, 0x0040: Serious failures. An error announcing that a particular request or operation has failed.
3, 0x0080: Minor failures. These are the errors that would percolate down to cause the operation failure of 2.
4, 0x0100: Configuration settings.
5, 0x0200: Function data.
6, 0x0400: Trace messages for operation functions.
7, 0x1000: Trace messages for internal control functions.
8, 0x2000: Contents of function-internal variables that may be interesting.
9, 0x4000: Extremely low-level tracing information.
9, 0x20000: Performance and statistical data, please note that due to the way requests are processed internally the logged execution time of a request might be longer than it actually was.
10, 0x10000: Even more low-level libldb tracing information. Almost never really required.
To log required bitmask debug levels, simply add their numbers together as shown in following examples:
Example: To log fatal failures, critical failures, serious failures and function data use 0x0270.
Example: To log fatal failures, configuration settings, function data, trace messages for internal control functions use 0x1310.
Note: The bitmask format of debug levels was introduced in 1.7.0.
Default: 0x0070 (i.e. fatal, critical and serious failures; corresponds to setting 2 in decimal notation)
debug (integer)
debug_timestamps (bool)
Default: true
debug_microseconds (bool)
Default: false
debug_backtrace_enabled (bool)
In case SSSD is run with debug_level less than 9, everything is logged to a ring buffer in memory and flushed to a log file on any error up to and including `min(0x0040, debug_level)` (i.e. if debug_level is explicitly set to 0 or 1 then only those error levels will trigger backtrace, otherwise up to 2).
Feature is only supported for `logger == files` (i.e. setting doesn't have effect for other logger types).
Default: true
Options usable in SERVICE and DOMAIN sections¶
timeout (integer)
Default: 10
SPECIAL SECTIONS¶
The [sssd] section¶
Individual pieces of SSSD functionality are provided by special SSSD services that are started and stopped together with SSSD. The services are managed by a special service frequently called “monitor”. The “[sssd]” section is used to configure the monitor as well as some other important options like the identity domains.
Section parameters
config_file_version (integer)
services
Supported services: nss, pam , sudo , autofs , ssh , pac , ifp
By default, all services are disabled and the administrator must enable the ones allowed to be used by executing: "systemctl enable sssd-@service@.socket".
reconnection_retries (integer)
Default: 3
domains
re_expression (string)
Each domain can have an individual regular expression configured. For some ID providers there are also default regular expressions. See DOMAIN SECTIONS for more info on these regular expressions.
full_name_format (string)
The following expansions are supported:
%1$s
%2$s
%3$s
Each domain can have an individual format string configured. See DOMAIN SECTIONS for more info on this option.
monitor_resolv_conf (boolean)
Default: true
try_inotify (boolean)
There are some limited situations where it is preferred that we should skip even trying to use inotify. In these rare cases, this option should be set to 'false'
Default: true on platforms where inotify is supported. False on other platforms.
Note: this option will have no effect on platforms where inotify is unavailable. On these platforms, polling will always be used.
krb5_rcache_dir (string)
This option accepts a special value __LIBKRB5_DEFAULTS__ that will instruct SSSD to let libkrb5 decide the appropriate location for the replay cache.
Default: Distribution-specific and specified at build-time. (__LIBKRB5_DEFAULTS__ if not configured)
user (string)
This option does not work when running socket-activated services, as the user set up to run the processes is set up during compilation time. The way to override the systemd unit files is by creating the appropriate files in /etc/systemd/system/. Keep in mind that any change in the socket user, group or permissions may result in a non-usable SSSD. The same may occur in case of changes of the user running the NSS responder.
Default: not set, process will run as root
default_domain_suffix (string)
Please note that if this option is set all users from the primary domain have to use their fully qualified name, e.g. user@domain.name, to log in. Setting this option changes default of use_fully_qualified_names to True. It is not allowed to use this option together with use_fully_qualified_names set to False. One exception from this rule are domains with “id_provider=files” that always try to match the behaviour of nss_files and therefore their output is not qualified even when the default_domain_suffix option is used.
Default: not set
override_space (string)
Please note it is a configuration error to use a replacement character that might be used in user or group names. If a name contains the replacement character SSSD tries to return the unmodified name but in general the result of a lookup is undefined.
Default: not set (spaces will not be replaced)
certificate_verification (string)
no_ocsp
soft_ocsp
ocsp_dgst
Default: sha1 (to allow compatibility with RFC5019-compliant responder)
no_verification
partial_chain
ocsp_default_responder=URL
ocsp_default_responder_signing_cert=NAME
crl_file=/PATH/TO/CRL/FILE
soft_crl
Unknown options are reported but ignored.
Default: not set, i.e. do not restrict certificate verification
disable_netlink (boolean)
The SSSD state changes caused by netlink events may be undesirable and can be disabled by setting this option to 'true'
Default: false (netlink changes are detected)
enable_files_domain (boolean)
Default: false
domain_resolution_order
Please, note that when this option is set the output format of all commands is always fully-qualified even when using short names for input , for all users but the ones managed by the files provider. In case the administrator wants the output not fully-qualified, the full_name_format option can be used as shown below: “full_name_format=%1$s” However, keep in mind that during login, login applications often canonicalize the username by calling getpwnam(3) which, if a shortname is returned for a qualified input (while trying to reach a user which exists in multiple domains) might re-route the login attempt into the domain which uses shortnames, making this workaround totally not recommended in cases where usernames may overlap between domains.
Default: Not set
implicit_pac_responder (boolean)
Default: true
core_dumpable (boolean)
Default: true
SERVICES SECTIONS¶
Settings that can be used to configure different services are described in this section. They should reside in the [$NAME] section, for example, for NSS service, the section would be “[nss]”
General service configuration options¶
These options can be used to configure any service.
reconnection_retries (integer)
Default: 3
fd_limit
Default: 8192 (or limits.conf "hard" limit)
client_idle_timeout
Default: 60, KCM: 300
offline_timeout (integer)
new_delay = Minimum(old_delay * 2, offline_timeout_max) + random[0...offline_timeout_random_offset]
The offline_timeout default value is 60. The offline_timeout_max default value is 3600. The offline_timeout_random_offset default value is 30. The end result is amount of seconds before next retry.
Note that the maximum length of each interval is defined by offline_timeout_max (apart of random part).
Default: 60
offline_timeout_max (integer)
A value of 0 disables the incrementing behaviour.
The value of this parameter should be set in correlation to offline_timeout parameter value.
With offline_timeout set to 60 (default value) there is no point in setting offlinet_timeout_max to less than 120 as it will saturate instantly. General rule here should be to set offline_timeout_max to at least 4 times offline_timeout.
Although a value between 0 and offline_timeout may be specified, it has the effect of overriding the offline_timeout value so is of little use.
Default: 3600
offline_timeout_random_offset (integer)
new_delay = Minimum(old_delay * 2, offline_timeout_max) + random[0...offline_timeout_random_offset]
This parameter controls the value of the random offset used for the above equation. Final random_offset value will be random number in range:
[0 - offline_timeout_random_offset]
A value of 0 disables the random offset addition.
Default: 30
responder_idle_timeout
Default: 300
cache_first
Default: false
NSS configuration options¶
These options can be used to configure the Name Service Switch (NSS) service.
enum_cache_timeout (integer)
Default: 120
entry_cache_nowait_percentage (integer)
For example, if the domain's entry_cache_timeout is set to 30s and entry_cache_nowait_percentage is set to 50 (percent), entries that come in after 15 seconds past the last cache update will be returned immediately, but the SSSD will go and update the cache on its own, so that future requests will not need to block waiting for a cache update.
Valid values for this option are 0-99 and represent a percentage of the entry_cache_timeout for each domain. For performance reasons, this percentage will never reduce the nowait timeout to less than 10 seconds. (0 disables this feature)
Default: 50
entry_negative_timeout (integer)
Default: 15
local_negative_timeout (integer)
Default: 14400 (4 hours)
filter_users, filter_groups (string)
NOTE: The filter_groups option doesn't affect inheritance of nested group members, since filtering happens after they are propagated for returning via NSS. E.g. a group having a member group filtered out will still have the member users of the latter listed.
Default: root
filter_users_in_groups (bool)
Default: true
override_homedir (string)
%u
%U
%d
%f
%l
%P
%o
%h
%H
%%
This option can also be set per-domain.
example:
override_homedir = /home/%u
Default: Not set (SSSD will use the value retrieved from LDAP)
Please note, the home directory from a specific override for the user, either locally (see sss_override(8)) or centrally managed IPA id-overrides, has a higher precedence and will be used instead of the value given by override_homedir.
homedir_substring (string)
Default: /home
fallback_homedir (string)
The available values for this option are the same as for override_homedir.
example:
fallback_homedir = /home/%u
Default: not set (no substitution for unset home directories)
override_shell (string)
Default: not set (SSSD will use the value retrieved from LDAP)
allowed_shells (string)
1. If the shell is present in “/etc/shells”, it is used.
2. If the shell is in the allowed_shells list but not in “/etc/shells”, use the value of the shell_fallback parameter.
3. If the shell is not in the allowed_shells list and not in “/etc/shells”, a nologin shell is used.
The wildcard (*) can be used to allow any shell.
The (*) is useful if you want to use shell_fallback in case that user's shell is not in “/etc/shells” and maintaining list of all allowed shells in allowed_shells would be to much overhead.
An empty string for shell is passed as-is to libc.
The “/etc/shells” is only read on SSSD start up, which means that a restart of the SSSD is required in case a new shell is installed.
Default: Not set. The user shell is automatically used.
vetoed_shells (string)
shell_fallback (string)
Default: /bin/sh
default_shell
Default: not set (Return NULL if no shell is specified and rely on libc to substitute something sensible when necessary, usually /bin/sh)
get_domains_timeout (int)
Default: 60
memcache_timeout (integer)
Default: 300
WARNING: Disabling the in-memory cache will have significant negative impact on SSSD's performance and should only be used for testing.
NOTE: If the environment variable SSS_NSS_USE_MEMCACHE is set to "NO", client applications will not use the fast in-memory cache.
memcache_size_passwd (integer)
Default: 8
WARNING: Disabled or too small in-memory cache can have significant negative impact on SSSD's performance.
NOTE: If the environment variable SSS_NSS_USE_MEMCACHE is set to "NO", client applications will not use the fast in-memory cache.
memcache_size_group (integer)
Default: 6
WARNING: Disabled or too small in-memory cache can have significant negative impact on SSSD's performance.
NOTE: If the environment variable SSS_NSS_USE_MEMCACHE is set to "NO", client applications will not use the fast in-memory cache.
memcache_size_initgroups (integer)
Default: 10
WARNING: Disabled or too small in-memory cache can have significant negative impact on SSSD's performance.
NOTE: If the environment variable SSS_NSS_USE_MEMCACHE is set to "NO", client applications will not use the fast in-memory cache.
memcache_size_sid (integer)
Default: 6
WARNING: Disabled or too small in-memory cache can have significant negative impact on SSSD's performance.
NOTE: If the environment variable SSS_NSS_USE_MEMCACHE is set to "NO", client applications will not use the fast in-memory cache.
user_attributes (string)
To make configuration more easy the NSS responder will check the InfoPipe option if it is not set for the NSS responder.
Default: not set, fallback to InfoPipe option
pwfield (string)
Default: “*”
Note: This option can also be set per-domain which overwrites the value in [nss] section.
Default: “not set” (remote domains), “x” (the files domain), “x” (proxy domain with nss_files and sssd-shadowutils target)
PAM configuration options¶
These options can be used to configure the Pluggable Authentication Module (PAM) service.
offline_credentials_expiration (integer)
Default: 0 (No limit)
offline_failed_login_attempts (integer)
Default: 0 (No limit)
offline_failed_login_delay (integer)
If set to 0 the user cannot authenticate offline if offline_failed_login_attempts has been reached. Only a successful online authentication can enable offline authentication again.
Default: 5
pam_verbosity (integer)
Currently sssd supports the following values:
0: do not show any message
1: show only important messages
2: show informational messages
3: show all messages and debug information
Default: 1
pam_response_filter (string)
While messages already can be controlled with the help of the pam_verbosity option this option allows to filter out other kind of responses as well.
Currently the following filters are supported:
ENV
ENV:var_name
ENV:var_name:service
The list of strings can either be the list of filters which would set this list of filters and overwrite the defaults. Or each element of the list can be prefixed by a '+' or '-' character which would add the filter to the existing default or remove it from the defaults, respectively. Please note that either all list elements must have a '+' or '-' prefix or none. It is considered as an error to mix both styles.
Default: ENV:KRB5CCNAME:sudo, ENV:KRB5CCNAME:sudo-i
Example: -ENV:KRB5CCNAME:sudo-i will remove the filter from the default list
pam_id_timeout (integer)
A complete PAM conversation may perform multiple PAM requests, such as account management and session opening. This option controls (on a per-client-application basis) how long (in seconds) we can cache the identity information to avoid excessive round-trips to the identity provider.
Default: 5
pam_pwd_expiration_warning (integer)
Please note that the backend server has to provide information about the expiration time of the password. If this information is missing, sssd cannot display a warning.
If zero is set, then this filter is not applied, i.e. if the expiration warning was received from backend server, it will automatically be displayed.
This setting can be overridden by setting pwd_expiration_warning for a particular domain.
Default: 0
get_domains_timeout (int)
Default: 60
pam_trusted_users (string)
Default: All users are considered trusted by default
Please note that UID 0 is always allowed to access the PAM responder even in case it is not in the pam_trusted_users list.
pam_public_domains (string)
Two special values for pam_public_domains option are defined:
all (Untrusted users are allowed to access all domains in PAM responder.)
none (Untrusted users are not allowed to access any domains PAM in responder.)
Default: none
pam_account_expired_message (string)
Note: Please be aware that message is only printed for the SSH service unless pam_verbosity is set to 3 (show all messages and debug information).
example:
pam_account_expired_message = Account expired, please contact help desk.
Default: none
pam_account_locked_message (string)
example:
pam_account_locked_message = Account locked, please contact help desk.
Default: none
pam_cert_auth (bool)
Default: False
pam_cert_db_path (string)
Default:
pam_cert_verification (string)
example:
pam_cert_verification = partial_chain
Default: not set, i.e. use default “certificate_verification” option defined in “[sssd]” section.
p11_child_timeout (integer)
Default: 10
pam_app_services (string)
Default: Not set
pam_p11_allowed_services (integer)
It is possible to add another PAM service name to the default set by using “+service_name” or to explicitly remove a PAM service name from the default set by using “-service_name”. For example, in order to replace a default PAM service name for authentication with Smartcards (e.g. “login”) with a custom PAM service name (e.g. “my_pam_service”), you would use the following configuration:
pam_p11_allowed_services = +my_pam_service, -login
Default: the default set of PAM service names includes:
p11_wait_for_card_timeout (integer)
Default: 60
p11_uri (string)
Example:
p11_uri = pkcs11:slot-description=My%20Smartcard%20Reader
or
p11_uri = pkcs11:library-description=OpenSC%20smartcard%20framework;slot-id=2
To find suitable URI please check the debug output of p11_child. As an alternative the GnuTLS utility 'p11tool' with e.g. the '--list-all' will show PKCS#11 URIs as well.
Default: none
pam_initgroups_scheme
always
no_session
never
Default: no_session
pam_gssapi_services
To disable GSSAPI authentication, set this option to “-” (dash).
Note: This option can also be set per-domain which overwrites the value in [pam] section. It can also be set for trusted domain which overwrites the value in the domain section.
Example:
pam_gssapi_services = sudo, sudo-i
Default: - (GSSAPI authentication is disabled)
pam_gssapi_check_upn
If False, every user that is able to obtained required service ticket will be authenticated.
Note: This option can also be set per-domain which overwrites the value in [pam] section. It can also be set for trusted domain which overwrites the value in the domain section.
Default: True
pam_gssapi_indicators_map
Each element of the list can be either an authentication indicator name or a pair “service:indicator”. Indicators not prefixed with the PAM service name will be required to access any PAM service configured to be used with pam_gssapi_services. A resulting list of indicators per PAM service is then checked against indicators in the Kerberos ticket during authentication by pam_sss_gss.so. Any indicator from the ticket that matches the resulting list of indicators for the PAM service would grant access. If none of the indicators in the list match, access will be denied. If the resulting list of indicators for the PAM service is empty, the check will not prevent the access.
To disable GSSAPI authentication indicator check, set this option to “-” (dash). To disable the check for a specific PAM service, add “service:-”.
Note: This option can also be set per-domain which overwrites the value in [pam] section. It can also be set for trusted domain which overwrites the value in the domain section.
Following authentication indicators are supported by IPA Kerberos deployments:
Example: to require access to SUDO services only for users which obtained their Kerberos tickets with a X.509 certificate pre-authentication (PKINIT), set
pam_gssapi_indicators_map = sudo:pkinit, sudo-i:pkinit
Default: not set (use of authentication indicators is not required)
SUDO configuration options¶
These options can be used to configure the sudo service. The detailed instructions for configuration of sudo(8) to work with sssd(8) are in the manual page sssd-sudo(5).
sudo_timed (bool)
Default: false
sudo_threshold (integer)
Default: 50
AUTOFS configuration options¶
These options can be used to configure the autofs service.
autofs_negative_timeout (integer)
Default: 15
Please note that the automounter only reads the master map on startup, so if any autofs-related changes are made to the sssd.conf, you typically also need to restart the automounter daemon after restarting the SSSD.
SSH configuration options¶
These options can be used to configure the SSH service.
ssh_hash_known_hosts (bool)
Default: false
ssh_known_hosts_timeout (integer)
Default: 180
ssh_use_certificate_keys (bool)
Default: true
ssh_use_certificate_matching_rules (string)
There are two special key words 'all_rules' and 'no_rules' which will enable all or no rules, respectively. The latter means that no certificates will be filtered out and ssh keys will be generated from all valid certificates.
If no rules are configured using 'all_rules' will enable a default rule which enables all certificates suitable for client authentication. This is the same behavior as for the PAM responder if certificate authentication is enabled.
A non-existing rule name is considered an error. If as a result no rule is selected all certificates will be ignored.
Default: not set, equivalent to 'all_rules', all found rules or the default rule are used
ca_db (string)
Default:
PAC responder configuration options¶
The PAC responder works together with the authorization data plugin for MIT Kerberos sssd_pac_plugin.so and a sub-domain provider. The plugin sends the PAC data during a GSSAPI authentication to the PAC responder. The sub-domain provider collects domain SID and ID ranges of the domain the client is joined to and of remote trusted domains from the local domain controller. If the PAC is decoded and evaluated some of the following operations are done:
These options can be used to configure the PAC responder.
allowed_uids (string)
Default: 0 (only the root user is allowed to access the PAC responder)
Please note that although the UID 0 is used as the default it will be overwritten with this option. If you still want to allow the root user to access the PAC responder, which would be the typical case, you have to add 0 to the list of allowed UIDs as well.
pac_lifetime (integer)
Default: 300
pac_check (string)
The following options can be used alone or in a comma-separated list:
no_check
pac_present
check_upn
check_upn_allow_missing
Currently this option is set by default to avoid regressions in such environments. A log message will be added to the system log and SSSD's debug log in case a UPN is found in the PAC but not in SSSD's cache. To avoid this log message it would be best to evaluate if the 'ldap_user_principal' option can be removed. If this is not possible, removing 'check_upn' will skip the test and avoid the log message.
upn_dns_info_present
check_upn_dns_info_ex
upn_dns_info_ex_present
Default: no_check (AD and IPA provider 'check_upn, check_upn_allow_missing, check_upn_dns_info_ex')
Session recording configuration options¶
Session recording works in conjunction with tlog-rec-session(8), a part of tlog package, to log what users see and type when they log in on a text terminal. See also sssd-session-recording(5).
These options can be used to configure session recording.
scope (string)
"none"
"some"
"all"
Default: "none"
users (string)
Default: Empty. Matches no users.
groups (string)
NOTE: using this option (having it set to anything) has a considerable performance cost, because each uncached request for a user requires retrieving and matching the groups the user is member of.
Default: Empty. Matches no groups.
exclude_users (string)
Default: Empty. No users excluded.
exclude_groups (string)
NOTE: using this option (having it set to anything) has a considerable performance cost, because each uncached request for a user requires retrieving and matching the groups the user is member of.
Default: Empty. No groups excluded.
DOMAIN SECTIONS¶
These configuration options can be present in a domain configuration section, that is, in a section called “[domain/NAME]”
enabled
domain_type (string)
Allowed values for this option are “posix” and “application”.
POSIX domains are reachable by all services. Application domains are only reachable from the InfoPipe responder (see sssd-ifp(5)) and the PAM responder.
NOTE: The application domains are currently well tested with “id_provider=ldap” only.
For an easy way to configure a non-POSIX domains, please see the “Application domains” section.
Default: posix
min_id,max_id (integer)
For users, this affects the primary GID limit. The user will not be returned to NSS if either the UID or the primary GID is outside the range. For non-primary group memberships, those that are in range will be reported as expected.
These ID limits affect even saving entries to cache, not only returning them by name or ID.
Default: 1 for min_id, 0 (no limit) for max_id
enumerate (bool)
TRUE = Users and groups are enumerated
FALSE = No enumerations for this domain
Default: FALSE
Enumerating a domain requires SSSD to download and store ALL user and group entries from the remote server.
Note: Enabling enumeration has a moderate performance impact on SSSD while enumeration is running. It may take up to several minutes after SSSD startup to fully complete enumerations. During this time, individual requests for information will go directly to LDAP, though it may be slow, due to the heavy enumeration processing. Saving a large number of entries to cache after the enumeration completes might also be CPU intensive as the memberships have to be recomputed. This can lead to the “sssd_be” process becoming unresponsive or even restarted by the internal watchdog.
While the first enumeration is running, requests for the complete user or group lists may return no results until it completes.
Further, enabling enumeration may increase the time necessary to detect network disconnection, as longer timeouts are required to ensure that enumeration lookups are completed successfully. For more information, refer to the man pages for the specific id_provider in use.
For the reasons cited above, enabling enumeration is not recommended, especially in large environments.
subdomain_enumerate (string)
all
none
Optionally, a list of one or more domain names can enable enumeration just for these trusted domains.
Default: none
entry_cache_timeout (integer)
The cache expiration timestamps are stored as attributes of individual objects in the cache. Therefore, changing the cache timeout only has effect for newly added or expired entries. You should run the sss_cache(8) tool in order to force refresh of entries that have already been cached.
Default: 5400
entry_cache_user_timeout (integer)
Default: entry_cache_timeout
entry_cache_group_timeout (integer)
Default: entry_cache_timeout
entry_cache_netgroup_timeout (integer)
Default: entry_cache_timeout
entry_cache_service_timeout (integer)
Default: entry_cache_timeout
entry_cache_resolver_timeout (integer)
Default: entry_cache_timeout
entry_cache_sudo_timeout (integer)
Default: entry_cache_timeout
entry_cache_autofs_timeout (integer)
Default: entry_cache_timeout
entry_cache_ssh_host_timeout (integer)
Default: entry_cache_timeout
entry_cache_computer_timeout (integer)
Default: entry_cache_timeout
refresh_expired_interval (integer)
The background refresh will process users, groups and netgroups in the cache. For users who have performed the initgroups (get group membership for user, typically ran at login) operation in the past, both the user entry and the group membership are updated.
This option is automatically inherited for all trusted domains.
You can consider setting this value to 3/4 * entry_cache_timeout.
Cache entry will be refreshed by background task when 2/3 of cache timeout has already passed. If there are existing cached entries, the background task will refer to their original cache timeout values instead of current configuration value. This may lead to a situation in which background refresh task appears to not be working. This is done by design to improve offline mode operation and reuse of existing valid cache entries. To make this change instant the user may want to manually invalidate existing cache.
Default: 0 (disabled)
cache_credentials (bool)
Take a note that while credentials are stored as a salted SHA512 hash, this still potentially poses some security risk in case an attacker manages to get access to a cache file (normally requires privileged access) and to break a password using brute force attack.
Default: FALSE
cache_credentials_minimal_first_factor_length (int)
This should avoid that the short PINs of a PIN based 2FA scheme are saved in the cache which would make them easy targets for brute-force attacks.
Default: 8
account_cache_expiration (integer)
Default: 0 (unlimited)
pwd_expiration_warning (integer)
If zero is set, then this filter is not applied, i.e. if the expiration warning was received from backend server, it will automatically be displayed.
Please note that the backend server has to provide information about the expiration time of the password. If this information is missing, sssd cannot display a warning. Also an auth provider has to be configured for the backend.
Default: 7 (Kerberos), 0 (LDAP)
id_provider (string)
“proxy”: Support a legacy NSS provider.
“files”: FILES provider. See sssd-files(5) for more information on how to mirror local users and groups into SSSD.
“ldap”: LDAP provider. See sssd-ldap(5) for more information on configuring LDAP.
“ipa”: FreeIPA and Red Hat Identity Management provider. See sssd-ipa(5) for more information on configuring FreeIPA.
“ad”: Active Directory provider. See sssd-ad(5) for more information on configuring Active Directory.
use_fully_qualified_names (bool)
If set to TRUE, all requests to this domain must use fully qualified names. For example, if used in LOCAL domain that contains a "test" user, getent passwd test wouldn't find the user while getent passwd test@LOCAL would.
NOTE: This option has no effect on netgroup lookups due to their tendency to include nested netgroups without qualified names. For netgroups, all domains will be searched when an unqualified name is requested.
Default: FALSE (TRUE for trusted domain/sub-domains or if default_domain_suffix is used)
ignore_group_members (bool)
If set to TRUE, the group membership attribute is not requested from the ldap server, and group members are not returned when processing group lookup calls, such as getgrnam(3) or getgrgid(3). As an effect, “getent group $groupname” would return the requested group as if it was empty.
Enabling this option can also make access provider checks for group membership significantly faster, especially for groups containing many members.
This option can be also set per subdomain or inherited via subdomain_inherit.
Default: FALSE
auth_provider (string)
“ldap” for native LDAP authentication. See sssd-ldap(5) for more information on configuring LDAP.
“krb5” for Kerberos authentication. See sssd-krb5(5) for more information on configuring Kerberos.
“ipa”: FreeIPA and Red Hat Identity Management provider. See sssd-ipa(5) for more information on configuring FreeIPA.
“ad”: Active Directory provider. See sssd-ad(5) for more information on configuring Active Directory.
“proxy” for relaying authentication to some other PAM target.
“none” disables authentication explicitly.
Default: “id_provider” is used if it is set and can handle authentication requests.
access_provider (string)
“permit” always allow access. It's the only permitted access provider for a local domain.
“deny” always deny access.
“ldap” for native LDAP authentication. See sssd-ldap(5) for more information on configuring LDAP.
“ipa”: FreeIPA and Red Hat Identity Management provider. See sssd-ipa(5) for more information on configuring FreeIPA.
“ad”: Active Directory provider. See sssd-ad(5) for more information on configuring Active Directory.
“simple” access control based on access or deny lists. See sssd-simple(5) for more information on configuring the simple access module.
“krb5”: .k5login based access control. See sssd-krb5(5) for more information on configuring Kerberos.
“proxy” for relaying access control to another PAM module.
Default: “permit”
chpass_provider (string)
“ldap” to change a password stored in a LDAP server. See sssd-ldap(5) for more information on configuring LDAP.
“krb5” to change the Kerberos password. See sssd-krb5(5) for more information on configuring Kerberos.
“ipa”: FreeIPA and Red Hat Identity Management provider. See sssd-ipa(5) for more information on configuring FreeIPA.
“ad”: Active Directory provider. See sssd-ad(5) for more information on configuring Active Directory.
“proxy” for relaying password changes to some other PAM target.
“none” disallows password changes explicitly.
Default: “auth_provider” is used if it is set and can handle change password requests.
sudo_provider (string)
“ldap” for rules stored in LDAP. See sssd-ldap(5) for more information on configuring LDAP.
“ipa” the same as “ldap” but with IPA default settings.
“ad” the same as “ldap” but with AD default settings.
“none” disables SUDO explicitly.
Default: The value of “id_provider” is used if it is set.
The detailed instructions for configuration of sudo_provider are in the manual page sssd-sudo(5). There are many configuration options that can be used to adjust the behavior. Please refer to "ldap_sudo_*" in sssd-ldap(5).
NOTE: Sudo rules are periodically downloaded in the background unless the sudo provider is explicitly disabled. Set sudo_provider = None to disable all sudo-related activity in SSSD if you do not want to use sudo with SSSD at all.
selinux_provider (string)
“ipa” to load selinux settings from an IPA server. See sssd-ipa(5) for more information on configuring IPA.
“none” disallows fetching selinux settings explicitly.
Default: “id_provider” is used if it is set and can handle selinux loading requests.
subdomains_provider (string)
“ipa” to load a list of subdomains from an IPA server. See sssd-ipa(5) for more information on configuring IPA.
“ad” to load a list of subdomains from an Active Directory server. See sssd-ad(5) for more information on configuring the AD provider.
“none” disallows fetching subdomains explicitly.
Default: The value of “id_provider” is used if it is set.
session_provider (string)
“ipa” to allow performing user session related tasks.
“none” does not perform any kind of user session related tasks.
Default: “id_provider” is used if it is set and can perform session related tasks.
NOTE: In order to have this feature working as expected SSSD must be running as "root" and not as the unprivileged user.
autofs_provider (string)
“ldap” to load maps stored in LDAP. See sssd-ldap(5) for more information on configuring LDAP.
“ipa” to load maps stored in an IPA server. See sssd-ipa(5) for more information on configuring IPA.
“ad” to load maps stored in an AD server. See sssd-ad(5) for more information on configuring the AD provider.
“none” disables autofs explicitly.
Default: The value of “id_provider” is used if it is set.
hostid_provider (string)
“ipa” to load host identity stored in an IPA server. See sssd-ipa(5) for more information on configuring IPA.
“none” disables hostid explicitly.
Default: The value of “id_provider” is used if it is set.
resolver_provider (string)
“proxy” to forward lookups to another NSS library. See “proxy_resolver_lib_name”
“ldap” to fetch hosts and networks stored in LDAP. See sssd-ldap(5) for more information on configuring LDAP.
“ad” to fetch hosts and networks stored in AD. See sssd-ad(5) for more information on configuring the AD provider.
“none” disallows fetching hosts and networks explicitly.
Default: The value of “id_provider” is used if it is set.
re_expression (string)
Default: “^((?P<name>.+)@(?P<domain>[^@]*)|(?P<name>[^@]+))$” which allows two different styles for user names:
Default for the AD and IPA provider: “^(((?P<domain>[^\\]+)\\(?P<name>.+))|((?P<name>.+)@(?P<domain>[^@]+))|((?P<name>[^@\\]+)))$” which allows three different styles for user names:
While the first two correspond to the general default the third one is introduced to allow easy integration of users from Windows domains.
The default re_expression uses the “@” character as a separator between the name and the domain. As a result of this setting the default does not accept the “@” character in short names (as it is allowed in Windows group names). If a user wishes to use short names with “@” they must create their own re_expression.
full_name_format (string)
The following expansions are supported:
%1$s
%2$s
%3$s
Default: “%1$s@%2$s”.
lookup_family_order (string)
Supported values:
ipv4_first: Try looking up IPv4 address, if that fails, try IPv6
ipv4_only: Only attempt to resolve hostnames to IPv4 addresses.
ipv6_first: Try looking up IPv6 address, if that fails, try IPv4
ipv6_only: Only attempt to resolve hostnames to IPv6 addresses.
Default: ipv4_first
dns_resolver_server_timeout (integer)
The AD provider will use this option for the CLDAP ping timeouts as well.
Please see the section “FAILOVER” for more information about the service resolution.
Default: 1000
dns_resolver_op_timeout (integer)
Please see the section “FAILOVER” for more information about the service resolution.
Default: 3
dns_resolver_timeout (integer)
Please see the section “FAILOVER” for more information about the service resolution.
Default: 6
dns_resolver_use_search_list (bool)
If fully qualified domain names (or _srv_) are used in the SSSD configuration, setting this option to FALSE can prevent unnecessary DNS lookups in such environments.
Default: TRUE
dns_discovery_domain (string)
Default: Use the domain part of machine's hostname
override_gid (integer)
case_sensitive (string)
True
False
Preserving
If you want to set this value for trusted domain with IPA provider, you need to set it on both the client and SSSD on the server.
This option can be also set per subdomain or inherited via subdomain_inherit.
Default: True (False for AD provider)
subdomain_inherit (string)
ldap_search_timeout
ldap_network_timeout
ldap_opt_timeout
ldap_offline_timeout
ldap_enumeration_refresh_timeout
ldap_enumeration_refresh_offset
ldap_purge_cache_timeout
ldap_purge_cache_offset
ldap_krb5_keytab (the value of krb5_keytab will be used if ldap_krb5_keytab is not set explicitly)
ldap_krb5_ticket_lifetime
ldap_enumeration_search_timeout
ldap_connection_expire_timeout
ldap_connection_expire_offset
ldap_connection_idle_timeout
ldap_use_tokengroups
ldap_user_principal
ignore_group_members
auto_private_groups
case_sensitive
Example:
subdomain_inherit = ldap_purge_cache_timeout
Default: none
Note: This option only works with the IPA and AD provider.
subdomain_homedir (string)
%F
The value can be overridden by override_homedir option.
Default: /home/%d/%u
realmd_tags (string)
cached_auth_timeout (int)
This option's value is inherited by all trusted domains. At the moment it is not possible to set a different value per trusted domain.
Special value 0 implies that this feature is disabled.
Please note that if “cached_auth_timeout” is longer than “pam_id_timeout” then the back end could be called to handle “initgroups.”
Default: 0
local_auth_policy (string)
There are three possible values for this option: match, only, enable. “match” is used to match offline and online states for Kerberos methods. “only” ignores the online methods and only offer the local ones. enable allows explicitly defining the methods for local authentication. As an example, “enable:passkey”, only enables passkey for local authentication. Multiple enable values should be comma-separated, such as “enable:passkey, enable:smartcard”
Please note that if local Smartcard authentication is enabled and a Smartcard is present, Smartcard authentication will be preferred over the authentication methods supported by the backend. I.e. there will be a PIN prompt instead of e.g. a password prompt.
The following configuration example allows local users to authenticate locally using any enabled method (i.e. smartcard, passkey).
[domain/shadowutils] id_provider = proxy proxy_lib_name = files auth_provider = none local_auth_policy = only
It is expected that the “files” provider ignores the local_auth_policy option and supports Smartcard authentication by default.
Default: match
auto_private_groups (string)
true
NOTE: Because the GID number and the user private group are inferred from the UID number, it is not supported to have multiple entries with the same UID or GID number with this option. In other words, enabling this option enforces uniqueness across the ID space.
false
hybrid
If the UID and GID of a user are different, then the GID must correspond to a group entry, otherwise the GID is simply not resolvable.
This feature is useful for environments that wish to stop maintaining a separate group objects for the user private groups, but also wish to retain the existing user private groups.
For subdomains, the default value is False for subdomains that use assigned POSIX IDs and True for subdomains that use automatic ID-mapping.
The value of auto_private_groups can either be set per subdomains in a subsection, for example:
[domain/forest.domain/sub.domain] auto_private_groups = false
or globally for all subdomains in the main domain section using the subdomain_inherit option:
[domain/forest.domain] subdomain_inherit = auto_private_groups auto_private_groups = false
Options valid for proxy domains.
proxy_pam_target (string)
Default: not set by default, you have to take an existing pam configuration or create a new one and add the service name here. As an alternative you can enable local authentication with the local_auth_policy option.
proxy_lib_name (string)
proxy_resolver_lib_name (string)
proxy_fast_alias (boolean)
Default: false
proxy_max_children (integer)
Default: 10
Application domains¶
SSSD, with its D-Bus interface (see sssd-ifp(5)) is appealing to applications as a gateway to an LDAP directory where users and groups are stored. However, contrary to the traditional SSSD deployment where all users and groups either have POSIX attributes or those attributes can be inferred from the Windows SIDs, in many cases the users and groups in the application support scenario have no POSIX attributes. Instead of setting a “[domain/NAME]” section, the administrator can set up an “[application/NAME]” section that internally represents a domain with type “application” optionally inherits settings from a tradition SSSD domain.
Please note that the application domain must still be explicitly enabled in the “domains” parameter so that the lookup order between the application domain and its POSIX sibling domain is set correctly.
Application domain parameters
inherit_from (string)
Default: Not set
The following example illustrates the use of an application domain. In this setup, the POSIX domain is connected to an LDAP server and is used by the OS through the NSS responder. In addition, the application domain also requests the telephoneNumber attribute, stores it as the phone attribute in the cache and makes the phone attribute reachable through the D-Bus interface.
[sssd] domains = appdom, posixdom [ifp] user_attributes = +phone [domain/posixdom] id_provider = ldap ldap_uri = ldap://ldap.example.com ldap_search_base = dc=example,dc=com [application/appdom] inherit_from = posixdom ldap_user_extra_attrs = phone:telephoneNumber
TRUSTED DOMAIN SECTION¶
Some options used in the domain section can also be used in the trusted domain section, that is, in a section called “[domain/DOMAIN_NAME/TRUSTED_DOMAIN_NAME]”. Where DOMAIN_NAME is the actual joined-to base domain. Please refer to examples below for explanation. Currently supported options in the trusted domain section are:
ldap_search_base,
ldap_user_search_base,
ldap_group_search_base,
ldap_netgroup_search_base,
ldap_service_search_base,
ldap_sasl_mech,
ad_server,
ad_backup_server,
ad_site,
use_fully_qualified_names
pam_gssapi_services
pam_gssapi_check_upn
For more details about these options see their individual description in the manual page.
CERTIFICATE MAPPING SECTION¶
To allow authentication with Smartcards and certificates SSSD must be able to map certificates to users. This can be done by adding the full certificate to the LDAP object of the user or to a local override. While using the full certificate is required to use the Smartcard authentication feature of SSH (see sss_ssh_authorizedkeys(8) for details) it might be cumbersome or not even possible to do this for the general case where local services use PAM for authentication.
To make the mapping more flexible mapping and matching rules were added to SSSD (see sss-certmap(5) for details).
A mapping and matching rule can be added to the SSSD configuration in a section on its own with a name like “[certmap/DOMAIN_NAME/RULE_NAME]”. In this section the following options are allowed:
matchrule (string)
Default: KRB5:<EKU>clientAuth, i.e. only certificates which have the Extended Key Usage “clientAuth”
maprule (string)
Default:
domains (string)
Default: the configured domain in sssd.conf
priority (integer)
Default: the lowest priority
To make the configuration simple and reduce the amount of configuration options the “files” provider has some special properties:
PROMPTING CONFIGURATION SECTION¶
If a special file (/var/lib/sss/pubconf/pam_preauth_available) exists SSSD's PAM module pam_sss will ask SSSD to figure out which authentication methods are available for the user trying to log in. Based on the results pam_sss will prompt the user for appropriate credentials.
With the growing number of authentication methods and the possibility that there are multiple ones for a single user the heuristic used by pam_sss to select the prompting might not be suitable for all use cases. The following options should provide a better flexibility here.
Each supported authentication method has its own configuration subsection under “[prompting/...]”. Currently there are:
[prompting/password]
password_prompt
[prompting/2fa]
first_prompt
second_prompt
single_prompt
If the second factor is optional and it should be possible to log in either only with the password or with both factors two-step prompting has to be used.
It is possible to add a subsection for specific PAM services, e.g. “[prompting/password/sshd]” to individual change the prompting for this service.
EXAMPLES¶
1. The following example shows a typical SSSD config. It does not describe configuration of the domains themselves - refer to documentation on configuring domains for more details.
[sssd] domains = LDAP services = nss, pam config_file_version = 2 [nss] filter_groups = root filter_users = root [pam] [domain/LDAP] id_provider = ldap ldap_uri = ldap://ldap.example.com ldap_search_base = dc=example,dc=com auth_provider = krb5 krb5_server = kerberos.example.com krb5_realm = EXAMPLE.COM cache_credentials = true min_id = 10000 max_id = 20000 enumerate = False
2. The following example shows configuration of IPA AD trust where the AD forest consists of two domains in a parent-child structure. Suppose IPA domain (ipa.com) has trust with AD domain(ad.com). ad.com has child domain (child.ad.com). To enable shortnames in the child domain the following configuration should be used.
[domain/ipa.com/child.ad.com] use_fully_qualified_names = false
3. The following example shows the configuration of a certificate mapping rule. It is valid for the configured domain “my.domain” and additionally for the subdomains “your.domain” and uses the full certificate in the search filter.
[certmap/my.domain/rule_name]
matchrule = <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
maprule = (userCertificate;binary={cert!bin})
domains = my.domain, your.domain
priority = 10
SEE ALSO¶
sssd(8), sssd.conf(5), sssd-ldap(5), sssd-ldap-attributes(5), sssd-krb5(5), sssd-simple(5), sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-sudo(5), sssd-session-recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8), sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8), sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5) sssd-systemtap(5)
AUTHORS¶
The SSSD upstream - https://github.com/SSSD/sssd/
| 05/24/2024 | SSSD |