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