SSSD.CONF(5)

okay bestie, welcome to SSSD.CONF(5) from File Formats and Conventions — literally the manual page for sssd.conf, the configuration file for SSSD. 🎀 The group chat is open, let’s get you fluent. 💅

🌸 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. Here’s an example of a 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 that is accessible only by the user used to run SSSD service or root. 👑

📂 CONFIGURATION SNIPPETS FROM INCLUDE DIRECTORY 📂

The configuration file sssd.conf will include configuration snippets using the include directory conf.d.

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.

⚙️ GENERAL OPTIONS ⚙️

Following options are usable in more than one configuration sections. Yes, bestie, that’s the original phrasing and we’re keeping it. 😌

🧸 Options usable in all sections 🧸

debug_level (integer) — SSSD supports two representations for specifying the debug level. The simplest is a decimal value from 0–9, which represents enabling that level and all lower-level debug messages. The more comprehensive option is to specify a hexadecimal bitmask to enable or disable specific levels (such as if you wish to suppress a level).

Each SSSD service logs into its own log file. Also, 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) — SSSD 1.14 and later also includes the debug alias for debug_level as a convenience feature. If both are specified, the value of debug_level will be used. 🪄
debug_timestamps (bool) — Add a timestamp to the debug messages. If journald is enabled for SSSD debug logging this option is ignored.

Default: true

debug_microseconds (bool) — Add microseconds to the timestamp in debug messages. If journald is enabled for SSSD debug logging this option is ignored.

Default: false

debug_backtrace_enabled (bool) — Enable debug backtrace.

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) — Timeout in seconds between heartbeats for this service. This is used to ensure that the process is alive and capable of answering requests. Note that after three missed heartbeats the process will terminate itself. 💀

Default: 10

🌸 The `[sssd]` section 🌸

Okay so listen — every individual piece of SSSD functionality? It's provided by special SSSD services, and those bad boys get started and stopped right along with SSSD itself. They're managed by a special service that everyone calls the "monitor" 👑. And the [sssd] section is literally where you configure the monitor plus some other important stuff like the identity domains. Main character section fr fr.

Section parameters

services — a comma separated list of services that get started when sssd itself starts. Lowkey this list is optional on platforms where systemd is supported, because they'll either be socket or D-Bus activated when needed. The supported services are: nss, pam, ifp, sudo, autofs, ssh, pac. By default all services are disabled, and the admin has to enable the ones allowed to be used by executing: systemctl enable sssd-@service@.socket 💅
domains — a domain is basically a database containing user information. SSSD can use more domains at the same time, but at least one must be configured or SSSD won't start, periodt. This parameter describes the list of domains in the order you want them to be queried. A domain name is recommended to contain only alphanumeric ASCII characters, dashes, dots and underscores. The / character is forbidden 🚫.
re_expression (string) — the default regular expression that describes how to parse the string containing user name and domain into these components. Each domain can have an individual regular expression configured, too. And for some ID providers there are also default regular expressions — see DOMAIN SECTIONS for more info on those. iykyk ✨
full_name_format (string) — a printf(3)-compatible format that describes how to compose a fully qualified name from the user name and domain name components. Here's the expansions it supports:
- %1$s — user name
- %2$s — domain name as specified in the SSSD config file
- %3$s — domain flat name. Mostly usable for Active Directory domains, both directly configured or discovered via IPA trusts. Each domain can have an individual format string configured. See DOMAIN SECTIONS for more info on this option.
monitor_resolv_conf (boolean) — controls if SSSD should monitor the state of resolv.conf to identify when it needs to update its internal DNS resolver. Default: true.
try_inotify (boolean) — by default, SSSD will attempt to use inotify to monitor configuration file changes, and will fall back to polling every five seconds if inotify can't be used. There are some limited situations where it's preferred that we skip even trying to use inotify — in these rare cases, set this option 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 those platforms, polling will always be used. No exceptions bestie 🫶

