1SSSD-AD(5) File Formats and Conventions SSSD-AD(5)
2
6 sssd-ad - SSSD Active Directory provider
7
9 This manual page describes the configuration of the AD provider for
10 sssd(8). For a detailed syntax reference, refer to the “FILE FORMAT”
11 section of the sssd.conf(5) manual page.
12 The AD provider is a back end used to connect to an Active Directory
14 server. This provider requires that the machine be joined to the AD
15 domain and a keytab is available. Back end communication occurs over a
16 GSSAPI-encrypted channel, SSL/TLS options should not be used with the
17 AD provider and will be superseded by Kerberos usage.
18 The AD provider supports connecting to Active Directory 2008 R2 or
20 later. Earlier versions may work, but are unsupported.
21 The AD provider can be used to get user information and authenticate
23 users from trusted domains. Currently only trusted domains in the same
24 forest are recognized. In addition servers from trusted domains are
25 always auto-discovered.
26 The AD provider enables SSSD to use the sssd-ldap(5) identity provider
28 and the sssd-krb5(5) authentication provider with optimizations for
29 Active Directory environments. The AD provider accepts the same options
30 used by the sssd-ldap and sssd-krb5 providers with some exceptions.
31 However, it is neither necessary nor recommended to set these options.
32 The AD provider primarily copies the traditional ldap and krb5 provider
34 default options with some exceptions, the differences are listed in the
35 “MODIFIED DEFAULT OPTIONS” section.
36 The AD provider can also be used as an access, chpass, sudo and autofs
38 provider. No configuration of the access provider is required on the
39 client side.
40 If “auth_provider=ad” or “access_provider=ad” is configured in
42 sssd.conf then the id_provider must also be set to “ad”.
43 By default, the AD provider will map UID and GID values from the
45 objectSID parameter in Active Directory. For details on this, see the
46 “ID MAPPING” section below. If you want to disable ID mapping and
47 instead rely on POSIX attributes defined in Active Directory, you
48 should set
49 ldap_id_mapping = False
51 If POSIX attributes should be used, it is recommended for performance
54 reasons that the attributes are also replicated to the Global Catalog.
55 If POSIX attributes are replicated, SSSD will attempt to locate the
56 domain of a requested numerical ID with the help of the Global Catalog
57 and only search that domain. In contrast, if POSIX attributes are not
58 replicated to the Global Catalog, SSSD must search all the domains in
59 the forest sequentially. Please note that the “cache_first” option
60 might be also helpful in speeding up domainless searches. Note that if
61 only a subset of POSIX attributes is present in the Global Catalog, the
62 non-replicated attributes are currently not read from the LDAP port.
63 Users, groups and other entities served by SSSD are always treated as
65 case-insensitive in the AD provider for compatibility with Active
66 Directory's LDAP implementation.
67 SSSD only resolves Active Directory Security Groups. For more
69 information about AD group types see: Active Directory security
70 groups[1]
71 SSSD filters out Domain Local groups from remote domains in the AD
73 forest. By default they are filtered out e.g. when following a nested
74 group hierarchy in remote domains because they are not valid in the
75 local domain. This is done to be in agreement with Active Directory's
76 group-membership assignment which can be seen in the PAC of the
77 Kerberos ticket of a user issued by Active Directory.
78
80 Refer to the section “DOMAIN SECTIONS” of the sssd.conf(5) manual page
81 for details on the configuration of an SSSD domain.
82 ad_domain (string)
84 Specifies the name of the Active Directory domain. This is
85 optional. If not provided, the configuration domain name is used.
86 For proper operation, this option should be specified as the
88 lower-case version of the long version of the Active Directory
89 domain.
90 The short domain name (also known as the NetBIOS or the flat name)
92 is autodetected by the SSSD.
93 ad_enabled_domains (string)
95 A comma-separated list of enabled Active Directory domains. If
96 provided, SSSD will ignore any domains not listed in this option.
97 If left unset, all discovered domains from the AD forest will be
98 available.
99 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 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 ad_enabled_domains = sales.example.com, eng.example.com
110 The short domain name (also known as the NetBIOS or the flat name)
113 will be autodetected by SSSD.
114 Default: Not set
116 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 This is optional if autodiscovery is enabled. For more information
123 on service discovery, refer to the “SERVICE DISCOVERY” section.
124 Note: Trusted domains will always auto-discover servers even if the
126 primary server is explicitly defined in the ad_server option.
127 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 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 ad_enable_dns_sites (boolean)
139 Enables DNS sites - location based service discovery.
140 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 Default: true
150 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 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 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 Multiple filters can be separated with the “?” character,
168 similarly to how search bases work.
169 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 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 Examples:
184 # apply filter on domain called dom1 only:
186 dom1:(memberOf=cn=admins,ou=groups,dc=dom1,dc=com)
187 # apply filter on domain called dom2 only:
189 DOM:dom2:(memberOf=cn=admins,ou=groups,dc=dom2,dc=com)
190 # apply filter on forest called EXAMPLE.COM only:
192 FOREST:EXAMPLE.COM:(memberOf=cn=admins,ou=groups,dc=example,dc=com)
193 # 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 Default: Not set
199 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 Default: Not set
205 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 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 Default: true
219 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 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 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 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 • Read: The user or one of its groups must have read access to
246 the properties of the GPO (RIGHT_DS_READ_PROPERTY)
247 • 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 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 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 There are three supported values for this option:
270 • disabled: GPO-based access control rules are neither evaluated
272 nor enforced.
273 • enforcing: GPO-based access control rules are evaluated and
275 enforced.
276 • 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 Default: enforcing
283 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 Default: False
294 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 ┌───────────────────────────────────────────────┐
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 ┌───────────────────────────────────────────────┐
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 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 Default: False
350 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 Default: 5 (seconds)
357 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 Note: Using the Group Policy Management Editor this value is called
373 "Allow log on locally" and "Deny log on locally".
374 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 ad_gpo_map_interactive = +my_pam_service, -login
383 Default: the default set of PAM service names includes:
386 • login
388 • su
390 • su-l
392 • gdm-fingerprint
394 • gdm-password
396 • gdm-smartcard
398 • kdm
400 • lightdm
402 • lxdm
404 • sddm
406 • unity
408 • xdm
410 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 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 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 ad_gpo_map_remote_interactive = +my_pam_service, -sshd
439 Default: the default set of PAM service names includes:
442 • sshd
444 • cockpit
446 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 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 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 ad_gpo_map_network = +my_pam_service, -ftp
474 Default: the default set of PAM service names includes:
477 • ftp
479 • samba
481 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 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 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 ad_gpo_map_batch = +my_pam_service, -crond
507 Note: Cron service name may differ depending on Linux distribution
510 used.
511 Default: the default set of PAM service names includes:
513 • crond
515 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 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 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 ad_gpo_map_service = +my_pam_service
541 Default: not set
544 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 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 ad_gpo_map_permit = +my_pam_service, -sudo
558 Default: the default set of PAM service names includes:
561 • polkit-1
563 • sudo
565 • sudo-i
567 • systemd-user
569 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 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 ad_gpo_map_deny = +my_pam_service
582 Default: not set
585 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 Supported values for this option include:
598 • interactive
600 • remote_interactive
602 • network
604 • batch
606 • service
608 • permit
610 • deny
612 Default: deny
614 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 Default: 30 days
621 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 Default: 86400:750 (24h and 15m)
630 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 Default: false
638 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 Default: False
649 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 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 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 Default: False
679 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 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 Default: true
694 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 Default: 3600 (seconds)
701 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 Default: Use the IP addresses of the interface which is used for AD
709 LDAP connection
710 Example: dyndns_iface = em1, vnet1, vnet2
712 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 Default: 86400 (24 hours)
722 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 Note that dyndns_update_per_family parameter does not apply for PTR
729 record updates. Those updates are always sent separately.
730 Default: True
732 dyndns_force_tcp (bool)
734 Whether the nsupdate utility should default to using TCP for
735 communicating with the DNS server.
736 Default: False (let nsupdate choose the protocol)
738 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 Default: GSS-TSIG
745 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 Default: Same as dyndns_auth
752 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 Setting this option makes sense for environments where the DNS
758 server is different from the identity server.
759 Please note that this option will be only used in fallback attempt
761 when previous attempt using autodetected settings failed.
762 Default: None (let nsupdate choose the server)
764 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 Default: true
771 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 %u
778 login name
779 %U
781 UID number
782 %d
784 domain name
785 %f
787 fully qualified user name (user@domain)
788 %l
790 The first letter of the login name.
791 %P
793 UPN - User Principal Name (name@REALM)
794 %o
796 The original home directory retrieved from the identity
797 provider.
798 %h
800 The original home directory retrieved from the identity
801 provider, but in lower case.
802 %H
804 The value of configure option homedir_substring.
805 %%
807 a literal '%'
808 This option can also be set per-domain.
810 example:
812 override_homedir = /home/%u
814 Default: Not set (SSSD will use the value retrieved from LDAP)
817 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 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 Default: /home
833 krb5_confd_path (string)
835 Absolute path of a directory where SSSD should place Kerberos
836 configuration snippets.
837 To disable the creation of the configuration snippets set the
839 parameter to 'none'.
840 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 KRB5 Provider
850 • krb5_validate = true
851 • krb5_use_enterprise_principal = true
853 LDAP Provider
855 • ldap_schema = ad
856 • ldap_force_upper_case_realm = true
858 • ldap_id_mapping = true
860 • ldap_sasl_mech = GSS-SPNEGO
862 • ldap_referrals = false
864 • ldap_account_expire_policy = ad
866 • ldap_use_tokengroups = true
868 • ldap_sasl_authid = sAMAccountName@REALM (typically
870 SHORTNAME$@REALM)
871 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 NSS configuration
882 • fallback_homedir = /home/%d/%u
883 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 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 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 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 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 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 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 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 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 This section lists the available tunables. Please refer to their
946 description in the sssd.conf(5), manual page.
947 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 Default: 1000
953 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 Default: 3
960 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 Default: 6
967 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 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 The domain name
990 Please refer to the “dns_discovery_domain” parameter in the
991 sssd.conf(5) manual page for more details.
992 The protocol
994 The queries usually specify _tcp as the protocol. Exceptions are
995 documented in respective option description.
996 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 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 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 • Making sure the remote servers are reachable
1023 • Stopping the SSSD service
1025 • Removing the database
1027 • Starting the SSSD service
1029 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 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 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 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 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 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 Configuration
1065 Minimum configuration (in the “[domain/DOMAINNAME]” section):
1066 ldap_id_mapping = True
1068 ldap_schema = ad
1069 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 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 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 Default: 200000
1087 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 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 Default: 2000200000
1103 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 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 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 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 Default: 200000
1126 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 Default: not set
1134 ldap_idmap_default_domain (string)
1136 Specify the name of the default domain.
1137 Default: not set
1139 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 When this option is configured, domains will be allocated
1145 starting with slice zero and increasing monotonically with each
1146 additional domain.
1147 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 Default: False
1156 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 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 Default: 10
1168 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 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 • Null Authority
1179 • World Authority
1181 • Local Authority
1183 • Creator Authority
1185 • Mandatory Label Authority
1187 • Authentication Authority
1189 • NT Authority
1191 • Built-in
1193 The capitalized version of these names are used as domain names when
1195 returning the fully qualified name of a Well-Known SID.
1196 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 [domain/EXAMPLE]
1212 id_provider = ad
1213 auth_provider = ad
1214 access_provider = ad
1215 chpass_provider = ad
1216 ad_server = dc1.example.com
1218 ad_hostname = client.example.com
1219 ad_domain = example.com
1220
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 access_provider = ldap
1227 ldap_access_order = expire
1228 ldap_account_expire_policy = ad
1229 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 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 2. [MS-ADTS] section LDAP extensions
1256 https://msdn.microsoft.com/en-us/library/cc223367.aspx
1257SSSD 11/15/2023 SSSD-AD(5)