1SSSD-AD(5) File Formats and Conventions SSSD-AD(5)
2
6 sssd-ad - SSSD Active Directory provider
7
9 This manual page describes the configuration of the AD provider for
10 sssd(8). For a detailed syntax reference, refer to the “FILE FORMAT”
11 section of the sssd.conf(5) manual page.
12 The AD provider is a back end used to connect to an Active Directory
14 server. This provider requires that the machine be joined to the AD
15 domain and a keytab is available. Back end communication occurs over a
16 GSSAPI-encrypted channel, SSL/TLS options should not be used with the
17 AD provider and will be superseded by Kerberos usage.
18 The AD provider supports connecting to Active Directory 2008 R2 or
20 later. Earlier versions may work, but are unsupported.
21 The AD provider can be used to get user information and authenticate
23 users from trusted domains. Currently only trusted domains in the same
24 forest are recognized. In addition servers from trusted domains are
25 always auto-discovered.
26 The AD provider enables SSSD to use the sssd-ldap(5) identity provider
28 and the sssd-krb5(5) authentication provider with optimizations for
29 Active Directory environments. The AD provider accepts the same options
30 used by the sssd-ldap and sssd-krb5 providers with some exceptions.
31 However, it is neither necessary nor recommended to set these options.
32 The AD provider primarily copies the traditional ldap and krb5 provider
34 default options with some exceptions, the differences are listed in the
35 “MODIFIED DEFAULT OPTIONS” section.
36 The AD provider can also be used as an access, chpass, sudo and autofs
38 provider. No configuration of the access provider is required on the
39 client side.
40 If “auth_provider=ad” or “access_provider=ad” is configured in
42 sssd.conf then the id_provider must also be set to “ad”.
43 By default, the AD provider will map UID and GID values from the
45 objectSID parameter in Active Directory. For details on this, see the
46 “ID MAPPING” section below. If you want to disable ID mapping and
47 instead rely on POSIX attributes defined in Active Directory, you
48 should set
49 ldap_id_mapping = False
51 If POSIX attributes should be used, it is recommended for performance
54 reasons that the attributes are also replicated to the Global Catalog.
55 If POSIX attributes are replicated, SSSD will attempt to locate the
56 domain of a requested numerical ID with the help of the Global Catalog
57 and only search that domain. In contrast, if POSIX attributes are not
58 replicated to the Global Catalog, SSSD must search all the domains in
59 the forest sequentially. Please note that the “cache_first” option
60 might be also helpful in speeding up domainless searches. Note that if
61 only a subset of POSIX attributes is present in the Global Catalog, the
62 non-replicated attributes are currently not read from the LDAP port.
63 Users, groups and other entities served by SSSD are always treated as
65 case-insensitive in the AD provider for compatibility with Active
66 Directory's LDAP implementation.
67 SSSD only resolves Active Directory Security Groups. For more
69 information about AD group types see: Active Directory security
70 groups[1]
71 SSSD filters out Domain Local groups from remote domains in the AD
73 forest. By default they are filtered out e.g. when following a nested
74 group hierarchy in remote domains because they are not valid in the
75 local domain. This is done to be in agreement with Active Directory's
76 group-membership assignment which can be seen in the PAC of the
77 Kerberos ticket of a user issued by Active Directory.
78
80 Refer to the section “DOMAIN SECTIONS” of the sssd.conf(5) manual page
81 for details on the configuration of an SSSD domain.
82 ad_domain (string)
84 Specifies the name of the Active Directory domain. This is
85 optional. If not provided, the configuration domain name is used.
86 For proper operation, this option should be specified as the
88 lower-case version of the long version of the Active Directory
89 domain.
90 The short domain name (also known as the NetBIOS or the flat name)
92 is autodetected by the SSSD.
93 ad_enabled_domains (string)
95 A comma-separated list of enabled Active Directory domains. If
96 provided, SSSD will ignore any domains not listed in this option.
97 If left unset, all domains from the AD forest will be available.
98 For proper operation, this option must be specified in all
100 lower-case and as the fully qualified domain name of the Active
101 Directory domain. For example:
102 ad_enabled_domains = sales.example.com, eng.example.com
104 The short domain name (also known as the NetBIOS or the flat name)
107 will be autodetected by SSSD.
108 Default: Not set
110 ad_server, ad_backup_server (string)
112 The comma-separated list of hostnames of the AD servers to which
113 SSSD should connect in order of preference. For more information on
114 failover and server redundancy, see the “FAILOVER” section.
115 This is optional if autodiscovery is enabled. For more information
117 on service discovery, refer to the “SERVICE DISCOVERY” section.
118 Note: Trusted domains will always auto-discover servers even if the
120 primary server is explicitly defined in the ad_server option.
121 ad_hostname (string)
123 Optional. On machines where the hostname(5) does not reflect the
124 fully qualified name, sssd will try to expand the short name. If it
125 is not possible or the short name should be really used instead,
126 set this parameter explicitly.
127 This field is used to determine the host principal in use in the
129 keytab and to perform dynamic DNS updates. It must match the
130 hostname for which the keytab was issued.
131 ad_enable_dns_sites (boolean)
133 Enables DNS sites - location based service discovery.
134 If true and service discovery (see Service Discovery paragraph at
136 the bottom of the man page) is enabled, the SSSD will first attempt
137 to discover the Active Directory server to connect to using the
138 Active Directory Site Discovery and fall back to the DNS SRV
139 records if no AD site is found. The DNS SRV configuration,
140 including the discovery domain, is used during site discovery as
141 well.
142 Default: true
144 ad_access_filter (string)
146 This option specifies LDAP access control filter that the user must
147 match in order to be allowed access. Please note that the
148 “access_provider” option must be explicitly set to “ad” in order
149 for this option to have an effect.
150 The option also supports specifying different filters per domain or
152 forest. This extended filter would consist of:
153 “KEYWORD:NAME:FILTER”. The keyword can be either “DOM”, “FOREST” or
154 missing.
155 If the keyword equals to “DOM” or is missing, then “NAME” specifies
157 the domain or subdomain the filter applies to. If the keyword
158 equals to “FOREST”, then the filter equals to all domains from the
159 forest specified by “NAME”.
160 Multiple filters can be separated with the “?” character,
162 similarly to how search bases work.
163 Nested group membership must be searched for using a special OID
165 “:1.2.840.113556.1.4.1941:” in addition to the full
166 DOM:domain.example.org: syntax to ensure the parser does not
167 attempt to interpret the colon characters associated with the OID.
168 If you do not use this OID then nested group membership will not be
169 resolved. See usage example below and refer here for further
170 information about the OID: [MS-ADTS] section LDAP extensions[2]
171 The most specific match is always used. For example, if the option
173 specified filter for a domain the user is a member of and a global
174 filter, the per-domain filter would be applied. If there are more
175 matches with the same specification, the first one is used.
176 Examples:
178 # apply filter on domain called dom1 only:
180 dom1:(memberOf=cn=admins,ou=groups,dc=dom1,dc=com)
181 # apply filter on domain called dom2 only:
183 DOM:dom2:(memberOf=cn=admins,ou=groups,dc=dom2,dc=com)
184 # apply filter on forest called EXAMPLE.COM only:
186 FOREST:EXAMPLE.COM:(memberOf=cn=admins,ou=groups,dc=example,dc=com)
187 # apply filter for a member of a nested group in dom1:
189 DOM:dom1:(memberOf:1.2.840.113556.1.4.1941:=cn=nestedgroup,ou=groups,dc=example,dc=com)
190 Default: Not set
193 ad_site (string)
195 Specify AD site to which client should try to connect. If this
196 option is not provided, the AD site will be auto-discovered.
197 Default: Not set
199 ad_enable_gc (boolean)
201 By default, the SSSD connects to the Global Catalog first to
202 retrieve users from trusted domains and uses the LDAP port to
203 retrieve group memberships or as a fallback. Disabling this option
204 makes the SSSD only connect to the LDAP port of the current AD
205 server.
206 Please note that disabling Global Catalog support does not disable
208 retrieving users from trusted domains. The SSSD would connect to
209 the LDAP port of trusted domains instead. However, Global Catalog
210 must be used in order to resolve cross-domain group memberships.
211 Default: true
213 ad_gpo_access_control (string)
215 This option specifies the operation mode for GPO-based access
216 control functionality: whether it operates in disabled mode,
217 enforcing mode, or permissive mode. Please note that the
218 “access_provider” option must be explicitly set to “ad” in order
219 for this option to have an effect.
220 GPO-based access control functionality uses GPO policy settings to
222 determine whether or not a particular user is allowed to logon to
223 the host. For more information on the supported policy settings
224 please refer to the “ad_gpo_map” options.
225 Please note that current version of SSSD does not support Active
227 Directory's built-in groups. Built-in groups (such as
228 Administrators with SID S-1-5-32-544) in GPO access control rules
229 will be ignored by SSSD. See upstream issue tracker
230 https://github.com/SSSD/sssd/issues/5063 .
231 Before performing access control SSSD applies group policy security
233 filtering on the GPOs. For every single user login, the
234 applicability of the GPOs that are linked to the host is checked.
235 In order for a GPO to apply to a user, the user or at least one of
236 the groups to which it belongs must have following permissions on
237 the GPO:
238 • Read: The user or one of its groups must have read access to
240 the properties of the GPO (RIGHT_DS_READ_PROPERTY)
241 • Apply Group Policy: The user or at least one of its groups must
243 be allowed to apply the GPO (RIGHT_DS_CONTROL_ACCESS).
244 By default, the Authenticated Users group is present on a GPO and
246 this group has both Read and Apply Group Policy access rights.
247 Since authentication of a user must have been completed
248 successfully before GPO security filtering and access control are
249 started, the Authenticated Users group permissions on the GPO
250 always apply also to the user.
251 NOTE: If the operation mode is set to enforcing, it is possible
253 that users that were previously allowed logon access will now be
254 denied logon access (as dictated by the GPO policy settings). In
255 order to facilitate a smooth transition for administrators, a
256 permissive mode is available that will not enforce the access
257 control rules, but will evaluate them and will output a syslog
258 message if access would have been denied. By examining the logs,
259 administrators can then make the necessary changes before setting
260 the mode to enforcing. For logging GPO-based access control debug
261 level 'trace functions' is required (see sssctl(8) manual page).
262 There are three supported values for this option:
264 • disabled: GPO-based access control rules are neither evaluated
266 nor enforced.
267 • enforcing: GPO-based access control rules are evaluated and
269 enforced.
270 • permissive: GPO-based access control rules are evaluated, but
272 not enforced. Instead, a syslog message will be emitted
273 indicating that the user would have been denied access if this
274 option's value were set to enforcing.
275 Default: enforcing
277 ad_gpo_implicit_deny (boolean)
279 Normally when no applicable GPOs are found the users are allowed
280 access. When this option is set to True users will be allowed
281 access only when explicitly allowed by a GPO rule. Otherwise users
282 will be denied access. This can be used to harden security but be
283 careful when using this option because it can deny access even to
284 users in the built-in Administrators group if no GPO rules apply to
285 them.
286 Default: False
288 The following 2 tables should illustrate when a user is allowed or
290 rejected based on the allow and deny login rights defined on the
291 server-side and the setting of ad_gpo_implicit_deny.
292 ┌───────────────────────────────────────────────┐
294 │ad_gpo_implicit_deny = False (default) │
295 ├────────────┬────────────┬─────────────────────┤
296 │allow-rules │ deny-rules │ results │
297 ├────────────┼────────────┼─────────────────────┤
298 │ missing │ missing │ all users are │
299 │ │ │ allowed │
300 ├────────────┼────────────┼─────────────────────┤
301 │ missing │ present │ only users not in │
302 │ │ │ deny-rules are │
303 │ │ │ allowed │
304 ├────────────┼────────────┼─────────────────────┤
305 │ present │ missing │ only users in │
306 │ │ │ allow-rules are │
307 │ │ │ allowed │
308 ├────────────┼────────────┼─────────────────────┤
309 │ present │ present │ only users in │
310 │ │ │ allow-rules and not │
311 │ │ │ in deny-rules are │
312 │ │ │ allowed │
313 └────────────┴────────────┴─────────────────────┘
314 ┌───────────────────────────────────────────────┐
316 │ad_gpo_implicit_deny = True │
317 ├────────────┬────────────┬─────────────────────┤
318 │allow-rules │ deny-rules │ results │
319 ├────────────┼────────────┼─────────────────────┤
320 │ missing │ missing │ no users are │
321 │ │ │ allowed │
322 ├────────────┼────────────┼─────────────────────┤
323 │ missing │ present │ no users are │
324 │ │ │ allowed │
325 ├────────────┼────────────┼─────────────────────┤
326 │ present │ missing │ only users in │
327 │ │ │ allow-rules are │
328 │ │ │ allowed │
329 ├────────────┼────────────┼─────────────────────┤
330 │ present │ present │ only users in │
331 │ │ │ allow-rules and not │
332 │ │ │ in deny-rules are │
333 │ │ │ allowed │
334 └────────────┴────────────┴─────────────────────┘
335 ad_gpo_ignore_unreadable (boolean)
337 Normally when some group policy containers (AD object) of
338 applicable group policy objects are not readable by SSSD then users
339 are denied access. This option allows to ignore group policy
340 containers and with them associated policies if their attributes in
341 group policy containers are not readable for SSSD.
342 Default: False
344 ad_gpo_cache_timeout (integer)
346 The amount of time between lookups of GPO policy files against the
347 AD server. This will reduce the latency and load on the AD server
348 if there are many access-control requests made in a short period.
349 Default: 5 (seconds)
351 ad_gpo_map_interactive (string)
353 A comma-separated list of PAM service names for which GPO-based
354 access control is evaluated based on the InteractiveLogonRight and
355 DenyInteractiveLogonRight policy settings. Only those GPOs are
356 evaluated for which the user has Read and Apply Group Policy
357 permission (see option “ad_gpo_access_control”). If an evaluated
358 GPO contains the deny interactive logon setting for the user or one
359 of its groups, the user is denied local access. If none of the
360 evaluated GPOs has an interactive logon right defined, the user is
361 granted local access. If at least one evaluated GPO contains
362 interactive logon right settings, the user is granted local access
363 only, if it or at least one of its groups is part of the policy
364 settings.
365 Note: Using the Group Policy Management Editor this value is called
367 "Allow log on locally" and "Deny log on locally".
368 It is possible to add another PAM service name to the default set
370 by using “+service_name” or to explicitly remove a PAM service name
371 from the default set by using “-service_name”. For example, in
372 order to replace a default PAM service name for this logon right
373 (e.g. “login”) with a custom pam service name (e.g.
374 “my_pam_service”), you would use the following configuration:
375 ad_gpo_map_interactive = +my_pam_service, -login
377 Default: the default set of PAM service names includes:
380 • login
382 • su
384 • su-l
386 • gdm-fingerprint
388 • gdm-password
390 • gdm-smartcard
392 • kdm
394 • lightdm
396 • lxdm
398 • sddm
400 • unity
402 • xdm
404 ad_gpo_map_remote_interactive (string)
407 A comma-separated list of PAM service names for which GPO-based
408 access control is evaluated based on the
409 RemoteInteractiveLogonRight and DenyRemoteInteractiveLogonRight
410 policy settings. Only those GPOs are evaluated for which the user
411 has Read and Apply Group Policy permission (see option
412 “ad_gpo_access_control”). If an evaluated GPO contains the deny
413 remote logon setting for the user or one of its groups, the user is
414 denied remote interactive access. If none of the evaluated GPOs has
415 a remote interactive logon right defined, the user is granted
416 remote access. If at least one evaluated GPO contains remote
417 interactive logon right settings, the user is granted remote access
418 only, if it or at least one of its groups is part of the policy
419 settings.
420 Note: Using the Group Policy Management Editor this value is called
422 "Allow log on through Remote Desktop Services" and "Deny log on
423 through Remote Desktop Services".
424 It is possible to add another PAM service name to the default set
426 by using “+service_name” or to explicitly remove a PAM service name
427 from the default set by using “-service_name”. For example, in
428 order to replace a default PAM service name for this logon right
429 (e.g. “sshd”) with a custom pam service name (e.g.
430 “my_pam_service”), you would use the following configuration:
431 ad_gpo_map_remote_interactive = +my_pam_service, -sshd
433 Default: the default set of PAM service names includes:
436 • sshd
438 • cockpit
440 ad_gpo_map_network (string)
443 A comma-separated list of PAM service names for which GPO-based
444 access control is evaluated based on the NetworkLogonRight and
445 DenyNetworkLogonRight policy settings. Only those GPOs are
446 evaluated for which the user has Read and Apply Group Policy
447 permission (see option “ad_gpo_access_control”). If an evaluated
448 GPO contains the deny network logon setting for the user or one of
449 its groups, the user is denied network logon access. If none of the
450 evaluated GPOs has a network logon right defined, the user is
451 granted logon access. If at least one evaluated GPO contains
452 network logon right settings, the user is granted logon access
453 only, if it or at least one of its groups is part of the policy
454 settings.
455 Note: Using the Group Policy Management Editor this value is called
457 "Access this computer from the network" and "Deny access to this
458 computer from the network".
459 It is possible to add another PAM service name to the default set
461 by using “+service_name” or to explicitly remove a PAM service name
462 from the default set by using “-service_name”. For example, in
463 order to replace a default PAM service name for this logon right
464 (e.g. “ftp”) with a custom pam service name (e.g.
465 “my_pam_service”), you would use the following configuration:
466 ad_gpo_map_network = +my_pam_service, -ftp
468 Default: the default set of PAM service names includes:
471 • ftp
473 • samba
475 ad_gpo_map_batch (string)
478 A comma-separated list of PAM service names for which GPO-based
479 access control is evaluated based on the BatchLogonRight and
480 DenyBatchLogonRight policy settings. Only those GPOs are evaluated
481 for which the user has Read and Apply Group Policy permission (see
482 option “ad_gpo_access_control”). If an evaluated GPO contains the
483 deny batch logon setting for the user or one of its groups, the
484 user is denied batch logon access. If none of the evaluated GPOs
485 has a batch logon right defined, the user is granted logon access.
486 If at least one evaluated GPO contains batch logon right settings,
487 the user is granted logon access only, if it or at least one of its
488 groups is part of the policy settings.
489 Note: Using the Group Policy Management Editor this value is called
491 "Allow log on as a batch job" and "Deny log on as a batch job".
492 It is possible to add another PAM service name to the default set
494 by using “+service_name” or to explicitly remove a PAM service name
495 from the default set by using “-service_name”. For example, in
496 order to replace a default PAM service name for this logon right
497 (e.g. “crond”) with a custom pam service name (e.g.
498 “my_pam_service”), you would use the following configuration:
499 ad_gpo_map_batch = +my_pam_service, -crond
501 Note: Cron service name may differ depending on Linux distribution
504 used.
505 Default: the default set of PAM service names includes:
507 • crond
509 ad_gpo_map_service (string)
512 A comma-separated list of PAM service names for which GPO-based
513 access control is evaluated based on the ServiceLogonRight and
514 DenyServiceLogonRight policy settings. Only those GPOs are
515 evaluated for which the user has Read and Apply Group Policy
516 permission (see option “ad_gpo_access_control”). If an evaluated
517 GPO contains the deny service logon setting for the user or one of
518 its groups, the user is denied service logon access. If none of the
519 evaluated GPOs has a service logon right defined, the user is
520 granted logon access. If at least one evaluated GPO contains
521 service logon right settings, the user is granted logon access
522 only, if it or at least one of its groups is part of the policy
523 settings.
524 Note: Using the Group Policy Management Editor this value is called
526 "Allow log on as a service" and "Deny log on as a service".
527 It is possible to add a PAM service name to the default set by
529 using “+service_name”. Since the default set is empty, it is not
530 possible to remove a PAM service name from the default set. For
531 example, in order to add a custom pam service name (e.g.
532 “my_pam_service”), you would use the following configuration:
533 ad_gpo_map_service = +my_pam_service
535 Default: not set
538 ad_gpo_map_permit (string)
540 A comma-separated list of PAM service names for which GPO-based
541 access is always granted, regardless of any GPO Logon Rights.
542 It is possible to add another PAM service name to the default set
544 by using “+service_name” or to explicitly remove a PAM service name
545 from the default set by using “-service_name”. For example, in
546 order to replace a default PAM service name for unconditionally
547 permitted access (e.g. “sudo”) with a custom pam service name
548 (e.g. “my_pam_service”), you would use the following
549 configuration:
550 ad_gpo_map_permit = +my_pam_service, -sudo
552 Default: the default set of PAM service names includes:
555 • polkit-1
557 • sudo
559 • sudo-i
561 • systemd-user
563 ad_gpo_map_deny (string)
566 A comma-separated list of PAM service names for which GPO-based
567 access is always denied, regardless of any GPO Logon Rights.
568 It is possible to add a PAM service name to the default set by
570 using “+service_name”. Since the default set is empty, it is not
571 possible to remove a PAM service name from the default set. For
572 example, in order to add a custom pam service name (e.g.
573 “my_pam_service”), you would use the following configuration:
574 ad_gpo_map_deny = +my_pam_service
576 Default: not set
579 ad_gpo_default_right (string)
581 This option defines how access control is evaluated for PAM service
582 names that are not explicitly listed in one of the ad_gpo_map_*
583 options. This option can be set in two different manners. First,
584 this option can be set to use a default logon right. For example,
585 if this option is set to 'interactive', it means that unmapped PAM
586 service names will be processed based on the InteractiveLogonRight
587 and DenyInteractiveLogonRight policy settings. Alternatively, this
588 option can be set to either always permit or always deny access for
589 unmapped PAM service names.
590 Supported values for this option include:
592 • interactive
594 • remote_interactive
596 • network
598 • batch
600 • service
602 • permit
604 • deny
606 Default: deny
608 ad_maximum_machine_account_password_age (integer)
610 SSSD will check once a day if the machine account password is older
611 than the given age in days and try to renew it. A value of 0 will
612 disable the renewal attempt.
613 Default: 30 days
615 ad_machine_account_password_renewal_opts (string)
617 This option should only be used to test the machine account renewal
618 task. The option expects 2 integers separated by a colon (':'). The
619 first integer defines the interval in seconds how often the task is
620 run. The second specifies the initial timeout in seconds before the
621 task is run for the first time after startup.
622 Default: 86400:750 (24h and 15m)
624 ad_update_samba_machine_account_password (boolean)
626 If enabled, when SSSD renews the machine account password, it will
627 also be updated in Samba's database. This prevents Samba's copy of
628 the machine account password from getting out of date when it is
629 set up to use AD for authentication.
630 Default: false
632 ad_use_ldaps (bool)
634 By default SSSD uses the plain LDAP port 389 and the Global Catalog
635 port 3628. If this option is set to True SSSD will use the LDAPS
636 port 636 and Global Catalog port 3629 with LDAPS protection. Since
637 AD does not allow to have multiple encryption layers on a single
638 connection and we still want to use SASL/GSSAPI or SASL/GSS-SPNEGO
639 for authentication the SASL security property maxssf is set to 0
640 (zero) for those connections.
641 Default: False
643 ad_allow_remote_domain_local_groups (boolean)
645 If this option is set to “true” SSSD will not filter out Domain
646 Local groups from remote domains in the AD forest. By default they
647 are filtered out e.g. when following a nested group hierarchy in
648 remote domains because they are not valid in the local domain. To
649 be compatible with other solutions which make AD users and groups
650 available on Linux client this option was added.
651 Please note that setting this option to “true” will be against the
653 intention of Domain Local group in Active Directory and SHOULD ONLY
654 BE USED TO FACILITATE MIGRATION FROM OTHER SOLUTIONS. Although the
655 group exists and user can be member of the group the intention is
656 that the group should be only used in the domain it is defined and
657 in no others. Since there is only one type of POSIX groups the only
658 way to achieve this on the Linux side is to ignore those groups.
659 This is also done by Active Directory as can be seen in the PAC of
660 the Kerberos ticket for a local service or in tokenGroups requests
661 where remote Domain Local groups are missing as well.
662 Given the comments above, if this option is set to “true” the
664 tokenGroups request must be disabled by setting
665 “ldap_use_tokengroups” to “false” to get consistent
666 group-memberships of a users. Additionally the Global Catalog
667 lookup should be skipped as well by setting “ad_enable_gc” to
668 “false”. Finally it might be necessary to modify
669 “ldap_group_nesting_level” if the remote Domain Local groups can
670 only be found with a deeper nesting level.
671 Default: False
673 dyndns_update (boolean)
675 Optional. This option tells SSSD to automatically update the Active
676 Directory DNS server with the IP address of this client. The update
677 is secured using GSS-TSIG. As a consequence, the Active Directory
678 administrator only needs to allow secure updates for the DNS zone.
679 The IP address of the AD LDAP connection is used for the updates,
680 if it is not otherwise specified by using the “dyndns_iface”
681 option.
682 NOTE: On older systems (such as RHEL 5), for this behavior to work
684 reliably, the default Kerberos realm must be set properly in
685 /etc/krb5.conf
686 Default: true
688 dyndns_ttl (integer)
690 The TTL to apply to the client DNS record when updating it. If
691 dyndns_update is false this has no effect. This will override the
692 TTL serverside if set by an administrator.
693 Default: 3600 (seconds)
695 dyndns_iface (string)
697 Optional. Applicable only when dyndns_update is true. Choose the
698 interface or a list of interfaces whose IP addresses should be used
699 for dynamic DNS updates. Special value “*” implies that IPs from
700 all interfaces should be used.
701 Default: Use the IP addresses of the interface which is used for AD
703 LDAP connection
704 Example: dyndns_iface = em1, vnet1, vnet2
706 dyndns_refresh_interval (integer)
708 How often should the back end perform periodic DNS update in
709 addition to the automatic update performed when the back end goes
710 online. This option is optional and applicable only when
711 dyndns_update is true. Note that the lowest possible value is 60
712 seconds in-case if value is provided less than 60, parameter will
713 assume lowest value only.
714 Default: 86400 (24 hours)
716 dyndns_update_ptr (bool)
718 Whether the PTR record should also be explicitly updated when
719 updating the client's DNS records. Applicable only when
720 dyndns_update is true.
721 Default: True
723 dyndns_force_tcp (bool)
725 Whether the nsupdate utility should default to using TCP for
726 communicating with the DNS server.
727 Default: False (let nsupdate choose the protocol)
729 dyndns_auth (string)
731 Whether the nsupdate utility should use GSS-TSIG authentication for
732 secure updates with the DNS server, insecure updates can be sent by
733 setting this option to 'none'.
734 Default: GSS-TSIG
736 dyndns_auth_ptr (string)
738 Whether the nsupdate utility should use GSS-TSIG authentication for
739 secure PTR updates with the DNS server, insecure updates can be
740 sent by setting this option to 'none'.
741 Default: Same as dyndns_auth
743 dyndns_server (string)
745 The DNS server to use when performing a DNS update. In most setups,
746 it's recommended to leave this option unset.
747 Setting this option makes sense for environments where the DNS
749 server is different from the identity server.
750 Please note that this option will be only used in fallback attempt
752 when previous attempt using autodetected settings failed.
753 Default: None (let nsupdate choose the server)
755 dyndns_update_per_family (boolean)
757 DNS update is by default performed in two steps - IPv4 update and
758 then IPv6 update. In some cases it might be desirable to perform
759 IPv4 and IPv6 update in single step.
760 Default: true
762 override_homedir (string)
764 Override the user's home directory. You can either provide an
765 absolute value or a template. In the template, the following
766 sequences are substituted:
767 %u
769 login name
770 %U
772 UID number
773 %d
775 domain name
776 %f
778 fully qualified user name (user@domain)
779 %l
781 The first letter of the login name.
782 %P
784 UPN - User Principal Name (name@REALM)
785 %o
787 The original home directory retrieved from the identity
788 provider.
789 %h
791 The original home directory retrieved from the identity
792 provider, but in lower case.
793 %H
795 The value of configure option homedir_substring.
796 %%
798 a literal '%'
799 This option can also be set per-domain.
801 example:
803 override_homedir = /home/%u
805 Default: Not set (SSSD will use the value retrieved from LDAP)
808 Please note, the home directory from a specific override for the
810 user, either locally (see sss_override(8)) or centrally managed IPA
811 id-overrides, has a higher precedence and will be used instead of
812 the value given by override_homedir.
813 homedir_substring (string)
815 The value of this option will be used in the expansion of the
816 override_homedir option if the template contains the format string
817 %H. An LDAP directory entry can directly contain this template so
818 that this option can be used to expand the home directory path for
819 each client machine (or operating system). It can be set per-domain
820 or globally in the [nss] section. A value specified in a domain
821 section will override one set in the [nss] section.
822 Default: /home
824 krb5_confd_path (string)
826 Absolute path of a directory where SSSD should place Kerberos
827 configuration snippets.
828 To disable the creation of the configuration snippets set the
830 parameter to 'none'.
831 Default: not set (krb5.include.d subdirectory of SSSD's pubconf
833 directory)
834
836 Certain option defaults do not match their respective backend provider
837 defaults, these option names and AD provider-specific defaults are
838 listed below:
839 KRB5 Provider
841 • krb5_validate = true
842 • krb5_use_enterprise_principal = true
844 LDAP Provider
846 • ldap_schema = ad
847 • ldap_force_upper_case_realm = true
849 • ldap_id_mapping = true
851 • ldap_sasl_mech = GSS-SPNEGO
853 • ldap_referrals = false
855 • ldap_account_expire_policy = ad
857 • ldap_use_tokengroups = true
859 • ldap_sasl_authid = sAMAccountName@REALM (typically
861 SHORTNAME$@REALM)
862 The AD provider looks for a different principal than the LDAP
864 provider by default, because in an Active Directory environment the
865 principals are divided into two groups - User Principals and
866 Service Principals. Only User Principal can be used to obtain a TGT
867 and by default, computer object's principal is constructed from its
868 sAMAccountName and the AD realm. The well-known host/hostname@REALM
869 principal is a Service Principal and thus cannot be used to get a
870 TGT with.
871 NSS configuration
873 • fallback_homedir = /home/%d/%u
874 The AD provider automatically sets "fallback_homedir = /home/%d/%u"
876 to provide personal home directories for users without the
877 homeDirectory attribute. If your AD Domain is properly populated
878 with Posix attributes, and you want to avoid this fallback
879 behavior, you can explicitly set "fallback_homedir = %o".
880 Note that the system typically expects a home directory in /home/%u
882 folder. If you decide to use a different directory structure, some
883 other parts of your system may need adjustments.
884 For example automated creation of home directories in combination
886 with selinux requires selinux adjustment, otherwise the home
887 directory will be created with wrong selinux context.
888
890 The failover feature allows back ends to automatically switch to a
891 different server if the current server fails.
892 Failover Syntax
894 The list of servers is given as a comma-separated list; any number of
895 spaces is allowed around the comma. The servers are listed in order of
896 preference. The list can contain any number of servers.
897 For each failover-enabled config option, two variants exist: primary
899 and backup. The idea is that servers in the primary list are preferred
900 and backup servers are only searched if no primary servers can be
901 reached. If a backup server is selected, a timeout of 31 seconds is
902 set. After this timeout SSSD will periodically try to reconnect to one
903 of the primary servers. If it succeeds, it will replace the current
904 active (backup) server.
905 The Failover Mechanism
907 The failover mechanism distinguishes between a machine and a service.
908 The back end first tries to resolve the hostname of a given machine; if
909 this resolution attempt fails, the machine is considered offline. No
910 further attempts are made to connect to this machine for any other
911 service. If the resolution attempt succeeds, the back end tries to
912 connect to a service on this machine. If the service connection attempt
913 fails, then only this particular service is considered offline and the
914 back end automatically switches over to the next service. The machine
915 is still considered online and might still be tried for another
916 service.
917 Further connection attempts are made to machines or services marked as
919 offline after a specified period of time; this is currently hard coded
920 to 30 seconds.
921 If there are no more machines to try, the back end as a whole switches
923 to offline mode, and then attempts to reconnect every 30 seconds.
924 Failover time outs and tuning
926 Resolving a server to connect to can be as simple as running a single
927 DNS query or can involve several steps, such as finding the correct
928 site or trying out multiple host names in case some of the configured
929 servers are not reachable. The more complex scenarios can take some
930 time and SSSD needs to balance between providing enough time to finish
931 the resolution process but on the other hand, not trying for too long
932 before falling back to offline mode. If the SSSD debug logs show that
933 the server resolution is timing out before a live server is contacted,
934 you can consider changing the time outs.
935 This section lists the available tunables. Please refer to their
937 description in the sssd.conf(5), manual page.
938 dns_resolver_server_timeout
940 Time in milliseconds that sets how long would SSSD talk to a single
941 DNS server before trying next one.
942 Default: 1000
944 dns_resolver_op_timeout
946 Time in seconds to tell how long would SSSD try to resolve single
947 DNS query (e.g. resolution of a hostname or an SRV record) before
948 trying the next hostname or discovery domain.
949 Default: 3
951 dns_resolver_timeout
953 How long would SSSD try to resolve a failover service. This service
954 resolution internally might include several steps, such as
955 resolving DNS SRV queries or locating the site.
956 Default: 6
958 For LDAP-based providers, the resolve operation is performed as part of
960 an LDAP connection operation. Therefore, also the “ldap_opt_timeout”
961 timeout should be set to a larger value than “dns_resolver_timeout”
962 which in turn should be set to a larger value than
963 “dns_resolver_op_timeout” which should be larger than
964 “dns_resolver_server_timeout”.
965
967 The service discovery feature allows back ends to automatically find
968 the appropriate servers to connect to using a special DNS query. This
969 feature is not supported for backup servers.
970 Configuration
972 If no servers are specified, the back end automatically uses service
973 discovery to try to find a server. Optionally, the user may choose to
974 use both fixed server addresses and service discovery by inserting a
975 special keyword, “_srv_”, in the list of servers. The order of
976 preference is maintained. This feature is useful if, for example, the
977 user prefers to use service discovery whenever possible, and fall back
978 to a specific server when no servers can be discovered using DNS.
979 The domain name
981 Please refer to the “dns_discovery_domain” parameter in the
982 sssd.conf(5) manual page for more details.
983 The protocol
985 The queries usually specify _tcp as the protocol. Exceptions are
986 documented in respective option description.
987 See Also
989 For more information on the service discovery mechanism, refer to RFC
990 2782.
991
993 The ID-mapping feature allows SSSD to act as a client of Active
994 Directory without requiring administrators to extend user attributes to
995 support POSIX attributes for user and group identifiers.
996 NOTE: When ID-mapping is enabled, the uidNumber and gidNumber
998 attributes are ignored. This is to avoid the possibility of conflicts
999 between automatically-assigned and manually-assigned values. If you
1000 need to use manually-assigned values, ALL values must be
1001 manually-assigned.
1002 Please note that changing the ID mapping related configuration options
1004 will cause user and group IDs to change. At the moment, SSSD does not
1005 support changing IDs, so the SSSD database must be removed. Because
1006 cached passwords are also stored in the database, removing the database
1007 should only be performed while the authentication servers are
1008 reachable, otherwise users might get locked out. In order to cache the
1009 password, an authentication must be performed. It is not sufficient to
1010 use sss_cache(8) to remove the database, rather the process consists
1011 of:
1012 • Making sure the remote servers are reachable
1014 • Stopping the SSSD service
1016 • Removing the database
1018 • Starting the SSSD service
1020 Moreover, as the change of IDs might necessitate the adjustment of
1022 other system properties such as file and directory ownership, it's
1023 advisable to plan ahead and test the ID mapping configuration
1024 thoroughly.
1025 Mapping Algorithm
1027 Active Directory provides an objectSID for every user and group object
1028 in the directory. This objectSID can be broken up into components that
1029 represent the Active Directory domain identity and the relative
1030 identifier (RID) of the user or group object.
1031 The SSSD ID-mapping algorithm takes a range of available UIDs and
1033 divides it into equally-sized component sections - called "slices"-.
1034 Each slice represents the space available to an Active Directory
1035 domain.
1036 When a user or group entry for a particular domain is encountered for
1038 the first time, the SSSD allocates one of the available slices for that
1039 domain. In order to make this slice-assignment repeatable on different
1040 client machines, we select the slice based on the following algorithm:
1041 The SID string is passed through the murmurhash3 algorithm to convert
1043 it to a 32-bit hashed value. We then take the modulus of this value
1044 with the total number of available slices to pick the slice.
1045 NOTE: It is possible to encounter collisions in the hash and subsequent
1047 modulus. In these situations, we will select the next available slice,
1048 but it may not be possible to reproduce the same exact set of slices on
1049 other machines (since the order that they are encountered will
1050 determine their slice). In this situation, it is recommended to either
1051 switch to using explicit POSIX attributes in Active Directory
1052 (disabling ID-mapping) or configure a default domain to guarantee that
1053 at least one is always consistent. See “Configuration” for details.
1054 Configuration
1056 Minimum configuration (in the “[domain/DOMAINNAME]” section):
1057 ldap_id_mapping = True
1059 ldap_schema = ad
1060 The default configuration results in configuring 10,000 slices, each
1062 capable of holding up to 200,000 IDs, starting from 200,000 and going
1063 up to 2,000,200,000. This should be sufficient for most deployments.
1064 Advanced Configuration
1066 ldap_idmap_range_min (integer)
1067 Specifies the lower (inclusive) bound of the range of POSIX IDs
1068 to use for mapping Active Directory user and group SIDs. It is
1069 the first POSIX ID which can be used for the mapping.
1070 NOTE: This option is different from “min_id” in that “min_id”
1072 acts to filter the output of requests to this domain, whereas
1073 this option controls the range of ID assignment. This is a
1074 subtle distinction, but the good general advice would be to
1075 have “min_id” be less-than or equal to “ldap_idmap_range_min”
1076 Default: 200000
1078 ldap_idmap_range_max (integer)
1080 Specifies the upper (exclusive) bound of the range of POSIX IDs
1081 to use for mapping Active Directory user and group SIDs. It is
1082 the first POSIX ID which cannot be used for the mapping
1083 anymore, i.e. one larger than the last one which can be used
1084 for the mapping.
1085 NOTE: This option is different from “max_id” in that “max_id”
1087 acts to filter the output of requests to this domain, whereas
1088 this option controls the range of ID assignment. This is a
1089 subtle distinction, but the good general advice would be to
1090 have “max_id” be greater-than or equal to
1091 “ldap_idmap_range_max”
1092 Default: 2000200000
1094 ldap_idmap_range_size (integer)
1096 Specifies the number of IDs available for each slice. If the
1097 range size does not divide evenly into the min and max values,
1098 it will create as many complete slices as it can.
1099 NOTE: The value of this option must be at least as large as the
1101 highest user RID planned for use on the Active Directory
1102 server. User lookups and login will fail for any user whose RID
1103 is greater than this value.
1104 For example, if your most recently-added Active Directory user
1106 has objectSid=S-1-5-21-2153326666-2176343378-3404031434-1107,
1107 “ldap_idmap_range_size” must be at least 1108 as range size is
1108 equal to maximal SID minus minimal SID plus one (e.g. 1108 =
1109 1107 - 0 + 1).
1110 It is important to plan ahead for future expansion, as changing
1112 this value will result in changing all of the ID mappings on
1113 the system, leading to users with different local IDs than they
1114 previously had.
1115 Default: 200000
1117 ldap_idmap_default_domain_sid (string)
1119 Specify the domain SID of the default domain. This will
1120 guarantee that this domain will always be assigned to slice
1121 zero in the ID map, bypassing the murmurhash algorithm
1122 described above.
1123 Default: not set
1125 ldap_idmap_default_domain (string)
1127 Specify the name of the default domain.
1128 Default: not set
1130 ldap_idmap_autorid_compat (boolean)
1132 Changes the behavior of the ID-mapping algorithm to behave more
1133 similarly to winbind's “idmap_autorid” algorithm.
1134 When this option is configured, domains will be allocated
1136 starting with slice zero and increasing monatomically with each
1137 additional domain.
1138 NOTE: This algorithm is non-deterministic (it depends on the
1140 order that users and groups are requested). If this mode is
1141 required for compatibility with machines running winbind, it is
1142 recommended to also use the “ldap_idmap_default_domain_sid”
1143 option to guarantee that at least one domain is consistently
1144 allocated to slice zero.
1145 Default: False
1147 ldap_idmap_helper_table_size (integer)
1149 Maximal number of secondary slices that is tried when
1150 performing mapping from UNIX id to SID.
1151 Note: Additional secondary slices might be generated when SID
1153 is being mapped to UNIX id and RID part of SID is out of range
1154 for secondary slices generated so far. If value of
1155 ldap_idmap_helper_table_size is equal to 0 then no additional
1156 secondary slices are generated.
1157 Default: 10
1159 Well-Known SIDs
1161 SSSD supports to look up the names of Well-Known SIDs, i.e. SIDs with a
1162 special hardcoded meaning. Since the generic users and groups related
1163 to those Well-Known SIDs have no equivalent in a Linux/UNIX environment
1164 no POSIX IDs are available for those objects.
1165 The SID name space is organized in authorities which can be seen as
1167 different domains. The authorities for the Well-Known SIDs are
1168 • Null Authority
1170 • World Authority
1172 • Local Authority
1174 • Creator Authority
1176 • Mandatory Label Authority
1178 • Authentication Authority
1180 • NT Authority
1182 • Built-in
1184 The capitalized version of these names are used as domain names when
1186 returning the fully qualified name of a Well-Known SID.
1187 Since some utilities allow to modify SID based access control
1189 information with the help of a name instead of using the SID directly
1190 SSSD supports to look up the SID by the name as well. To avoid
1191 collisions only the fully qualified names can be used to look up
1192 Well-Known SIDs. As a result the domain names “NULL AUTHORITY”, “WORLD
1193 AUTHORITY”, “LOCAL AUTHORITY”, “CREATOR AUTHORITY”, “MANDATORY LABEL
1194 AUTHORITY”, “AUTHENTICATION AUTHORITY”, “NT AUTHORITY” and “BUILTIN”
1195 should not be used as domain names in sssd.conf.
1196
1198 The following example assumes that SSSD is correctly configured and
1199 example.com is one of the domains in the [sssd] section. This example
1200 shows only the AD provider-specific options.
1201 [domain/EXAMPLE]
1203 id_provider = ad
1204 auth_provider = ad
1205 access_provider = ad
1206 chpass_provider = ad
1207 ad_server = dc1.example.com
1209 ad_hostname = client.example.com
1210 ad_domain = example.com
1211
1214 The AD access control provider checks if the account is expired. It has
1215 the same effect as the following configuration of the LDAP provider:
1216 access_provider = ldap
1218 ldap_access_order = expire
1219 ldap_account_expire_policy = ad
1220 However, unless the “ad” access control provider is explicitly
1222 configured, the default access provider is “permit”. Please note that
1223 if you configure an access provider other than “ad”, you need to set
1224 all the connection parameters (such as LDAP URIs and encryption
1225 details) manually.
1226 When the autofs provider is set to “ad”, the RFC2307 schema attribute
1228 mapping (nisMap, nisObject, ...) is used, because these attributes are
1229 included in the default Active Directory schema.
1230
1232 sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
1233 sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-sudo(5), sssd-session-
1234 recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8),
1235 sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
1236 sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5)
1237 sssd-systemtap(5)
1238
1240 The SSSD upstream - https://github.com/SSSD/sssd/
1241
1243 1. Active Directory security groups
1244 https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/manage/understand-security-groups
1245 2. [MS-ADTS] section LDAP extensions
1247 https://msdn.microsoft.com/en-us/library/cc223367.aspx
1248SSSD 12/09/2022 SSSD-AD(5)