krb5_rcache_dir (string) — directory on the filesystem where SSSD should store Kerberos replay cache files. 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).
default_domain_suffix (string) — ⚠️ heads up bestie: please note that this option is deprecated and domain_resolution_order should be used instead. This string will be used as a default domain name for all names without a domain name component. The main use case is environments where the primary domain is intended for managing host policies and all users are located in a trusted domain — this option lets those users log in just with their user name, without also giving a domain name. 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 the 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 😤 Default: not set.
override_space (string) — this parameter will replace spaces (space bar) with the given character for user and group names, e.g. (_). User name "john doe" will be "john_doe". This feature was added to help compatibility with shell scripts that have difficulty handling spaces, due to the default field separator in the shell. Please note it's 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) — with this parameter you can tune the certificate verification with a comma separated list of options. Supported options are:
- no_ocsp — disables Online Certificate Status Protocol (OCSP) checks. This might be needed if the OCSP servers defined in the certificate aren't reachable from the client.
- soft_ocsp — if a connection can't be established to an OCSP responder, the OCSP check is skipped. This option should be used to allow authentication when the system is offline and the OCSP responder can't be reached.
- ocsp_dgst — digest (hash) function used to create the certificate ID for the OCSP request. Allowed values are:
  - sha1
  - sha256
  - sha384
  - sha512 Default: sha1 (to allow compatibility with RFC5019-compliant responder).
- no_verification — disables verification completely. This option should only be used for testing 👀
- partial_chain — allow verification to succeed even if a complete chain can't be built to a self-signed trust-anchor, provided it's possible to construct a chain to a trusted certificate that might not be self-signed.
- ocsp_default_responder=URL — sets the OCSP default responder that should be used instead of the one mentioned in the certificate. URL must be replaced with the URL of the OCSP default responder, e.g. http://example.com:80/ocsp.
- ocsp_default_responder_signing_cert=NAME — this option is currently ignored 🫠 all needed certificates must be available in the PEM file given by pam_cert_db_path.
- crl_file=/PATH/TO/CRL/FILE — use the Certificate Revocation List (CRL) from the given file during the verification of the certificate. The CRL must be given in PEM format, see crl(1ssl) for details.
- soft_crl — if a Certificate Revocation List (CRL) is expired, ignore the expiration time of the CRL and check the related certificates with the expired CRL. This option should be used to allow authentication when the system is offline and the CRL can't be renewed. Unknown options are reported but ignored. Default: not set, i.e. do not restrict certificate verification.
disable_netlink (boolean) — SSSD hooks into the netlink interface to monitor changes to routes, addresses, links and trigger certain actions. 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).
domain_resolution_order — a comma separated list of domains and subdomains representing the lookup order that will be followed. The list doesn't have to include all possible domains, since the missing domains will be looked up based on the order they're presented in the domains configuration option. The subdomains which aren't listed as part of lookup_order will be looked up in a random order for each parent domain 🎲 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. 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. Consider yourself warned 💀 Default: Not set.
implicit_pac_responder (boolean) — the PAC responder is enabled automatically for the IPA and AD provider to evaluate and check the PAC. If it has to be disabled, set this option to 'false'. Default: true.
core_dumpable (boolean) — this option can be used for general system hardening: setting it to 'false' forbids core dumps for all SSSD processes to avoid leaking plain text passwords 🔐. See man page prctl:PR_SET_DUMPABLE on Linux or procctl:PROC_TRACE_CTL on FreeBSD for details. Take a note that this setting has no effect for ldap_child, krb5_child and sssd_pam, since those privileged binaries can have a copy of host keytab data in memory, and their behavior in this regards is governed by the /proc/sys/fs/suid_dumpable system setting. Default: true.
passkey_verification (string) — with this parameter the passkey verification can be tuned with a comma separated list of options. Supported options are:
- user_verification (boolean) — enable or disable the user verification (i.e. PIN, fingerprint) during authentication. If enabled, the PIN will always be requested. The default is that the key settings decide what to do. In the IPA or kerberos pre-authentication case, this value will be overwritten by the server 🔑✨

🦋 SERVICES SECTIONS 🦋

