1SSSD-AD(5) File Formats and Conventions SSSD-AD(5)
2
3
4
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
13 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
19 The AD provider supports connecting to Active Directory 2008 R2 or
20 later. Earlier versions may work, but are unsupported.
21
22 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
27 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
33 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
37 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
41 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
44 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
50 ldap_id_mapping = False
51
52
53 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
64 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
72 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
76 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
80 The short domain name (also known as the NetBIOS or the flat name)
81 is autodetected by the SSSD.
82
83 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
88 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
92 ad_enabled_domains = sales.example.com, eng.example.com
93
94
95 The short domain name (also known as the NetBIOS or the flat name)
96 will be autodetected by SSSD.
97
98 Default: Not set
99
100 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
105 This is optional if autodiscovery is enabled. For more information
106 on service discovery, refer to the “SERVICE DISCOVERY” section.
107
108 Note: Trusted domains will always auto-discover servers even if the
109 primary server is explicitly defined in the ad_server option.
110
111 ad_hostname (string)
112 Optional. May be set on machines where the hostname(5) does not
113 reflect the fully qualified name used in the Active Directory
114 domain to identify this host.
115
116 This field is used to determine the host principal in use in the
117 keytab. It must match the hostname for which the keytab was issued.
118
119 ad_enable_dns_sites (boolean)
120 Enables DNS sites - location based service discovery.
121
122 If true and service discovery (see Service Discovery paragraph at
123 the bottom of the man page) is enabled, the SSSD will first attempt
124 to discover the Active Directory server to connect to using the
125 Active Directory Site Discovery and fall back to the DNS SRV
126 records if no AD site is found. The DNS SRV configuration,
127 including the discovery domain, is used during site discovery as
128 well.
129
130 Default: true
131
132 ad_access_filter (string)
133 This option specifies LDAP access control filter that the user must
134 match in order to be allowed access. Please note that the
135 “access_provider” option must be explicitly set to “ad” in order
136 for this option to have an effect.
137
138 The option also supports specifying different filters per domain or
139 forest. This extended filter would consist of:
140 “KEYWORD:NAME:FILTER”. The keyword can be either “DOM”, “FOREST” or
141 missing.
142
143 If the keyword equals to “DOM” or is missing, then “NAME” specifies
144 the domain or subdomain the filter applies to. If the keyword
145 equals to “FOREST”, then the filter equals to all domains from the
146 forest specified by “NAME”.
147
148 Multiple filters can be separated with the “?” character,
149 similarly to how search bases work.
150
151 Nested group membership must be searched for using a special OID
152 “:1.2.840.113556.1.4.1941:” in addition to the full
153 DOM:domain.example.org: syntax to ensure the parser does not
154 attempt to interpret the colon characters associated with the OID.
155 If you do not use this OID then nested group membership will not be
156 resolved. See usage example below and refer here for further
157 information about the OID: [MS-ADTS] section LDAP extensions[1]
158
159 The most specific match is always used. For example, if the option
160 specified filter for a domain the user is a member of and a global
161 filter, the per-domain filter would be applied. If there are more
162 matches with the same specification, the first one is used.
163
164 Examples:
165
166 # apply filter on domain called dom1 only:
167 dom1:(memberOf=cn=admins,ou=groups,dc=dom1,dc=com)
168
169 # apply filter on domain called dom2 only:
170 DOM:dom2:(memberOf=cn=admins,ou=groups,dc=dom2,dc=com)
171
172 # apply filter on forest called EXAMPLE.COM only:
173 FOREST:EXAMPLE.COM:(memberOf=cn=admins,ou=groups,dc=example,dc=com)
174
175 # apply filter for a member of a nested group in dom1:
176 DOM:dom1:(memberOf:1.2.840.113556.1.4.1941:=cn=nestedgroup,ou=groups,dc=example,dc=com)
177
178
179 Default: Not set
180
181 ad_site (string)
182 Specify AD site to which client should try to connect. If this
183 option is not provided, the AD site will be auto-discovered.
184
185 Default: Not set
186
187 ad_enable_gc (boolean)
188 By default, the SSSD connects to the Global Catalog first to
189 retrieve users from trusted domains and uses the LDAP port to
190 retrieve group memberships or as a fallback. Disabling this option
191 makes the SSSD only connect to the LDAP port of the current AD
192 server.
193
194 Please note that disabling Global Catalog support does not disable
195 retrieving users from trusted domains. The SSSD would connect to
196 the LDAP port of trusted domains instead. However, Global Catalog
197 must be used in order to resolve cross-domain group memberships.
198
199 Default: true
200
201 ad_gpo_access_control (string)
202 This option specifies the operation mode for GPO-based access
203 control functionality: whether it operates in disabled mode,
204 enforcing mode, or permissive mode. Please note that the
205 “access_provider” option must be explicitly set to “ad” in order
206 for this option to have an effect.
207
208 GPO-based access control functionality uses GPO policy settings to
209 determine whether or not a particular user is allowed to logon to
210 the host. For more information on the supported policy settings
211 please refer to the “ad_gpo_map” options.
212
213 Please note that current version of SSSD does not support Active
214 Directory's built-in groups. Built-in groups (such as
215 Administrators with SID S-1-5-32-544) in GPO access control rules
216 will be ignored by SSSD. See upstream issue tracker
217 https://pagure.io/SSSD/sssd/issue/4099 .
218
219 Before performing access control SSSD applies group policy security
220 filtering on the GPOs. For every single user login, the
221 applicability of the GPOs that are linked to the host is checked.
222 In order for a GPO to apply to a user, the user or at least one of
223 the groups to which it belongs must have following permissions on
224 the GPO:
225
226 · Read: The user or one of its groups must have read access to
227 the properties of the GPO (RIGHT_DS_READ_PROPERTY)
228
229 · Apply Group Policy: The user or at least one of its groups must
230 be allowed to apply the GPO (RIGHT_DS_CONTROL_ACCESS).
231
232 By default, the Authenticated Users group is present on a GPO and
233 this group has both Read and Apply Group Policy access rights.
234 Since authentication of a user must have been completed
235 successfully before GPO security filtering and access control are
236 started, the Authenticated Users group permissions on the GPO
237 always apply also to the user.
238
239 NOTE: The current version of SSSD does not support host (computer)
240 entries in the GPO 'Security Filtering' list. Only user and group
241 entries are supported. Host entries in the list have no effect.
242
243 NOTE: If the operation mode is set to enforcing, it is possible
244 that users that were previously allowed logon access will now be
245 denied logon access (as dictated by the GPO policy settings). In
246 order to facilitate a smooth transition for administrators, a
247 permissive mode is available that will not enforce the access
248 control rules, but will evaluate them and will output a syslog
249 message if access would have been denied. By examining the logs,
250 administrators can then make the necessary changes before setting
251 the mode to enforcing. For logging GPO-based access control debug
252 level 'trace functions' is required (see sssctl(8) manual page).
253
254 There are three supported values for this option:
255
256 · disabled: GPO-based access control rules are neither evaluated
257 nor enforced.
258
259 · enforcing: GPO-based access control rules are evaluated and
260 enforced.
261
262 · permissive: GPO-based access control rules are evaluated, but
263 not enforced. Instead, a syslog message will be emitted
264 indicating that the user would have been denied access if this
265 option's value were set to enforcing.
266
267 Default: enforcing
268
269 ad_gpo_implicit_deny (boolean)
270 Normally when no applicable GPOs are found the users are allowed
271 access. When this option is set to True users will be allowed
272 access only when explicitly allowed by a GPO rule. Otherwise users
273 will be denied access. This can be used to harden security but be
274 careful when using this option because it can deny access even to
275 users in the built-in Administrators group if no GPO rules apply to
276 them.
277
278 Default: False
279
280 ad_gpo_ignore_unreadable (boolean)
281 Normally when some group policy containers (AD object) of
282 applicable group policy objects are not readable by SSSD then users
283 are denied access. This option allows to ignore group policy
284 containers and with them associated policies if their attributes in
285 group policy containers are not readable for SSSD.
286
287 Default: False
288
289 ad_gpo_cache_timeout (integer)
290 The amount of time between lookups of GPO policy files against the
291 AD server. This will reduce the latency and load on the AD server
292 if there are many access-control requests made in a short period.
293
294 Default: 5 (seconds)
295
296 ad_gpo_map_interactive (string)
297 A comma-separated list of PAM service names for which GPO-based
298 access control is evaluated based on the InteractiveLogonRight and
299 DenyInteractiveLogonRight policy settings. Only those GPOs are
300 evaluated for which the user has Read and Apply Group Policy
301 permission (see option “ad_gpo_access_control”). If an evaluated
302 GPO contains the deny interactive logon setting for the user or one
303 of its groups, the user is denied local access. If none of the
304 evaluated GPOs has an interactive logon right defined, the user is
305 granted local access. If at least one evaluated GPO contains
306 interactive logon right settings, the user is granted local access
307 only, if it or at least one of its groups is part of the policy
308 settings.
309
310 Note: Using the Group Policy Management Editor this value is called
311 "Allow log on locally" and "Deny log on locally".
312
313 It is possible to add another PAM service name to the default set
314 by using “+service_name” or to explicitly remove a PAM service name
315 from the default set by using “-service_name”. For example, in
316 order to replace a default PAM service name for this logon right
317 (e.g. “login”) with a custom pam service name (e.g.
318 “my_pam_service”), you would use the following configuration:
319
320 ad_gpo_map_interactive = +my_pam_service, -login
321
322
323 Default: the default set of PAM service names includes:
324
325 · login
326
327 · su
328
329 · su-l
330
331 · gdm-fingerprint
332
333 · gdm-password
334
335 · gdm-smartcard
336
337 · kdm
338
339 · lightdm
340
341 · lxdm
342
343 · sddm
344
345 · unity
346
347 · xdm
348
349
350 ad_gpo_map_remote_interactive (string)
351 A comma-separated list of PAM service names for which GPO-based
352 access control is evaluated based on the
353 RemoteInteractiveLogonRight and DenyRemoteInteractiveLogonRight
354 policy settings. Only those GPOs are evaluated for which the user
355 has Read and Apply Group Policy permission (see option
356 “ad_gpo_access_control”). If an evaluated GPO contains the deny
357 remote logon setting for the user or one of its groups, the user is
358 denied remote interactive access. If none of the evaluated GPOs has
359 a remote interactive logon right defined, the user is granted
360 remote access. If at least one evaluated GPO contains remote
361 interactive logon right settings, the user is granted remote access
362 only, if it or at least one of its groups is part of the policy
363 settings.
364
365 Note: Using the Group Policy Management Editor this value is called
366 "Allow log on through Remote Desktop Services" and "Deny log on
367 through Remote Desktop Services".
368
369 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. “sshd”) with a custom pam service name (e.g.
374 “my_pam_service”), you would use the following configuration:
375
376 ad_gpo_map_remote_interactive = +my_pam_service, -sshd
377
378
379 Default: the default set of PAM service names includes:
380
381 · sshd
382
383 · cockpit
384
385
386 ad_gpo_map_network (string)
387 A comma-separated list of PAM service names for which GPO-based
388 access control is evaluated based on the NetworkLogonRight and
389 DenyNetworkLogonRight policy settings. Only those GPOs are
390 evaluated for which the user has Read and Apply Group Policy
391 permission (see option “ad_gpo_access_control”). If an evaluated
392 GPO contains the deny network logon setting for the user or one of
393 its groups, the user is denied network logon access. If none of the
394 evaluated GPOs has a network logon right defined, the user is
395 granted logon access. If at least one evaluated GPO contains
396 network logon right settings, the user is granted logon access
397 only, if it or at least one of its groups is part of the policy
398 settings.
399
400 Note: Using the Group Policy Management Editor this value is called
401 "Access this computer from the network" and "Deny access to this
402 computer from the network".
403
404 It is possible to add another PAM service name to the default set
405 by using “+service_name” or to explicitly remove a PAM service name
406 from the default set by using “-service_name”. For example, in
407 order to replace a default PAM service name for this logon right
408 (e.g. “ftp”) with a custom pam service name (e.g.
409 “my_pam_service”), you would use the following configuration:
410
411 ad_gpo_map_network = +my_pam_service, -ftp
412
413
414 Default: the default set of PAM service names includes:
415
416 · ftp
417
418 · samba
419
420
421 ad_gpo_map_batch (string)
422 A comma-separated list of PAM service names for which GPO-based
423 access control is evaluated based on the BatchLogonRight and
424 DenyBatchLogonRight policy settings. Only those GPOs are evaluated
425 for which the user has Read and Apply Group Policy permission (see
426 option “ad_gpo_access_control”). If an evaluated GPO contains the
427 deny batch logon setting for the user or one of its groups, the
428 user is denied batch logon access. If none of the evaluated GPOs
429 has a batch logon right defined, the user is granted logon access.
430 If at least one evaluated GPO contains batch logon right settings,
431 the user is granted logon access only, if it or at least one of its
432 groups is part of the policy settings.
433
434 Note: Using the Group Policy Management Editor this value is called
435 "Allow log on as a batch job" and "Deny log on as a batch job".
436
437 It is possible to add another PAM service name to the default set
438 by using “+service_name” or to explicitly remove a PAM service name
439 from the default set by using “-service_name”. For example, in
440 order to replace a default PAM service name for this logon right
441 (e.g. “crond”) with a custom pam service name (e.g.
442 “my_pam_service”), you would use the following configuration:
443
444 ad_gpo_map_batch = +my_pam_service, -crond
445
446
447 Note: Cron service name may differ depending on Linux distribution
448 used.
449
450 Default: the default set of PAM service names includes:
451
452 · crond
453
454
455 ad_gpo_map_service (string)
456 A comma-separated list of PAM service names for which GPO-based
457 access control is evaluated based on the ServiceLogonRight and
458 DenyServiceLogonRight policy settings. Only those GPOs are
459 evaluated for which the user has Read and Apply Group Policy
460 permission (see option “ad_gpo_access_control”). If an evaluated
461 GPO contains the deny service logon setting for the user or one of
462 its groups, the user is denied service logon access. If none of the
463 evaluated GPOs has a service logon right defined, the user is
464 granted logon access. If at least one evaluated GPO contains
465 service logon right settings, the user is granted logon access
466 only, if it or at least one of its groups is part of the policy
467 settings.
468
469 Note: Using the Group Policy Management Editor this value is called
470 "Allow log on as a service" and "Deny log on as a service".
471
472 It is possible to add a PAM service name to the default set by
473 using “+service_name”. Since the default set is empty, it is not
474 possible to remove a PAM service name from the default set. For
475 example, in order to add a custom pam service name (e.g.
476 “my_pam_service”), you would use the following configuration:
477
478 ad_gpo_map_service = +my_pam_service
479
480
481 Default: not set
482
483 ad_gpo_map_permit (string)
484 A comma-separated list of PAM service names for which GPO-based
485 access is always granted, regardless of any GPO Logon Rights.
486
487 It is possible to add another PAM service name to the default set
488 by using “+service_name” or to explicitly remove a PAM service name
489 from the default set by using “-service_name”. For example, in
490 order to replace a default PAM service name for unconditionally
491 permitted access (e.g. “sudo”) with a custom pam service name
492 (e.g. “my_pam_service”), you would use the following
493 configuration:
494
495 ad_gpo_map_permit = +my_pam_service, -sudo
496
497
498 Default: the default set of PAM service names includes:
499
500 · polkit-1
501
502 · sudo
503
504 · sudo-i
505
506 · systemd-user
507
508
509 ad_gpo_map_deny (string)
510 A comma-separated list of PAM service names for which GPO-based
511 access is always denied, regardless of any GPO Logon Rights.
512
513 It is possible to add a PAM service name to the default set by
514 using “+service_name”. Since the default set is empty, it is not
515 possible to remove a PAM service name from the default set. For
516 example, in order to add a custom pam service name (e.g.
517 “my_pam_service”), you would use the following configuration:
518
519 ad_gpo_map_deny = +my_pam_service
520
521
522 Default: not set
523
524 ad_gpo_default_right (string)
525 This option defines how access control is evaluated for PAM service
526 names that are not explicitly listed in one of the ad_gpo_map_*
527 options. This option can be set in two different manners. First,
528 this option can be set to use a default logon right. For example,
529 if this option is set to 'interactive', it means that unmapped PAM
530 service names will be processed based on the InteractiveLogonRight
531 and DenyInteractiveLogonRight policy settings. Alternatively, this
532 option can be set to either always permit or always deny access for
533 unmapped PAM service names.
534
535 Supported values for this option include:
536
537 · interactive
538
539 · remote_interactive
540
541 · network
542
543 · batch
544
545 · service
546
547 · permit
548
549 · deny
550
551 Default: deny
552
553 ad_maximum_machine_account_password_age (integer)
554 SSSD will check once a day if the machine account password is older
555 than the given age in days and try to renew it. A value of 0 will
556 disable the renewal attempt.
557
558 Default: 30 days
559
560 ad_machine_account_password_renewal_opts (string)
561 This option should only be used to test the machine account renewal
562 task. The option expects 2 integers separated by a colon (':'). The
563 first integer defines the interval in seconds how often the task is
564 run. The second specifies the initial timeout in seconds before the
565 task is run for the first time after startup.
566
567 Default: 86400:750 (24h and 15m)
568
569 ad_use_ldaps (bool)
570 By default SSSD uses the plain LDAP port 389 and the Global Catalog
571 port 3628. If this option is set to True SSSD will use the LDAPS
572 port 636 and Global Catalog port 3629 with LDAPS protection. Since
573 AD does not allow to have multiple encryption layers on a single
574 connection and we still want to use SASL/GSSAPI or SASL/GSS-SPNEGO
575 for authentication the SASL security property maxssf is set to 0
576 (zero) for those connections.
577
578 Default: False
579
580 dyndns_update (boolean)
581 Optional. This option tells SSSD to automatically update the Active
582 Directory DNS server with the IP address of this client. The update
583 is secured using GSS-TSIG. As a consequence, the Active Directory
584 administrator only needs to allow secure updates for the DNS zone.
585 The IP address of the AD LDAP connection is used for the updates,
586 if it is not otherwise specified by using the “dyndns_iface”
587 option.
588
589 NOTE: On older systems (such as RHEL 5), for this behavior to work
590 reliably, the default Kerberos realm must be set properly in
591 /etc/krb5.conf
592
593 Default: true
594
595 dyndns_ttl (integer)
596 The TTL to apply to the client DNS record when updating it. If
597 dyndns_update is false this has no effect. This will override the
598 TTL serverside if set by an administrator.
599
600 Default: 3600 (seconds)
601
602 dyndns_iface (string)
603 Optional. Applicable only when dyndns_update is true. Choose the
604 interface or a list of interfaces whose IP addresses should be used
605 for dynamic DNS updates. Special value “*” implies that IPs from
606 all interfaces should be used.
607
608 Default: Use the IP addresses of the interface which is used for AD
609 LDAP connection
610
611 Example: dyndns_iface = em1, vnet1, vnet2
612
613 dyndns_refresh_interval (integer)
614 How often should the back end perform periodic DNS update in
615 addition to the automatic update performed when the back end goes
616 online. This option is optional and applicable only when
617 dyndns_update is true. Note that the lowest possible value is 60
618 seconds in-case if value is provided less than 60, parameter will
619 assume lowest value only.
620
621 Default: 86400 (24 hours)
622
623 dyndns_update_ptr (bool)
624 Whether the PTR record should also be explicitly updated when
625 updating the client's DNS records. Applicable only when
626 dyndns_update is true.
627
628 Default: True
629
630 dyndns_force_tcp (bool)
631 Whether the nsupdate utility should default to using TCP for
632 communicating with the DNS server.
633
634 Default: False (let nsupdate choose the protocol)
635
636 dyndns_auth (string)
637 Whether the nsupdate utility should use GSS-TSIG authentication for
638 secure updates with the DNS server, insecure updates can be sent by
639 setting this option to 'none'.
640
641 Default: GSS-TSIG
642
643 dyndns_server (string)
644 The DNS server to use when performing a DNS update. In most setups,
645 it's recommended to leave this option unset.
646
647 Setting this option makes sense for environments where the DNS
648 server is different from the identity server.
649
650 Please note that this option will be only used in fallback attempt
651 when previous attempt using autodetected settings failed.
652
653 Default: None (let nsupdate choose the server)
654
655 dyndns_update_per_family (boolean)
656 DNS update is by default performed in two steps - IPv4 update and
657 then IPv6 update. In some cases it might be desirable to perform
658 IPv4 and IPv6 update in single step.
659
660 Default: true
661
662 override_homedir (string)
663 Override the user's home directory. You can either provide an
664 absolute value or a template. In the template, the following
665 sequences are substituted:
666
667 %u
668 login name
669
670 %U
671 UID number
672
673 %d
674 domain name
675
676 %f
677 fully qualified user name (user@domain)
678
679 %l
680 The first letter of the login name.
681
682 %P
683 UPN - User Principal Name (name@REALM)
684
685 %o
686 The original home directory retrieved from the identity
687 provider.
688
689 %H
690 The value of configure option homedir_substring.
691
692 %%
693 a literal '%'
694
695 This option can also be set per-domain.
696
697 example:
698
699 override_homedir = /home/%u
700
701
702 Default: Not set (SSSD will use the value retrieved from LDAP)
703
704 homedir_substring (string)
705 The value of this option will be used in the expansion of the
706 override_homedir option if the template contains the format string
707 %H. An LDAP directory entry can directly contain this template so
708 that this option can be used to expand the home directory path for
709 each client machine (or operating system). It can be set per-domain
710 or globally in the [nss] section. A value specified in a domain
711 section will override one set in the [nss] section.
712
713 Default: /home
714
715 krb5_confd_path (string)
716 Absolute path of a directory where SSSD should place Kerberos
717 configuration snippets.
718
719 To disable the creation of the configuration snippets set the
720 parameter to 'none'.
721
722 Default: not set (krb5.include.d subdirectory of SSSD's pubconf
723 directory)
724
726 Certain option defaults do not match their respective backend provider
727 defaults, these option names and AD provider-specific defaults are
728 listed below:
729
730 KRB5 Provider
731 · krb5_validate = true
732
733 · krb5_use_enterprise_principal = true
734
735 LDAP Provider
736 · ldap_schema = ad
737
738 · ldap_force_upper_case_realm = true
739
740 · ldap_id_mapping = true
741
742 · ldap_sasl_mech = gssapi
743
744 · ldap_referrals = false
745
746 · ldap_account_expire_policy = ad
747
748 · ldap_use_tokengroups = true
749
750 · ldap_sasl_authid = sAMAccountName@REALM (typically
751 SHORTNAME$@REALM)
752
753 The AD provider looks for a different principal than the LDAP
754 provider by default, because in an Active Directory environment the
755 principals are divided into two groups - User Principals and
756 Service Principals. Only User Principal can be used to obtain a TGT
757 and by default, computer object's principal is constructed from its
758 sAMAccountName and the AD realm. The well-known host/hostname@REALM
759 principal is a Service Principal and thus cannot be used to get a
760 TGT with.
761
762 NSS configuration
763 · fallback_homedir = /home/%d/%u
764
765 The AD provider automatically sets "fallback_homedir = /home/%d/%u"
766 to provide personal home directories for users without the
767 homeDirectory attribute. If your AD Domain is properly populated
768 with Posix attributes, and you want to avoid this fallback
769 behavior, you can explicitly set "fallback_homedir = %o".
770
772 The failover feature allows back ends to automatically switch to a
773 different server if the current server fails.
774
775 Failover Syntax
776 The list of servers is given as a comma-separated list; any number of
777 spaces is allowed around the comma. The servers are listed in order of
778 preference. The list can contain any number of servers.
779
780 For each failover-enabled config option, two variants exist: primary
781 and backup. The idea is that servers in the primary list are preferred
782 and backup servers are only searched if no primary servers can be
783 reached. If a backup server is selected, a timeout of 31 seconds is
784 set. After this timeout SSSD will periodically try to reconnect to one
785 of the primary servers. If it succeeds, it will replace the current
786 active (backup) server.
787
788 The Failover Mechanism
789 The failover mechanism distinguishes between a machine and a service.
790 The back end first tries to resolve the hostname of a given machine; if
791 this resolution attempt fails, the machine is considered offline. No
792 further attempts are made to connect to this machine for any other
793 service. If the resolution attempt succeeds, the back end tries to
794 connect to a service on this machine. If the service connection attempt
795 fails, then only this particular service is considered offline and the
796 back end automatically switches over to the next service. The machine
797 is still considered online and might still be tried for another
798 service.
799
800 Further connection attempts are made to machines or services marked as
801 offline after a specified period of time; this is currently hard coded
802 to 30 seconds.
803
804 If there are no more machines to try, the back end as a whole switches
805 to offline mode, and then attempts to reconnect every 30 seconds.
806
807 Failover time outs and tuning
808 Resolving a server to connect to can be as simple as running a single
809 DNS query or can involve several steps, such as finding the correct
810 site or trying out multiple host names in case some of the configured
811 servers are not reachable. The more complex scenarios can take some
812 time and SSSD needs to balance between providing enough time to finish
813 the resolution process but on the other hand, not trying for too long
814 before falling back to offline mode. If the SSSD debug logs show that
815 the server resolution is timing out before a live server is contacted,
816 you can consider changing the time outs.
817
818 This section lists the available tunables. Please refer to their
819 description in the sssd.conf(5), manual page.
820
821 dns_resolver_server_timeout
822 Time in milliseconds that sets how long would SSSD talk to a single
823 DNS server before trying next one.
824
825 Default: 1000
826
827 dns_resolver_op_timeout
828 Time in seconds to tell how long would SSSD try to resolve single
829 DNS query (e.g. resolution of a hostname or an SRV record) before
830 trying the next hostname or discovery domain.
831
832 Default: 2
833
834 dns_resolver_timeout
835 How long would SSSD try to resolve a failover service. This service
836 resolution internally might include several steps, such as
837 resolving DNS SRV queries or locating the site.
838
839 Default: 4
840
841 For LDAP-based providers, the resolve operation is performed as part of
842 an LDAP connection operation. Therefore, also the “ldap_opt_timeout>”
843 timeout should be set to a larger value than “dns_resolver_timeout”
844 which in turn should be set to a larger value than
845 “dns_resolver_op_timeout” which should be larger than
846 “dns_resolver_server_timeout”.
847
849 The service discovery feature allows back ends to automatically find
850 the appropriate servers to connect to using a special DNS query. This
851 feature is not supported for backup servers.
852
853 Configuration
854 If no servers are specified, the back end automatically uses service
855 discovery to try to find a server. Optionally, the user may choose to
856 use both fixed server addresses and service discovery by inserting a
857 special keyword, “_srv_”, in the list of servers. The order of
858 preference is maintained. This feature is useful if, for example, the
859 user prefers to use service discovery whenever possible, and fall back
860 to a specific server when no servers can be discovered using DNS.
861
862 The domain name
863 Please refer to the “dns_discovery_domain” parameter in the
864 sssd.conf(5) manual page for more details.
865
866 The protocol
867 The queries usually specify _tcp as the protocol. Exceptions are
868 documented in respective option description.
869
870 See Also
871 For more information on the service discovery mechanism, refer to RFC
872 2782.
873
875 The ID-mapping feature allows SSSD to act as a client of Active
876 Directory without requiring administrators to extend user attributes to
877 support POSIX attributes for user and group identifiers.
878
879 NOTE: When ID-mapping is enabled, the uidNumber and gidNumber
880 attributes are ignored. This is to avoid the possibility of conflicts
881 between automatically-assigned and manually-assigned values. If you
882 need to use manually-assigned values, ALL values must be
883 manually-assigned.
884
885 Please note that changing the ID mapping related configuration options
886 will cause user and group IDs to change. At the moment, SSSD does not
887 support changing IDs, so the SSSD database must be removed. Because
888 cached passwords are also stored in the database, removing the database
889 should only be performed while the authentication servers are
890 reachable, otherwise users might get locked out. In order to cache the
891 password, an authentication must be performed. It is not sufficient to
892 use sss_cache(8) to remove the database, rather the process consists
893 of:
894
895 · Making sure the remote servers are reachable
896
897 · Stopping the SSSD service
898
899 · Removing the database
900
901 · Starting the SSSD service
902
903 Moreover, as the change of IDs might necessitate the adjustment of
904 other system properties such as file and directory ownership, it's
905 advisable to plan ahead and test the ID mapping configuration
906 thoroughly.
907
908 Mapping Algorithm
909 Active Directory provides an objectSID for every user and group object
910 in the directory. This objectSID can be broken up into components that
911 represent the Active Directory domain identity and the relative
912 identifier (RID) of the user or group object.
913
914 The SSSD ID-mapping algorithm takes a range of available UIDs and
915 divides it into equally-sized component sections - called "slices"-.
916 Each slice represents the space available to an Active Directory
917 domain.
918
919 When a user or group entry for a particular domain is encountered for
920 the first time, the SSSD allocates one of the available slices for that
921 domain. In order to make this slice-assignment repeatable on different
922 client machines, we select the slice based on the following algorithm:
923
924 The SID string is passed through the murmurhash3 algorithm to convert
925 it to a 32-bit hashed value. We then take the modulus of this value
926 with the total number of available slices to pick the slice.
927
928 NOTE: It is possible to encounter collisions in the hash and subsequent
929 modulus. In these situations, we will select the next available slice,
930 but it may not be possible to reproduce the same exact set of slices on
931 other machines (since the order that they are encountered will
932 determine their slice). In this situation, it is recommended to either
933 switch to using explicit POSIX attributes in Active Directory
934 (disabling ID-mapping) or configure a default domain to guarantee that
935 at least one is always consistent. See “Configuration” for details.
936
937 Configuration
938 Minimum configuration (in the “[domain/DOMAINNAME]” section):
939
940 ldap_id_mapping = True
941 ldap_schema = ad
942
943 The default configuration results in configuring 10,000 slices, each
944 capable of holding up to 200,000 IDs, starting from 200,000 and going
945 up to 2,000,200,000. This should be sufficient for most deployments.
946
947 Advanced Configuration
948 ldap_idmap_range_min (integer)
949 Specifies the lower bound of the range of POSIX IDs to use for
950 mapping Active Directory user and group SIDs.
951
952 NOTE: This option is different from “min_id” in that “min_id”
953 acts to filter the output of requests to this domain, whereas
954 this option controls the range of ID assignment. This is a
955 subtle distinction, but the good general advice would be to
956 have “min_id” be less-than or equal to “ldap_idmap_range_min”
957
958 Default: 200000
959
960 ldap_idmap_range_max (integer)
961 Specifies the upper bound of the range of POSIX IDs to use for
962 mapping Active Directory user and group SIDs.
963
964 NOTE: This option is different from “max_id” in that “max_id”
965 acts to filter the output of requests to this domain, whereas
966 this option controls the range of ID assignment. This is a
967 subtle distinction, but the good general advice would be to
968 have “max_id” be greater-than or equal to
969 “ldap_idmap_range_max”
970
971 Default: 2000200000
972
973 ldap_idmap_range_size (integer)
974 Specifies the number of IDs available for each slice. If the
975 range size does not divide evenly into the min and max values,
976 it will create as many complete slices as it can.
977
978 NOTE: The value of this option must be at least as large as the
979 highest user RID planned for use on the Active Directory
980 server. User lookups and login will fail for any user whose RID
981 is greater than this value.
982
983 For example, if your most recently-added Active Directory user
984 has objectSid=S-1-5-21-2153326666-2176343378-3404031434-1107,
985 “ldap_idmap_range_size” must be at least 1108 as range size is
986 equal to maximal SID minus minimal SID plus one (e.g. 1108 =
987 1107 - 0 + 1).
988
989 It is important to plan ahead for future expansion, as changing
990 this value will result in changing all of the ID mappings on
991 the system, leading to users with different local IDs than they
992 previously had.
993
994 Default: 200000
995
996 ldap_idmap_default_domain_sid (string)
997 Specify the domain SID of the default domain. This will
998 guarantee that this domain will always be assigned to slice
999 zero in the ID map, bypassing the murmurhash algorithm
1000 described above.
1001
1002 Default: not set
1003
1004 ldap_idmap_default_domain (string)
1005 Specify the name of the default domain.
1006
1007 Default: not set
1008
1009 ldap_idmap_autorid_compat (boolean)
1010 Changes the behavior of the ID-mapping algorithm to behave more
1011 similarly to winbind's “idmap_autorid” algorithm.
1012
1013 When this option is configured, domains will be allocated
1014 starting with slice zero and increasing monatomically with each
1015 additional domain.
1016
1017 NOTE: This algorithm is non-deterministic (it depends on the
1018 order that users and groups are requested). If this mode is
1019 required for compatibility with machines running winbind, it is
1020 recommended to also use the “ldap_idmap_default_domain_sid”
1021 option to guarantee that at least one domain is consistently
1022 allocated to slice zero.
1023
1024 Default: False
1025
1026 ldap_idmap_helper_table_size (integer)
1027 Maximal number of secondary slices that is tried when
1028 performing mapping from UNIX id to SID.
1029
1030 Note: Additional secondary slices might be generated when SID
1031 is being mapped to UNIX id and RID part of SID is out of range
1032 for secondary slices generated so far. If value of
1033 ldap_idmap_helper_table_size is equal to 0 then no additional
1034 secondary slices are generated.
1035
1036 Default: 10
1037
1038 Well-Known SIDs
1039 SSSD supports to look up the names of Well-Known SIDs, i.e. SIDs with a
1040 special hardcoded meaning. Since the generic users and groups related
1041 to those Well-Known SIDs have no equivalent in a Linux/UNIX environment
1042 no POSIX IDs are available for those objects.
1043
1044 The SID name space is organized in authorities which can be seen as
1045 different domains. The authorities for the Well-Known SIDs are
1046
1047 · Null Authority
1048
1049 · World Authority
1050
1051 · Local Authority
1052
1053 · Creator Authority
1054
1055 · NT Authority
1056
1057 · Built-in
1058
1059 The capitalized version of these names are used as domain names when
1060 returning the fully qualified name of a Well-Known SID.
1061
1062 Since some utilities allow to modify SID based access control
1063 information with the help of a name instead of using the SID directly
1064 SSSD supports to look up the SID by the name as well. To avoid
1065 collisions only the fully qualified names can be used to look up
1066 Well-Known SIDs. As a result the domain names “NULL AUTHORITY”, “WORLD
1067 AUTHORITY”, “ LOCAL AUTHORITY”, “CREATOR AUTHORITY”, “NT AUTHORITY” and
1068 “BUILTIN” should not be used as domain names in sssd.conf.
1069
1071 The following example assumes that SSSD is correctly configured and
1072 example.com is one of the domains in the [sssd] section. This example
1073 shows only the AD provider-specific options.
1074
1075 [domain/EXAMPLE]
1076 id_provider = ad
1077 auth_provider = ad
1078 access_provider = ad
1079 chpass_provider = ad
1080
1081 ad_server = dc1.example.com
1082 ad_hostname = client.example.com
1083 ad_domain = example.com
1084
1085
1087 The AD access control provider checks if the account is expired. It has
1088 the same effect as the following configuration of the LDAP provider:
1089
1090 access_provider = ldap
1091 ldap_access_order = expire
1092 ldap_account_expire_policy = ad
1093
1094 However, unless the “ad” access control provider is explicitly
1095 configured, the default access provider is “permit”. Please note that
1096 if you configure an access provider other than “ad”, you need to set
1097 all the connection parameters (such as LDAP URIs and encryption
1098 details) manually.
1099
1100 When the autofs provider is set to “ad”, the RFC2307 schema attribute
1101 mapping (nisMap, nisObject, ...) is used, because these attributes are
1102 included in the default Active Directory schema.
1103
1105 sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
1106 sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-sudo(5), sssd-session-
1107 recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8),
1108 sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
1109 sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5)
1110 sssd-systemtap(5)
1111
1113 The SSSD upstream - https://pagure.io/SSSD/sssd/
1114
1116 1. [MS-ADTS] section LDAP extensions
1117 https://msdn.microsoft.com/en-us/library/cc223367.aspx
1118
1119
1120
1121SSSD 02/26/2020 SSSD-AD(5)