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
69 Refer to the section “DOMAIN SECTIONS” of the sssd.conf(5) manual page
70 for details on the configuration of an SSSD domain.
71 ad_domain (string)
73 Specifies the name of the Active Directory domain. This is
74 optional. If not provided, the configuration domain name is used.
75 For proper operation, this option should be specified as the
77 lower-case version of the long version of the Active Directory
78 domain.
79 The short domain name (also known as the NetBIOS or the flat name)
81 is autodetected by the SSSD.
82 ad_enabled_domains (string)
84 A comma-separated list of enabled Active Directory domains. If
85 provided, SSSD will ignore any domains not listed in this option.
86 If left unset, all domains from the AD forest will be available.
87 For proper operation, this option must be specified in all
89 lower-case and as the fully qualified domain name of the Active
90 Directory domain. For example:
91 ad_enabled_domains = sales.example.com, eng.example.com
93 The short domain name (also known as the NetBIOS or the flat name)
96 will be autodetected by SSSD.
97 Default: Not set
99 ad_server, ad_backup_server (string)
101 The comma-separated list of hostnames of the AD servers to which
102 SSSD should connect in order of preference. For more information on
103 failover and server redundancy, see the “FAILOVER” section.
104 This is optional if autodiscovery is enabled. For more information
106 on service discovery, refer to the “SERVICE DISCOVERY” section.
107 Note: Trusted domains will always auto-discover servers even if the
109 primary server is explicitly defined in the ad_server option.
110 ad_hostname (string)
112 Optional. On machines where the hostname(5) does not reflect the
113 fully qualified name, sssd will try to expand the short name. If it
114 is not possible or the short name should be really used instead,
115 set this parameter explicitly.
116 This field is used to determine the host principal in use in the
118 keytab and to perform dynamic DNS updates. It must match the
119 hostname for which the keytab was issued.
120 ad_enable_dns_sites (boolean)
122 Enables DNS sites - location based service discovery.
123 If true and service discovery (see Service Discovery paragraph at
125 the bottom of the man page) is enabled, the SSSD will first attempt
126 to discover the Active Directory server to connect to using the
127 Active Directory Site Discovery and fall back to the DNS SRV
128 records if no AD site is found. The DNS SRV configuration,
129 including the discovery domain, is used during site discovery as
130 well.
131 Default: true
133 ad_access_filter (string)
135 This option specifies LDAP access control filter that the user must
136 match in order to be allowed access. Please note that the
137 “access_provider” option must be explicitly set to “ad” in order
138 for this option to have an effect.
139 The option also supports specifying different filters per domain or
141 forest. This extended filter would consist of:
142 “KEYWORD:NAME:FILTER”. The keyword can be either “DOM”, “FOREST” or
143 missing.
144 If the keyword equals to “DOM” or is missing, then “NAME” specifies
146 the domain or subdomain the filter applies to. If the keyword
147 equals to “FOREST”, then the filter equals to all domains from the
148 forest specified by “NAME”.
149 Multiple filters can be separated with the “?” character,
151 similarly to how search bases work.
152 Nested group membership must be searched for using a special OID
154 “:1.2.840.113556.1.4.1941:” in addition to the full
155 DOM:domain.example.org: syntax to ensure the parser does not
156 attempt to interpret the colon characters associated with the OID.
157 If you do not use this OID then nested group membership will not be
158 resolved. See usage example below and refer here for further
159 information about the OID: [MS-ADTS] section LDAP extensions[1]
160 The most specific match is always used. For example, if the option
162 specified filter for a domain the user is a member of and a global
163 filter, the per-domain filter would be applied. If there are more
164 matches with the same specification, the first one is used.
165 Examples:
167 # apply filter on domain called dom1 only:
169 dom1:(memberOf=cn=admins,ou=groups,dc=dom1,dc=com)
170 # apply filter on domain called dom2 only:
172 DOM:dom2:(memberOf=cn=admins,ou=groups,dc=dom2,dc=com)
173 # apply filter on forest called EXAMPLE.COM only:
175 FOREST:EXAMPLE.COM:(memberOf=cn=admins,ou=groups,dc=example,dc=com)
176 # apply filter for a member of a nested group in dom1:
178 DOM:dom1:(memberOf:1.2.840.113556.1.4.1941:=cn=nestedgroup,ou=groups,dc=example,dc=com)
179 Default: Not set
182 ad_site (string)
184 Specify AD site to which client should try to connect. If this
185 option is not provided, the AD site will be auto-discovered.
186 Default: Not set
188 ad_enable_gc (boolean)
190 By default, the SSSD connects to the Global Catalog first to
191 retrieve users from trusted domains and uses the LDAP port to
192 retrieve group memberships or as a fallback. Disabling this option
193 makes the SSSD only connect to the LDAP port of the current AD
194 server.
195 Please note that disabling Global Catalog support does not disable
197 retrieving users from trusted domains. The SSSD would connect to
198 the LDAP port of trusted domains instead. However, Global Catalog
199 must be used in order to resolve cross-domain group memberships.
200 Default: true
202 ad_gpo_access_control (string)
204 This option specifies the operation mode for GPO-based access
205 control functionality: whether it operates in disabled mode,
206 enforcing mode, or permissive mode. Please note that the
207 “access_provider” option must be explicitly set to “ad” in order
208 for this option to have an effect.
209 GPO-based access control functionality uses GPO policy settings to
211 determine whether or not a particular user is allowed to logon to
212 the host. For more information on the supported policy settings
213 please refer to the “ad_gpo_map” options.
214 Please note that current version of SSSD does not support Active
216 Directory's built-in groups. Built-in groups (such as
217 Administrators with SID S-1-5-32-544) in GPO access control rules
218 will be ignored by SSSD. See upstream issue tracker
219 https://github.com/SSSD/sssd/issues/5063 .
220 Before performing access control SSSD applies group policy security
222 filtering on the GPOs. For every single user login, the
223 applicability of the GPOs that are linked to the host is checked.
224 In order for a GPO to apply to a user, the user or at least one of
225 the groups to which it belongs must have following permissions on
226 the GPO:
227 • Read: The user or one of its groups must have read access to
229 the properties of the GPO (RIGHT_DS_READ_PROPERTY)
230 • Apply Group Policy: The user or at least one of its groups must
232 be allowed to apply the GPO (RIGHT_DS_CONTROL_ACCESS).
233 By default, the Authenticated Users group is present on a GPO and
235 this group has both Read and Apply Group Policy access rights.
236 Since authentication of a user must have been completed
237 successfully before GPO security filtering and access control are
238 started, the Authenticated Users group permissions on the GPO
239 always apply also to the user.
240 NOTE: If the operation mode is set to enforcing, it is possible
242 that users that were previously allowed logon access will now be
243 denied logon access (as dictated by the GPO policy settings). In
244 order to facilitate a smooth transition for administrators, a
245 permissive mode is available that will not enforce the access
246 control rules, but will evaluate them and will output a syslog
247 message if access would have been denied. By examining the logs,
248 administrators can then make the necessary changes before setting
249 the mode to enforcing. For logging GPO-based access control debug
250 level 'trace functions' is required (see sssctl(8) manual page).
251 There are three supported values for this option:
253 • disabled: GPO-based access control rules are neither evaluated
255 nor enforced.
256 • enforcing: GPO-based access control rules are evaluated and
258 enforced.
259 • permissive: GPO-based access control rules are evaluated, but
261 not enforced. Instead, a syslog message will be emitted
262 indicating that the user would have been denied access if this
263 option's value were set to enforcing.
264 Default: enforcing
266 ad_gpo_implicit_deny (boolean)
268 Normally when no applicable GPOs are found the users are allowed
269 access. When this option is set to True users will be allowed
270 access only when explicitly allowed by a GPO rule. Otherwise users
271 will be denied access. This can be used to harden security but be
272 careful when using this option because it can deny access even to
273 users in the built-in Administrators group if no GPO rules apply to
274 them.
275 Default: False
277 The following 2 tables should illustrate when a user is allowed or
279 rejected based on the allow and deny login rights defined on the
280 server-side and the setting of ad_gpo_implicit_deny.
281 ┌───────────────────────────────────────────────┐
283 │ad_gpo_implicit_deny = False (default) │
284 ├────────────┬────────────┬─────────────────────┤
285 │allow-rules │ deny-rules │ results │
286 ├────────────┼────────────┼─────────────────────┤
287 │ missing │ missing │ all users are │
288 │ │ │ allowed │
289 ├────────────┼────────────┼─────────────────────┤
290 │ missing │ present │ only users not in │
291 │ │ │ deny-rules are │
292 │ │ │ allowed │
293 ├────────────┼────────────┼─────────────────────┤
294 │ present │ missing │ only users in │
295 │ │ │ allow-rules are │
296 │ │ │ allowed │
297 ├────────────┼────────────┼─────────────────────┤
298 │ present │ present │ only users in │
299 │ │ │ allow-rules and not │
300 │ │ │ in deny-rules are │
301 │ │ │ allowed │
302 └────────────┴────────────┴─────────────────────┘
303 ┌───────────────────────────────────────────────┐
305 │ad_gpo_implicit_deny = True │
306 ├────────────┬────────────┬─────────────────────┤
307 │allow-rules │ deny-rules │ results │
308 ├────────────┼────────────┼─────────────────────┤
309 │ missing │ missing │ no users are │
310 │ │ │ allowed │
311 ├────────────┼────────────┼─────────────────────┤
312 │ missing │ present │ no users are │
313 │ │ │ allowed │
314 ├────────────┼────────────┼─────────────────────┤
315 │ present │ missing │ only users in │
316 │ │ │ allow-rules are │
317 │ │ │ allowed │
318 ├────────────┼────────────┼─────────────────────┤
319 │ present │ present │ only users in │
320 │ │ │ allow-rules and not │
321 │ │ │ in deny-rules are │
322 │ │ │ allowed │
323 └────────────┴────────────┴─────────────────────┘
324 ad_gpo_ignore_unreadable (boolean)
326 Normally when some group policy containers (AD object) of
327 applicable group policy objects are not readable by SSSD then users
328 are denied access. This option allows to ignore group policy
329 containers and with them associated policies if their attributes in
330 group policy containers are not readable for SSSD.
331 Default: False
333 ad_gpo_cache_timeout (integer)
335 The amount of time between lookups of GPO policy files against the
336 AD server. This will reduce the latency and load on the AD server
337 if there are many access-control requests made in a short period.
338 Default: 5 (seconds)
340 ad_gpo_map_interactive (string)
342 A comma-separated list of PAM service names for which GPO-based
343 access control is evaluated based on the InteractiveLogonRight and
344 DenyInteractiveLogonRight policy settings. Only those GPOs are
345 evaluated for which the user has Read and Apply Group Policy
346 permission (see option “ad_gpo_access_control”). If an evaluated
347 GPO contains the deny interactive logon setting for the user or one
348 of its groups, the user is denied local access. If none of the
349 evaluated GPOs has an interactive logon right defined, the user is
350 granted local access. If at least one evaluated GPO contains
351 interactive logon right settings, the user is granted local access
352 only, if it or at least one of its groups is part of the policy
353 settings.
354 Note: Using the Group Policy Management Editor this value is called
356 "Allow log on locally" and "Deny log on locally".
357 It is possible to add another PAM service name to the default set
359 by using “+service_name” or to explicitly remove a PAM service name
360 from the default set by using “-service_name”. For example, in
361 order to replace a default PAM service name for this logon right
362 (e.g. “login”) with a custom pam service name (e.g.
363 “my_pam_service”), you would use the following configuration:
364 ad_gpo_map_interactive = +my_pam_service, -login
366 Default: the default set of PAM service names includes:
369 • login
371 • su
373 • su-l
375 • gdm-fingerprint
377 • gdm-password
379 • gdm-smartcard
381 • kdm
383 • lightdm
385 • lxdm
387 • sddm
389 • unity
391 • xdm
393 ad_gpo_map_remote_interactive (string)
396 A comma-separated list of PAM service names for which GPO-based
397 access control is evaluated based on the
398 RemoteInteractiveLogonRight and DenyRemoteInteractiveLogonRight
399 policy settings. Only those GPOs are evaluated for which the user
400 has Read and Apply Group Policy permission (see option
401 “ad_gpo_access_control”). If an evaluated GPO contains the deny
402 remote logon setting for the user or one of its groups, the user is
403 denied remote interactive access. If none of the evaluated GPOs has
404 a remote interactive logon right defined, the user is granted
405 remote access. If at least one evaluated GPO contains remote
406 interactive logon right settings, the user is granted remote access
407 only, if it or at least one of its groups is part of the policy
408 settings.
409 Note: Using the Group Policy Management Editor this value is called
411 "Allow log on through Remote Desktop Services" and "Deny log on
412 through Remote Desktop Services".
413 It is possible to add another PAM service name to the default set
415 by using “+service_name” or to explicitly remove a PAM service name
416 from the default set by using “-service_name”. For example, in
417 order to replace a default PAM service name for this logon right
418 (e.g. “sshd”) with a custom pam service name (e.g.
419 “my_pam_service”), you would use the following configuration:
420 ad_gpo_map_remote_interactive = +my_pam_service, -sshd
422 Default: the default set of PAM service names includes:
425 • sshd
427 • cockpit
429 ad_gpo_map_network (string)
432 A comma-separated list of PAM service names for which GPO-based
433 access control is evaluated based on the NetworkLogonRight and
434 DenyNetworkLogonRight policy settings. Only those GPOs are
435 evaluated for which the user has Read and Apply Group Policy
436 permission (see option “ad_gpo_access_control”). If an evaluated
437 GPO contains the deny network logon setting for the user or one of
438 its groups, the user is denied network logon access. If none of the
439 evaluated GPOs has a network logon right defined, the user is
440 granted logon access. If at least one evaluated GPO contains
441 network logon right settings, the user is granted logon access
442 only, if it or at least one of its groups is part of the policy
443 settings.
444 Note: Using the Group Policy Management Editor this value is called
446 "Access this computer from the network" and "Deny access to this
447 computer from the network".
448 It is possible to add another PAM service name to the default set
450 by using “+service_name” or to explicitly remove a PAM service name
451 from the default set by using “-service_name”. For example, in
452 order to replace a default PAM service name for this logon right
453 (e.g. “ftp”) with a custom pam service name (e.g.
454 “my_pam_service”), you would use the following configuration:
455 ad_gpo_map_network = +my_pam_service, -ftp
457 Default: the default set of PAM service names includes:
460 • ftp
462 • samba
464 ad_gpo_map_batch (string)
467 A comma-separated list of PAM service names for which GPO-based
468 access control is evaluated based on the BatchLogonRight and
469 DenyBatchLogonRight policy settings. Only those GPOs are evaluated
470 for which the user has Read and Apply Group Policy permission (see
471 option “ad_gpo_access_control”). If an evaluated GPO contains the
472 deny batch logon setting for the user or one of its groups, the
473 user is denied batch logon access. If none of the evaluated GPOs
474 has a batch logon right defined, the user is granted logon access.
475 If at least one evaluated GPO contains batch logon right settings,
476 the user is granted logon access only, if it or at least one of its
477 groups is part of the policy settings.
478 Note: Using the Group Policy Management Editor this value is called
480 "Allow log on as a batch job" and "Deny log on as a batch job".
481 It is possible to add another PAM service name to the default set
483 by using “+service_name” or to explicitly remove a PAM service name
484 from the default set by using “-service_name”. For example, in
485 order to replace a default PAM service name for this logon right
486 (e.g. “crond”) with a custom pam service name (e.g.
487 “my_pam_service”), you would use the following configuration:
488 ad_gpo_map_batch = +my_pam_service, -crond
490 Note: Cron service name may differ depending on Linux distribution
493 used.
494 Default: the default set of PAM service names includes:
496 • crond
498 ad_gpo_map_service (string)
501 A comma-separated list of PAM service names for which GPO-based
502 access control is evaluated based on the ServiceLogonRight and
503 DenyServiceLogonRight policy settings. Only those GPOs are
504 evaluated for which the user has Read and Apply Group Policy
505 permission (see option “ad_gpo_access_control”). If an evaluated
506 GPO contains the deny service logon setting for the user or one of
507 its groups, the user is denied service logon access. If none of the
508 evaluated GPOs has a service logon right defined, the user is
509 granted logon access. If at least one evaluated GPO contains
510 service logon right settings, the user is granted logon access
511 only, if it or at least one of its groups is part of the policy
512 settings.
513 Note: Using the Group Policy Management Editor this value is called
515 "Allow log on as a service" and "Deny log on as a service".
516 It is possible to add a PAM service name to the default set by
518 using “+service_name”. Since the default set is empty, it is not
519 possible to remove a PAM service name from the default set. For
520 example, in order to add a custom pam service name (e.g.
521 “my_pam_service”), you would use the following configuration:
522 ad_gpo_map_service = +my_pam_service
524 Default: not set
527 ad_gpo_map_permit (string)
529 A comma-separated list of PAM service names for which GPO-based
530 access is always granted, regardless of any GPO Logon Rights.
531 It is possible to add another PAM service name to the default set
533 by using “+service_name” or to explicitly remove a PAM service name
534 from the default set by using “-service_name”. For example, in
535 order to replace a default PAM service name for unconditionally
536 permitted access (e.g. “sudo”) with a custom pam service name
537 (e.g. “my_pam_service”), you would use the following
538 configuration:
539 ad_gpo_map_permit = +my_pam_service, -sudo
541 Default: the default set of PAM service names includes:
544 • polkit-1
546 • sudo
548 • sudo-i
550 • systemd-user
552 ad_gpo_map_deny (string)
555 A comma-separated list of PAM service names for which GPO-based
556 access is always denied, regardless of any GPO Logon Rights.
557 It is possible to add a PAM service name to the default set by
559 using “+service_name”. Since the default set is empty, it is not
560 possible to remove a PAM service name from the default set. For
561 example, in order to add a custom pam service name (e.g.
562 “my_pam_service”), you would use the following configuration:
563 ad_gpo_map_deny = +my_pam_service
565 Default: not set
568 ad_gpo_default_right (string)
570 This option defines how access control is evaluated for PAM service
571 names that are not explicitly listed in one of the ad_gpo_map_*
572 options. This option can be set in two different manners. First,
573 this option can be set to use a default logon right. For example,
574 if this option is set to 'interactive', it means that unmapped PAM
575 service names will be processed based on the InteractiveLogonRight
576 and DenyInteractiveLogonRight policy settings. Alternatively, this
577 option can be set to either always permit or always deny access for
578 unmapped PAM service names.
579 Supported values for this option include:
581 • interactive
583 • remote_interactive
585 • network
587 • batch
589 • service
591 • permit
593 • deny
595 Default: deny
597 ad_maximum_machine_account_password_age (integer)
599 SSSD will check once a day if the machine account password is older
600 than the given age in days and try to renew it. A value of 0 will
601 disable the renewal attempt.
602 Default: 30 days
604 ad_machine_account_password_renewal_opts (string)
606 This option should only be used to test the machine account renewal
607 task. The option expects 2 integers separated by a colon (':'). The
608 first integer defines the interval in seconds how often the task is
609 run. The second specifies the initial timeout in seconds before the
610 task is run for the first time after startup.
611 Default: 86400:750 (24h and 15m)
613 ad_update_samba_machine_account_password (boolean)
615 If enabled, when SSSD renews the machine account password, it will
616 also be updated in Samba's database. This prevents Samba's copy of
617 the machine account password from getting out of date when it is
618 set up to use AD for authentication.
619 Default: false
621 ad_use_ldaps (bool)
623 By default SSSD uses the plain LDAP port 389 and the Global Catalog
624 port 3628. If this option is set to True SSSD will use the LDAPS
625 port 636 and Global Catalog port 3629 with LDAPS protection. Since
626 AD does not allow to have multiple encryption layers on a single
627 connection and we still want to use SASL/GSSAPI or SASL/GSS-SPNEGO
628 for authentication the SASL security property maxssf is set to 0
629 (zero) for those connections.
630 Default: False
632 ad_allow_remote_domain_local_groups (boolean)
634 If this option is set to “true” SSSD will not filter out Domain
635 Local groups from remote domains in the AD forest. By default they
636 are filtered out e.g. when following a nested group hierarchy in
637 remote domains because they are not valid in the local domain. To
638 be compatible with other solutions which make AD users and groups
639 available on Linux client this option was added.
640 Please note that setting this option to “true” will be against the
642 intention of Domain Local group in Active Directory and SHOULD ONLY
643 BE USED TO FACILITATE MIGRATION FROM OTHER SOLUTIONS. Although the
644 group exists and user can be member of the group the intention is
645 that the group should be only used in the domain it is defined and
646 in no others. Since there is only one type of POSIX groups the only
647 way to achieve this on the Linux side is to ignore those groups.
648 This is also done by Active Directory as can be seen in the PAC of
649 the Kerberos ticket for a local service or in tokenGroups requests
650 where remote Domain Local groups are missing as well.
651 Given the comments above, if this option is set to “true” the
653 tokenGroups request must be disabled by setting
654 “ldap_use_tokengroups” to “false” to get consistent
655 group-memberships of a users. Additionally the Global Catalog
656 lookup should be skipped as well by setting “ad_enable_gc” to
657 “false”. Finally it might be necessary to modify
658 “ldap_group_nesting_level” if the remote Domain Local groups can
659 only be found with a deeper nesting level.
660 Default: False
662 dyndns_update (boolean)
664 Optional. This option tells SSSD to automatically update the Active
665 Directory DNS server with the IP address of this client. The update
666 is secured using GSS-TSIG. As a consequence, the Active Directory
667 administrator only needs to allow secure updates for the DNS zone.
668 The IP address of the AD LDAP connection is used for the updates,
669 if it is not otherwise specified by using the “dyndns_iface”
670 option.
671 NOTE: On older systems (such as RHEL 5), for this behavior to work
673 reliably, the default Kerberos realm must be set properly in
674 /etc/krb5.conf
675 Default: true
677 dyndns_ttl (integer)
679 The TTL to apply to the client DNS record when updating it. If
680 dyndns_update is false this has no effect. This will override the
681 TTL serverside if set by an administrator.
682 Default: 3600 (seconds)
684 dyndns_iface (string)
686 Optional. Applicable only when dyndns_update is true. Choose the
687 interface or a list of interfaces whose IP addresses should be used
688 for dynamic DNS updates. Special value “*” implies that IPs from
689 all interfaces should be used.
690 Default: Use the IP addresses of the interface which is used for AD
692 LDAP connection
693 Example: dyndns_iface = em1, vnet1, vnet2
695 dyndns_refresh_interval (integer)
697 How often should the back end perform periodic DNS update in
698 addition to the automatic update performed when the back end goes
699 online. This option is optional and applicable only when
700 dyndns_update is true. Note that the lowest possible value is 60
701 seconds in-case if value is provided less than 60, parameter will
702 assume lowest value only.
703 Default: 86400 (24 hours)
705 dyndns_update_ptr (bool)
707 Whether the PTR record should also be explicitly updated when
708 updating the client's DNS records. Applicable only when
709 dyndns_update is true.
710 Default: True
712 dyndns_force_tcp (bool)
714 Whether the nsupdate utility should default to using TCP for
715 communicating with the DNS server.
716 Default: False (let nsupdate choose the protocol)
718 dyndns_auth (string)
720 Whether the nsupdate utility should use GSS-TSIG authentication for
721 secure updates with the DNS server, insecure updates can be sent by
722 setting this option to 'none'.
723 Default: GSS-TSIG
725 dyndns_auth_ptr (string)
727 Whether the nsupdate utility should use GSS-TSIG authentication for
728 secure PTR updates with the DNS server, insecure updates can be
729 sent by setting this option to 'none'.
730 Default: Same as dyndns_auth
732 dyndns_server (string)
734 The DNS server to use when performing a DNS update. In most setups,
735 it's recommended to leave this option unset.
736 Setting this option makes sense for environments where the DNS
738 server is different from the identity server.
739 Please note that this option will be only used in fallback attempt
741 when previous attempt using autodetected settings failed.
742 Default: None (let nsupdate choose the server)
744 dyndns_update_per_family (boolean)
746 DNS update is by default performed in two steps - IPv4 update and
747 then IPv6 update. In some cases it might be desirable to perform
748 IPv4 and IPv6 update in single step.
749 Default: true
751 override_homedir (string)
753 Override the user's home directory. You can either provide an
754 absolute value or a template. In the template, the following
755 sequences are substituted:
756 %u
758 login name
759 %U
761 UID number
762 %d
764 domain name
765 %f
767 fully qualified user name (user@domain)
768 %l
770 The first letter of the login name.
771 %P
773 UPN - User Principal Name (name@REALM)
774 %o
776 The original home directory retrieved from the identity
777 provider.
778 %H
780 The value of configure option homedir_substring.
781 %%
783 a literal '%'
784 This option can also be set per-domain.
786 example:
788 override_homedir = /home/%u
790 Default: Not set (SSSD will use the value retrieved from LDAP)
793 Please note, the home directory from a specific override for the
795 user, either locally (see sss_override(8)) or centrally managed IPA
796 id-overrides, has a higher precedence and will be used instead of
797 the value given by override_homedir.
798 homedir_substring (string)
800 The value of this option will be used in the expansion of the
801 override_homedir option if the template contains the format string
802 %H. An LDAP directory entry can directly contain this template so
803 that this option can be used to expand the home directory path for
804 each client machine (or operating system). It can be set per-domain
805 or globally in the [nss] section. A value specified in a domain
806 section will override one set in the [nss] section.
807 Default: /home
809 krb5_confd_path (string)
811 Absolute path of a directory where SSSD should place Kerberos
812 configuration snippets.
813 To disable the creation of the configuration snippets set the
815 parameter to 'none'.
816 Default: not set (krb5.include.d subdirectory of SSSD's pubconf
818 directory)
819
821 Certain option defaults do not match their respective backend provider
822 defaults, these option names and AD provider-specific defaults are
823 listed below:
824 KRB5 Provider
826 • krb5_validate = true
827 • krb5_use_enterprise_principal = true
829 LDAP Provider
831 • ldap_schema = ad
832 • ldap_force_upper_case_realm = true
834 • ldap_id_mapping = true
836 • ldap_sasl_mech = GSS-SPNEGO
838 • ldap_referrals = false
840 • ldap_account_expire_policy = ad
842 • ldap_use_tokengroups = true
844 • ldap_sasl_authid = sAMAccountName@REALM (typically
846 SHORTNAME$@REALM)
847 The AD provider looks for a different principal than the LDAP
849 provider by default, because in an Active Directory environment the
850 principals are divided into two groups - User Principals and
851 Service Principals. Only User Principal can be used to obtain a TGT
852 and by default, computer object's principal is constructed from its
853 sAMAccountName and the AD realm. The well-known host/hostname@REALM
854 principal is a Service Principal and thus cannot be used to get a
855 TGT with.
856 NSS configuration
858 • fallback_homedir = /home/%d/%u
859 The AD provider automatically sets "fallback_homedir = /home/%d/%u"
861 to provide personal home directories for users without the
862 homeDirectory attribute. If your AD Domain is properly populated
863 with Posix attributes, and you want to avoid this fallback
864 behavior, you can explicitly set "fallback_homedir = %o".
865 Note that the system typically expects a home directory in /home/%u
867 folder. If you decide to use a different directory structure, some
868 other parts of your system may need adjustments.
869 For example automated creation of home directories in combination
871 with selinux requires selinux adjustment, otherwise the home
872 directory will be created with wrong selinux context.
873
875 The failover feature allows back ends to automatically switch to a
876 different server if the current server fails.
877 Failover Syntax
879 The list of servers is given as a comma-separated list; any number of
880 spaces is allowed around the comma. The servers are listed in order of
881 preference. The list can contain any number of servers.
882 For each failover-enabled config option, two variants exist: primary
884 and backup. The idea is that servers in the primary list are preferred
885 and backup servers are only searched if no primary servers can be
886 reached. If a backup server is selected, a timeout of 31 seconds is
887 set. After this timeout SSSD will periodically try to reconnect to one
888 of the primary servers. If it succeeds, it will replace the current
889 active (backup) server.
890 The Failover Mechanism
892 The failover mechanism distinguishes between a machine and a service.
893 The back end first tries to resolve the hostname of a given machine; if
894 this resolution attempt fails, the machine is considered offline. No
895 further attempts are made to connect to this machine for any other
896 service. If the resolution attempt succeeds, the back end tries to
897 connect to a service on this machine. If the service connection attempt
898 fails, then only this particular service is considered offline and the
899 back end automatically switches over to the next service. The machine
900 is still considered online and might still be tried for another
901 service.
902 Further connection attempts are made to machines or services marked as
904 offline after a specified period of time; this is currently hard coded
905 to 30 seconds.
906 If there are no more machines to try, the back end as a whole switches
908 to offline mode, and then attempts to reconnect every 30 seconds.
909 Failover time outs and tuning
911 Resolving a server to connect to can be as simple as running a single
912 DNS query or can involve several steps, such as finding the correct
913 site or trying out multiple host names in case some of the configured
914 servers are not reachable. The more complex scenarios can take some
915 time and SSSD needs to balance between providing enough time to finish
916 the resolution process but on the other hand, not trying for too long
917 before falling back to offline mode. If the SSSD debug logs show that
918 the server resolution is timing out before a live server is contacted,
919 you can consider changing the time outs.
920 This section lists the available tunables. Please refer to their
922 description in the sssd.conf(5), manual page.
923 dns_resolver_server_timeout
925 Time in milliseconds that sets how long would SSSD talk to a single
926 DNS server before trying next one.
927 Default: 1000
929 dns_resolver_op_timeout
931 Time in seconds to tell how long would SSSD try to resolve single
932 DNS query (e.g. resolution of a hostname or an SRV record) before
933 trying the next hostname or discovery domain.
934 Default: 3
936 dns_resolver_timeout
938 How long would SSSD try to resolve a failover service. This service
939 resolution internally might include several steps, such as
940 resolving DNS SRV queries or locating the site.
941 Default: 6
943 For LDAP-based providers, the resolve operation is performed as part of
945 an LDAP connection operation. Therefore, also the “ldap_opt_timeout”
946 timeout should be set to a larger value than “dns_resolver_timeout”
947 which in turn should be set to a larger value than
948 “dns_resolver_op_timeout” which should be larger than
949 “dns_resolver_server_timeout”.
950
952 The service discovery feature allows back ends to automatically find
953 the appropriate servers to connect to using a special DNS query. This
954 feature is not supported for backup servers.
955 Configuration
957 If no servers are specified, the back end automatically uses service
958 discovery to try to find a server. Optionally, the user may choose to
959 use both fixed server addresses and service discovery by inserting a
960 special keyword, “_srv_”, in the list of servers. The order of
961 preference is maintained. This feature is useful if, for example, the
962 user prefers to use service discovery whenever possible, and fall back
963 to a specific server when no servers can be discovered using DNS.
964 The domain name
966 Please refer to the “dns_discovery_domain” parameter in the
967 sssd.conf(5) manual page for more details.
968 The protocol
970 The queries usually specify _tcp as the protocol. Exceptions are
971 documented in respective option description.
972 See Also
974 For more information on the service discovery mechanism, refer to RFC
975 2782.
976
978 The ID-mapping feature allows SSSD to act as a client of Active
979 Directory without requiring administrators to extend user attributes to
980 support POSIX attributes for user and group identifiers.
981 NOTE: When ID-mapping is enabled, the uidNumber and gidNumber
983 attributes are ignored. This is to avoid the possibility of conflicts
984 between automatically-assigned and manually-assigned values. If you
985 need to use manually-assigned values, ALL values must be
986 manually-assigned.
987 Please note that changing the ID mapping related configuration options
989 will cause user and group IDs to change. At the moment, SSSD does not
990 support changing IDs, so the SSSD database must be removed. Because
991 cached passwords are also stored in the database, removing the database
992 should only be performed while the authentication servers are
993 reachable, otherwise users might get locked out. In order to cache the
994 password, an authentication must be performed. It is not sufficient to
995 use sss_cache(8) to remove the database, rather the process consists
996 of:
997 • Making sure the remote servers are reachable
999 • Stopping the SSSD service
1001 • Removing the database
1003 • Starting the SSSD service
1005 Moreover, as the change of IDs might necessitate the adjustment of
1007 other system properties such as file and directory ownership, it's
1008 advisable to plan ahead and test the ID mapping configuration
1009 thoroughly.
1010 Mapping Algorithm
1012 Active Directory provides an objectSID for every user and group object
1013 in the directory. This objectSID can be broken up into components that
1014 represent the Active Directory domain identity and the relative
1015 identifier (RID) of the user or group object.
1016 The SSSD ID-mapping algorithm takes a range of available UIDs and
1018 divides it into equally-sized component sections - called "slices"-.
1019 Each slice represents the space available to an Active Directory
1020 domain.
1021 When a user or group entry for a particular domain is encountered for
1023 the first time, the SSSD allocates one of the available slices for that
1024 domain. In order to make this slice-assignment repeatable on different
1025 client machines, we select the slice based on the following algorithm:
1026 The SID string is passed through the murmurhash3 algorithm to convert
1028 it to a 32-bit hashed value. We then take the modulus of this value
1029 with the total number of available slices to pick the slice.
1030 NOTE: It is possible to encounter collisions in the hash and subsequent
1032 modulus. In these situations, we will select the next available slice,
1033 but it may not be possible to reproduce the same exact set of slices on
1034 other machines (since the order that they are encountered will
1035 determine their slice). In this situation, it is recommended to either
1036 switch to using explicit POSIX attributes in Active Directory
1037 (disabling ID-mapping) or configure a default domain to guarantee that
1038 at least one is always consistent. See “Configuration” for details.
1039 Configuration
1041 Minimum configuration (in the “[domain/DOMAINNAME]” section):
1042 ldap_id_mapping = True
1044 ldap_schema = ad
1045 The default configuration results in configuring 10,000 slices, each
1047 capable of holding up to 200,000 IDs, starting from 200,000 and going
1048 up to 2,000,200,000. This should be sufficient for most deployments.
1049 Advanced Configuration
1051 ldap_idmap_range_min (integer)
1052 Specifies the lower (inclusive) bound of the range of POSIX IDs
1053 to use for mapping Active Directory user and group SIDs. It is
1054 the first POSIX ID which can be used for the mapping.
1055 NOTE: This option is different from “min_id” in that “min_id”
1057 acts to filter the output of requests to this domain, whereas
1058 this option controls the range of ID assignment. This is a
1059 subtle distinction, but the good general advice would be to
1060 have “min_id” be less-than or equal to “ldap_idmap_range_min”
1061 Default: 200000
1063 ldap_idmap_range_max (integer)
1065 Specifies the upper (exclusive) bound of the range of POSIX IDs
1066 to use for mapping Active Directory user and group SIDs. It is
1067 the first POSIX ID which cannot be used for the mapping
1068 anymore, i.e. one larger than the last one which can be used
1069 for the mapping.
1070 NOTE: This option is different from “max_id” in that “max_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 “max_id” be greater-than or equal to
1076 “ldap_idmap_range_max”
1077 Default: 2000200000
1079 ldap_idmap_range_size (integer)
1081 Specifies the number of IDs available for each slice. If the
1082 range size does not divide evenly into the min and max values,
1083 it will create as many complete slices as it can.
1084 NOTE: The value of this option must be at least as large as the
1086 highest user RID planned for use on the Active Directory
1087 server. User lookups and login will fail for any user whose RID
1088 is greater than this value.
1089 For example, if your most recently-added Active Directory user
1091 has objectSid=S-1-5-21-2153326666-2176343378-3404031434-1107,
1092 “ldap_idmap_range_size” must be at least 1108 as range size is
1093 equal to maximal SID minus minimal SID plus one (e.g. 1108 =
1094 1107 - 0 + 1).
1095 It is important to plan ahead for future expansion, as changing
1097 this value will result in changing all of the ID mappings on
1098 the system, leading to users with different local IDs than they
1099 previously had.
1100 Default: 200000
1102 ldap_idmap_default_domain_sid (string)
1104 Specify the domain SID of the default domain. This will
1105 guarantee that this domain will always be assigned to slice
1106 zero in the ID map, bypassing the murmurhash algorithm
1107 described above.
1108 Default: not set
1110 ldap_idmap_default_domain (string)
1112 Specify the name of the default domain.
1113 Default: not set
1115 ldap_idmap_autorid_compat (boolean)
1117 Changes the behavior of the ID-mapping algorithm to behave more
1118 similarly to winbind's “idmap_autorid” algorithm.
1119 When this option is configured, domains will be allocated
1121 starting with slice zero and increasing monatomically with each
1122 additional domain.
1123 NOTE: This algorithm is non-deterministic (it depends on the
1125 order that users and groups are requested). If this mode is
1126 required for compatibility with machines running winbind, it is
1127 recommended to also use the “ldap_idmap_default_domain_sid”
1128 option to guarantee that at least one domain is consistently
1129 allocated to slice zero.
1130 Default: False
1132 ldap_idmap_helper_table_size (integer)
1134 Maximal number of secondary slices that is tried when
1135 performing mapping from UNIX id to SID.
1136 Note: Additional secondary slices might be generated when SID
1138 is being mapped to UNIX id and RID part of SID is out of range
1139 for secondary slices generated so far. If value of
1140 ldap_idmap_helper_table_size is equal to 0 then no additional
1141 secondary slices are generated.
1142 Default: 10
1144 Well-Known SIDs
1146 SSSD supports to look up the names of Well-Known SIDs, i.e. SIDs with a
1147 special hardcoded meaning. Since the generic users and groups related
1148 to those Well-Known SIDs have no equivalent in a Linux/UNIX environment
1149 no POSIX IDs are available for those objects.
1150 The SID name space is organized in authorities which can be seen as
1152 different domains. The authorities for the Well-Known SIDs are
1153 • Null Authority
1155 • World Authority
1157 • Local Authority
1159 • Creator Authority
1161 • NT Authority
1163 • Built-in
1165 The capitalized version of these names are used as domain names when
1167 returning the fully qualified name of a Well-Known SID.
1168 Since some utilities allow to modify SID based access control
1170 information with the help of a name instead of using the SID directly
1171 SSSD supports to look up the SID by the name as well. To avoid
1172 collisions only the fully qualified names can be used to look up
1173 Well-Known SIDs. As a result the domain names “NULL AUTHORITY”, “WORLD
1174 AUTHORITY”, “ LOCAL AUTHORITY”, “CREATOR AUTHORITY”, “NT AUTHORITY” and
1175 “BUILTIN” should not be used as domain names in sssd.conf.
1176
1178 The following example assumes that SSSD is correctly configured and
1179 example.com is one of the domains in the [sssd] section. This example
1180 shows only the AD provider-specific options.
1181 [domain/EXAMPLE]
1183 id_provider = ad
1184 auth_provider = ad
1185 access_provider = ad
1186 chpass_provider = ad
1187 ad_server = dc1.example.com
1189 ad_hostname = client.example.com
1190 ad_domain = example.com
1191
1194 The AD access control provider checks if the account is expired. It has
1195 the same effect as the following configuration of the LDAP provider:
1196 access_provider = ldap
1198 ldap_access_order = expire
1199 ldap_account_expire_policy = ad
1200 However, unless the “ad” access control provider is explicitly
1202 configured, the default access provider is “permit”. Please note that
1203 if you configure an access provider other than “ad”, you need to set
1204 all the connection parameters (such as LDAP URIs and encryption
1205 details) manually.
1206 When the autofs provider is set to “ad”, the RFC2307 schema attribute
1208 mapping (nisMap, nisObject, ...) is used, because these attributes are
1209 included in the default Active Directory schema.
1210
1212 sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
1213 sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-sudo(5), sssd-session-
1214 recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8),
1215 sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
1216 sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5)
1217 sssd-systemtap(5)
1218
1220 The SSSD upstream - https://github.com/SSSD/sssd/
1221
1223 1. [MS-ADTS] section LDAP extensions
1224 https://msdn.microsoft.com/en-us/library/cc223367.aspx
1225SSSD 07/04/2022 SSSD-AD(5)