Okay so settings that can be used to configure different services are described in this section. They should live in the [$NAME] section — like, for the NSS service, the section would be [nss] 💖

✨ General service configuration options ✨

These options can be used to configure any service.

fd_limit — the max number of file descriptors this SSSD process is allowed to have open at one time 💅 heads up tho: this value gets capped by your init system when SSSD starts up, so check man systemd.exec for the deets. Default is 8192 (or the limits.conf "hard" limit, whichever applies) 🫶
client_idle_timeout — how many seconds a client of an SSSD process can just sit there holding a file descriptor without actually talking on it 😴 this is a whole anti-resource-exhaustion thing, so the timeout literally cannot be shorter than 10 seconds — configure something lower and it gets bumped up to 10. Default: 60, and for KCM: 300 ✨
responder_idle_timeout — how many seconds an SSSD responder process can be alive without anybody using it 🦋 same energy as above, it's capped so the system doesn't run out of resources. Minimum acceptable value is 60 seconds. Set it to 0 (zero) and no timeout gets set up on the responder at all. Lowkey important: this only does anything when SSSD is built with systemd support and the services are either socket or D-Bus activated 👑 Default: 300
cache_first — should the responder go query all the caches before it bothers the Data Providers? 🔥 Default: true

💅 NSS configuration options 💅

These ones are all about configuring the Name Service Switch (NSS) service, bestie 🌸

enum_cache_timeout (integer) — how many seconds nss_sss should cache enumerations (that's requests for info about all users, iykyk). Default: 120 ⭐
entry_cache_nowait_percentage (integer) — okay so this one lets the entry cache auto-update entries in the background when they're requested past a certain percentage of the entry_cache_timeout value for the domain ✨

Like, say your domain's entry_cache_timeout is 30s and you set entry_cache_nowait_percentage to 50 (percent) — then entries that come in after 15 seconds past the last cache update get returned immediately, but SSSD will go and update the cache on its own so future requests don't have to block waiting for a cache update 🎀

Valid values are 0-99, and they 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 the feature entirely). Default: 50 🦋

entry_negative_timeout (integer) — how many seconds nss_sss should cache negative cache hits before asking the back end again 💀 and yes, "negative hits" means queries for invalid database entries, like ones that don't exist. Default: 15
filter_users, filter_groups (string) — exclude certain users or groups from being fetched from the sss NSS database 🙈 super useful for system accounts. This can also be set per-domain, or you can include fully-qualified names to filter only users from a particular domain, or filter by a user principal name (UPN) 🫶 Default: root

NOTE: the filter_groups option does not affect inheritance of nested group members, because filtering happens after they've been propagated for returning via NSS. So like, a group that has a member group filtered out will still have the member users of that latter group listed 😭

filter_users_in_groups (bool) — if you want a filtered user to still be a group member, set this to false ✨ Default: true
override_homedir (string) — override the user's home directory 🏠 you can give it an absolute value or a template, and in the template these sequences get substituted:
- %u — login name
- %U — UID number
- %d — domain name
- %f — fully qualified user name (user@domain)
- %l — the first letter of the login name
- %P — UPN, aka User Principal Name (name@REALM)
- %o — the homedir value that's defined in the directory of the identity provider 💖 this substitution is designed to be used in an IPA-AD trust scenario. If it's used for the subdomain_homedir option, it propagates the home directory value from the AD domain to the IPA clients. In that scenario, the option must be set in the SSSD configuration on the IPA server where SSSD is running in server mode 👑
- %h — the path defined for the homedir directory attribute of the identity provider, but in lower case. For details of use, see %o.
- %H — the value of the configure option homedir_substring
- %% — a literal %

This option can also be set per-domain, bestie 🦋

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 higher precedence and will be used instead of whatever override_homedir says 💅

homedir_substring (string) — the value of this option gets used in the expansion of the override_homedir option when the template contains the format string %H 🌸 an LDAP directory entry can directly contain this template, so this option can expand the home directory path for each client machine (or operating system). It can be set per-domain or globally in the [nss] section — and a value in a domain section overrides one set in [nss] ✨ Default: /home
fallback_homedir (string) — set a default template for a user's home directory if the domain's data provider doesn't specify one explicitly 🎀 available values are the same as for override_homedir.

