1SSSD-AD(5)               File Formats and Conventions               SSSD-AD(5)
2
3
4

NAME

6       sssd-ad - SSSD Active Directory provider
7

DESCRIPTION

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

CONFIGURATION OPTIONS

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           ┌───────────────────────────────────────────────┐
300ad_gpo_implicit_deny = False (default)         
301           ├────────────┬────────────┬─────────────────────┤
302allow-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           ┌───────────────────────────────────────────────┐
322ad_gpo_implicit_deny = True                    
323           ├────────────┬────────────┬─────────────────────┤
324allow-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

MODIFIED DEFAULT OPTIONS

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

FAILOVER

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

SERVICE DISCOVERY

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

ID MAPPING

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

EXAMPLE

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

NOTES

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

SEE ALSO

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

AUTHORS

1249       The SSSD upstream - https://github.com/SSSD/sssd/
1250

NOTES

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)
Impressum