example:

fallback_homedir = /home/%u

Default: not set (no substitution for unset home directories) 😭

override_shell (string) — override the login shell for all users 🐚 this supersedes any other shell options if it takes effect, and it can be set in the [nss] section or per-domain. Default: not set (SSSD will use the value retrieved from LDAP)
allowed_shells (string) — restrict user shells to one of the listed values 💅 the order of evaluation is:
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 🔥 and the (*) is genuinely useful if you want to use shell_fallback in case a user's shell isn't in /etc/shells — because maintaining a list of all allowed shells in allowed_shells would be way too much overhead, no cap.

An empty string for shell is passed as-is to libc 🫶

Heads up: /etc/shells is only read on SSSD start up, which means you need to restart SSSD if a new shell gets installed ⭐

Default: Not set. The user shell is automatically used.

vetoed_shells (string) — replace any instance of these shells with the shell_fallback 💀
shell_fallback (string) — the default shell to use if an allowed shell isn't installed on the machine. Default: /bin/sh ✨
default_shell — the default shell to use if the provider doesn't return one during lookup 🌸 can be specified globally in the [nss] section or per-domain. 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) — specifies the time in seconds for which the list of subdomains will be considered valid. Default: 60 🦋
memcache_timeout (integer) — specifies the time in seconds for which records in the in-memory cache will be valid ⏳ setting it to zero disables the in-memory cache entirely. Default: 300

WARNING: disabling the in-memory cache will have a significant negative impact on SSSD's performance, so only do it for testing, bestie, I'm begging 😭

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) — size (in megabytes) of the data table allocated inside the fast in-memory cache for passwd requests 💖 setting the size to 0 disables the passwd in-memory cache. Default: 8

WARNING: a disabled or too-small in-memory cache can have a 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) — size (in megabytes) of the data table allocated inside the fast in-memory cache for group requests 👯 setting it to 0 disables the group in-memory cache. Default: 6

WARNING: a disabled or too-small in-memory cache can have a 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) — size (in megabytes) of the data table allocated inside the fast in-memory cache for initgroups requests 🌈 setting it to 0 disables the initgroups in-memory cache. Default: 10

WARNING: a disabled or too-small in-memory cache can have a 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) — size (in megabytes) of the data table allocated inside the fast in-memory cache for SID related requests 🎀 only SID-by-ID and ID-by-SID requests are currently cached in the fast in-memory cache. Setting the size to 0 disables the SID in-memory cache. Default: 6

WARNING: a disabled or too-small in-memory cache can have a 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) — okay so some of the extra NSS responder requests can return more attributes than just the POSIX ones defined by the NSS interface. The list of attributes is controlled by this option. It’s handled the same way as the user_attributes option of the InfoPipe responder (see sssd-ifp(5) for details), but with no default values.

To make configuration easier, 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) — the value that NSS operations returning users or groups will return for the password field.

Default: *

Note: this option can also be set per-domain, and that overwrites the value in the [nss] section.

Default: not set (remote domains), x (proxy domain with nss_files and sssd-shadowutils target)

💖 PAM configuration options 💖

These options configure the Pluggable Authentication Module (PAM) service. PAM girlies, this one’s for you 🫶

offline_credentials_expiration (integer) — if the authentication provider is offline, how long should we allow cached logins (in days since the last successful online login)?

Default: 0 (No limit)

offline_failed_login_attempts (integer) — if the authentication provider is offline, how many failed login attempts are allowed?

Default: 0 (No limit)

offline_failed_login_delay (integer) — the time in minutes which has to pass after offline_failed_login_attempts has been reached before a new login attempt is possible.

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) — controls what kind of messages are shown to the user during authentication. The higher the number, the more messages are displayed.

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) — a comma separated list of strings which allows you to remove (filter) data sent by the PAM responder to the pam_sss PAM module. There are different kinds of responses sent to pam_sss, e.g. messages displayed to the user or environment variables which should be set by pam_sss.

While messages already can be controlled with the help of the pam_verbosity option, this option allows you to filter out other kinds of responses as well.

Currently the following filters are supported:

ENV — Do not send any environment variables to any service.
ENV:var_name — Do not send environment variable var_name to any service.
ENV:var_name:service — Do not send environment variable var_name to 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 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) — for any PAM request while SSSD is online, SSSD will attempt to immediately update the cached identity information for the user in order to ensure that authentication takes place with the latest information.

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) — display a warning N days before the password expires.

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 the 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) — specifies time in seconds for which the list of subdomains will be considered valid.

Default: 60

pam_trusted_users (string) — specifies the comma-separated list of UID values or user names that are allowed to run PAM conversations against trusted domains. Users not included in this list can only access domains marked as public with pam_public_domains. User names are resolved to UIDs at startup.

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) — specifies the comma-separated list of domain names that are accessible even to untrusted users.

Two special values for the pam_public_domains option are defined:

all — Untrusted users are allowed to access all domains in the PAM responder.
none — Untrusted users are not allowed to access any domains PAM in responder.

Default: none

pam_account_expired_message (string) — allows a custom expiration message to be set, replacing the default 'Permission denied' message.

Note: please be aware that the 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) — allows a custom lockout message to be set, replacing the default 'Permission denied' message.

example:

pam_account_locked_message = Account locked, please contact help desk.

Default: none

pam_passkey_auth (bool) — enable passkey device based authentication.

Default: True

passkey_debug_libfido2 (bool) — enable libfido2 library debug messages.

Default: False

pam_cert_auth (bool) — enable certificate based Smartcard authentication. Since this requires additional communication with the Smartcard which will delay the authentication process, this option is disabled by default.

Default: False

pam_cert_db_path (string) — the path to the certificate database.

Default:

/etc/sssd/pki/sssd_auth_ca_db.pem (path to a file with trusted CA certificates in PEM format)

pam_cert_verification (string) — with this parameter the PAM certificate verification can be tuned with a comma separated list of options that override the certificate_verification value in [sssd] section. Supported options are the same of certificate_verification.

example:

pam_cert_verification = partial_chain

Default: not set, i.e. use default certificate_verification option defined in [sssd] section.

p11_child_timeout (integer) — how many seconds will pam_sss wait for p11_child to finish.

Default: 10

passkey_child_timeout (integer) — how many seconds will the PAM responder wait for passkey_child to finish.

Default: 15

pam_app_services (string) — which PAM services are permitted to contact domains of type application

Default: Not set

pam_p11_allowed_services (string) — a comma-separated list of PAM service names for which it will be allowed to use Smartcards.

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:

login
su
su-l
gdm-smartcard
gdm-password
gdm-switchable-auth
kdm
plasmalogin
sudo
sudo-i
gnome-screensaver

p11_wait_for_card_timeout (integer) — if Smartcard authentication is required, how many extra seconds in addition to p11_child_timeout should the PAM responder wait until a Smartcard is inserted?

Default: 60

p11_uri (string) — PKCS#11 URI (see RFC-7512 for details) which can be used to restrict the selection of devices used for Smartcard authentication. By default SSSD's p11_child will search for a PKCS#11 slot (reader) where the 'removable' flags is set and read the certificates from the inserted token from the first slot found. If multiple readers are connected, p11_uri can be used to tell p11_child to use a specific reader.

Example:

p11_uri = pkcs11:slot-description=My%20Smartcard%20Reader

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 — the PAM responder can force an online lookup to get the current group memberships of the user trying to log in. This option controls when this should be done and the following values are allowed:
- always — Always do an online lookup, please note that pam_id_timeout still applies
- no_session — Only do an online lookup if there is no active session of the user, i.e. if the user is currently not logged in
- never — Never force an online lookup, use the data from the cache as long as they are not expired
-, default: no_session — that's your fallback vibe, bestie 💅

pam_gssapi_services — a comma separated list of PAM services that are allowed to try GSSAPI authentication using the pam_sss_gss.so module ✨

To disable GSSAPI authentication, set this option to “-” (dash).

Note: this option can also be set per-domain which overwrites the value in the [pam] section. It can also be set for a trusted domain which overwrites the value in the domain section. The way it just cascades down, iykyk 🫶

Example:

pam_gssapi_services = sudo, sudo-i

Default: - (GSSAPI authentication is disabled)

pam_gssapi_check_upn — if True, SSSD will require that the Kerberos user principal that successfully authenticated through GSSAPI can be associated with the user who is being authenticated. Authentication will fail if the check fails. no cap, it just won't let you in 💀

If False, every user that is able to obtain the required service ticket will be authenticated. (Whoever has the ticket gets the crown 👑)

Note: this option can also be set per-domain which overwrites the value in the [pam] section. It can also be set for a trusted domain which overwrites the value in the domain section.

Default: True

pam_gssapi_indicators_map — a comma separated list of authentication indicators required to be present in a Kerberos ticket to access a PAM service that is allowed to try GSSAPI authentication using the pam_sss_gss.so module 🎟️

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. (Empty list = it's giving "no thoughts, head empty", and nobody gets blocked 🙈)

To disable the 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 the [pam] section. It can also be set for a trusted domain which overwrites the value in the domain section.

Following authentication indicators are supported by IPA Kerberos deployments:

pkinit — pre-authentication using X.509 certificates — whether stored in files or on smart cards 🪪
hardened — SPAKE pre-authentication or any pre-authentication wrapped in a FAST channel 🔥
radius — pre-authentication with the help of a RADIUS server 📡
otp — pre-authentication using integrated two-factor authentication (2FA or one-time password, OTP) in IPA 🔐
idp — pre-authentication using an external identity provider 🌐

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)

pam_gssapi_indicators_apply — a comma separated list of triples to assign additional information from the Kerberos ticket, e.g. a SID from the PAC, to authentication indicators 🧩

Currently supported is:

SID:S-1-5-[domain]-[RID]:[authentication indicator]

Example: to assign a SID, which is e.g. set by Active Directory's Authentication Mechanism Assurance (AMA) if the AD user used a Smartcard for authentication, to the 'pkinit' authentication indicator use:

pam_gssapi_indicators_apply = SID:S-1-5-12345-23456-34567-4321:pkinit

Default: not set

pam_json_services (string) — a comma separated list of PAM services which can handle the JSON protocol for selecting authentication mechanisms 🌸

To disable the JSON protocol, set this option to “-” (dash).

Example:

pam_json_services = gdm-switchable-auth

Default: - (JSON protocol is disabled)

Note: 2-Factor Authentication (2FA) is not supported. If 2FA is required, do not activate the JSON protocol. Like, seriously, do not 😭

💅 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). Go read that one too, bestie, it's iconic 🫶

sudo_timed (bool) — whether or not to evaluate the sudoNotBefore and sudoNotAfter attributes that implement time-dependent sudoers entries ⏰

Default: false

sudo_threshold (integer) — maximum number of expired rules that can be refreshed at once. If the number of expired rules is below the threshold, those rules are refreshed with the “rules refresh” mechanism. If the threshold is exceeded, a “full refresh” of sudo rules is triggered instead. This threshold number also applies to IPA sudo command and command group searches. (It's giving "small cleanup vs. full closet purge" 🧹)

Default: 50

🚗 AUTOFS configuration options 🚗

These options can be used to configure the autofs service.

autofs_negative_timeout (integer) — specifies for how many seconds the autofs responder should negative cache hits (that is, queries for invalid map entries, like nonexistent ones) before asking the back end again 🙈

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. It's a whole two-step situation, don't skip leg day 💀

🦋 SSH configuration options 🦋

These options can be used to configure the SSH service.

ssh_use_certificate_keys (bool) — if set to true, the sss_ssh_authorizedkeys will return ssh keys derived from the public key of X.509 certificates stored in the user entry as well. See sss_ssh_authorizedkeys(1) for details 🔑

Default: true

ssh_use_certificate_matching_rules (string) — by default the ssh responder will use all available certificate matching rules to filter the certificates so that ssh keys are only derived from the matching ones. With this option the used rules can be restricted with a comma separated list of mapping and matching rule names. All other rules will be ignored ✨

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. (Yeah, all of them. Gone. Poof 🫥)

Default: not set, equivalent to all_rules, all found rules or the default rule are used

ca_db (string) — path to a storage of trusted CA certificates. The option is used to validate user certificates before deriving public ssh keys from them 🎀

Default:

/etc/sssd/pki/sssd_auth_ca_db.pem (path to a file with trusted CA certificates in PEM format)

🌈 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:

If the remote user does not exist in the cache, it is created. The UID is determined with the help of the SID, trusted domains will have UPGs and the GID will have the same value as the UID. The home directory is set based on the subdomain_homedir parameter. The shell will be empty by default, i.e. the system defaults are used, but can be overwritten with the default_shell parameter 🏠
If there are SIDs of groups from domains sssd knows about, the user will be added to those groups 👯

These options can be used to configure the PAC responder.

allowed_uids (string) — specifies the comma-separated list of UID values or user names that are allowed to access the PAC responder. User names are resolved to UIDs at startup 🔐

Default: 0, sssd (only root and SSSD service users are allowed to access the PAC responder)

Please note that defaults will be overwritten with this option. If you still want to allow the root and/or 'sssd' user to access the PAC responder, which would be the typical case, you have to add those to the list of allowed UIDs explicitly. Yes, it fully replaces the default — it does not add to it, bestie 😭

pac_lifetime (integer) — lifetime of the PAC entry in seconds. As long as the PAC is valid the PAC data can be used to determine the group memberships of a user ⏳

Default: 300

pac_check (string) — apply additional checks on the PAC of the Kerberos ticket which is available in Active Directory and FreeIPA domains, if configured. Please note that Kerberos ticket validation must be enabled to be able to check the PAC, i.e. the krb5_validate option must be set to 'True' which is the default for the IPA and AD provider. If krb5_validate is set to 'False' the PAC checks will be skipped 🫣

Please note that the checks listed below only apply to PACs issued by Active Directory or recent versions of FreeIPA. PACs issued e.g. by a plain MIT Kerberos KDC will not contain the needed PAC data buffers to run the checks.

The following options can be used alone or in a comma-separated list:

no_check — the PAC must not be present and even if it is present no additional checks will be done 🙅
pac_present — the PAC must be present in the service ticket which SSSD will request with the help of the user's TGT. If the PAC is not available the authentication will fail 💀
check_upn — if the PAC is present check if the user principal name (UPN) information is consistent 🔍

check_upn_allow_missing — bestie, this one only makes sense with check_upn. It handles that specific situation where a UPN is set on the server-side but SSSD never actually reads it. The classic example? A FreeIPA domain where ldap_user_principal is pointed at an attribute name that doesn't even exist. People did that to work around issues in the handling of enterprise principals… but that's been fixed for quite a while now, and FreeIPA handles enterprise principals just fine, so there's genuinely no need to set ldap_user_principal anymore. 💅

Right now this option is set by default to avoid regressions in environments like that. If a UPN shows up in the PAC but not in SSSD's cache, you'll get a log message in the system log and in SSSD's debug log. To make that message go away, the move is to evaluate whether ldap_user_principal can be dropped. Can't drop it? Then removing check_upn skips the test entirely and dodges the log message. 🎀

upn_dns_info_present — the PAC must contain the UPN-DNS-INFO buffer. Implies check_upn. ✨
check_upn_dns_info_ex — if the PAC is present and the extension to the UPN-DNS-INFO buffer is available, this checks whether the info inside that extension is consistent. 🦋
upn_dns_info_ex_present — the PAC must contain the extension of the UPN-DNS-INFO buffer. Implies check_upn_dns_info_ex, upn_dns_info_present and check_upn. That's a whole implication chain, she's committed. 😭
Default: no_check (AD and IPA provider: check_upn, check_upn_allow_missing, check_upn_dns_info_ex)

🎀 Session recording configuration options 🎀

So session recording works together with tlog-rec-session(8) — that's part of the tlog package — to log what users actually see and type when they log in on a text terminal. Also peep sssd-session-recording(5) for the full picture. 👀

These are the options that configure it:

scope (string) — one of these strings, which sets the scope of session recording:
- "none" — no users are recorded. 🚫
- "some" — users/groups listed in the users and groups options get recorded. ✨
- "all" — everyone gets recorded. literally everyone. 💀

Default: "none"

users (string) — a comma-separated list of users who should have session recording enabled. Matches user names as returned by NSS — meaning after the possible space replacement, case changes, etc. 🙈

Default: Empty. Matches no users.

groups (string) — a comma-separated list of groups; members of these groups get session recording enabled. Matches group names as returned by NSS — again, after the possible space replacement, case changes, etc. 🫶

NOTE: using this option (like, having it set to anything at all) comes with a considerable performance cost, because every uncached request for a user requires retrieving and matching all the groups that user is a member of. Not me warning you twice. 😭

Default: Empty. Matches no groups.

exclude_users (string) — a comma-separated list of users to be excluded from recording. Only applicable with scope=all. 🚫

Default: Empty. No users excluded.

exclude_groups (string) — a comma-separated list of groups whose members should be excluded from recording. Only applicable with scope=all. 🚫

NOTE: same deal as above — 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 a member of. 💅

Default: Empty. No groups excluded.

👑 DOMAIN SECTIONS 👑

Okay so these configuration options can live in a domain configuration section — that's a section called [domain/NAME] in case you were wondering. 💖

enabled — explicitly enable or disable the domain. If "true", the domain is always "enabled". If "false", the domain is always "disabled". If you don't set this option at all, the domain is enabled only if it's listed in the domains option in the [sssd] section. ⭐
domain_type (string) — tells SSSD whether the domain is meant for POSIX-aware clients like the Name Service Switch, or for applications that don't need POSIX data present or generated. Only objects from POSIX domains are available to the operating system interfaces and utilities. 🦋

Allowed values 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: application domains are currently well tested with id_provider=ldap only.

For an easy way to configure a non-POSIX domain, check out the "Application domains" section.

Default: posix

min_id,max_id (integer) — the UID and GID limits for the domain. If the domain contains an entry outside these limits, it just gets ignored, bye. 👋

For users, this affects the primary GID limit. The user won't be returned to NSS if either the UID or the primary GID is outside the range. For non-primary group memberships though, the ones in range get reported as expected. 💅

These ID limits affect even saving entries to cache — not just returning them by name or ID. Keep that in mind.

Default: 1 for min_id, 0 (no limit) for max_id

enumerate (bool) — determines if a domain can be enumerated, i.e. whether the domain can list all the users and groups it contains. Note that you don't need to enable enumeration for secondary groups to be displayed, bestie. This parameter can be one of:

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 severe 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 go directly to LDAP — though it may be slow, because of the heavy enumeration processing. Saving a large number of entries to cache after the enumeration completes might also be CPU intensive, since 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, because longer timeouts are required to make sure enumeration lookups complete successfully. For more info, refer to the man pages for the specific id_provider in use.

For all the reasons above, enabling enumeration is not recommended, especially in large environments. fr fr, don't do it.

Note: the proxy provider is tested with open source modules like libnss_files and libnss_ldap. 3rd party modules must follow the documented behavior of nss modules to be used in this configuration.

entry_cache_timeout (integer) — how many seconds should nss_sss consider entries valid before asking the backend again? ⏳

The cache expiration timestamps are stored as attributes of individual objects in the cache. So changing the cache timeout only has effect for newly added or expired entries. You should run the sss_cache(8) tool to force refresh of entries that have already been cached. 🙈

Default: 5400

entry_cache_user_timeout (integer) — how many seconds should nss_sss consider user entries valid before asking the backend again? ✨