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

CONFIGURATION OPTIONS

69       Refer to the section “DOMAIN SECTIONS” of the sssd.conf(5) manual page
70       for details on the configuration of an SSSD domain.
71
72       ad_domain (string)
73           Specifies the name of the Active Directory domain. This is
74           optional. If not provided, the configuration domain name is used.
75
76           For proper operation, this option should be specified as the
77           lower-case version of the long version of the Active Directory
78           domain.
79
80           The short domain name (also known as the NetBIOS or the flat name)
81           is autodetected by the SSSD.
82
83       ad_enabled_domains (string)
84           A comma-separated list of enabled Active Directory domains. If
85           provided, SSSD will ignore any domains not listed in this option.
86           If left unset, all domains from the AD forest will be available.
87
88           For proper operation, this option must be specified in all
89           lower-case and as the fully qualified domain name of the Active
90           Directory domain. For example:
91
92               ad_enabled_domains = sales.example.com, eng.example.com
93
94
95           The short domain name (also known as the NetBIOS or the flat name)
96           will be autodetected by SSSD.
97
98           Default: Not set
99
100       ad_server, ad_backup_server (string)
101           The comma-separated list of hostnames of the AD servers to which
102           SSSD should connect in order of preference. For more information on
103           failover and server redundancy, see the “FAILOVER” section.
104
105           This is optional if autodiscovery is enabled. For more information
106           on service discovery, refer to the “SERVICE DISCOVERY” section.
107
108           Note: Trusted domains will always auto-discover servers even if the
109           primary server is explicitly defined in the ad_server option.
110
111       ad_hostname (string)
112           Optional. On machines where the hostname(5) does not reflect the
113           fully qualified name, sssd will try to expand the short name. If it
114           is not possible or the short name should be really used instead,
115           set this parameter explicitly.
116
117           This field is used to determine the host principal in use in the
118           keytab and to perform dynamic DNS updates. It must match the
119           hostname for which the keytab was issued.
120
121       ad_enable_dns_sites (boolean)
122           Enables DNS sites - location based service discovery.
123
124           If true and service discovery (see Service Discovery paragraph at
125           the bottom of the man page) is enabled, the SSSD will first attempt
126           to discover the Active Directory server to connect to using the
127           Active Directory Site Discovery and fall back to the DNS SRV
128           records if no AD site is found. The DNS SRV configuration,
129           including the discovery domain, is used during site discovery as
130           well.
131
132           Default: true
133
134       ad_access_filter (string)
135           This option specifies LDAP access control filter that the user must
136           match in order to be allowed access. Please note that the
137           “access_provider” option must be explicitly set to “ad” in order
138           for this option to have an effect.
139
140           The option also supports specifying different filters per domain or
141           forest. This extended filter would consist of:
142           “KEYWORD:NAME:FILTER”. The keyword can be either “DOM”, “FOREST” or
143           missing.
144
145           If the keyword equals to “DOM” or is missing, then “NAME” specifies
146           the domain or subdomain the filter applies to. If the keyword
147           equals to “FOREST”, then the filter equals to all domains from the
148           forest specified by “NAME”.
149
150           Multiple filters can be separated with the “?”  character,
151           similarly to how search bases work.
152
153           Nested group membership must be searched for using a special OID
154           “:1.2.840.113556.1.4.1941:” in addition to the full
155           DOM:domain.example.org: syntax to ensure the parser does not
156           attempt to interpret the colon characters associated with the OID.
157           If you do not use this OID then nested group membership will not be
158           resolved. See usage example below and refer here for further
159           information about the OID: [MS-ADTS] section LDAP extensions[1]
160
161           The most specific match is always used. For example, if the option
162           specified filter for a domain the user is a member of and a global
163           filter, the per-domain filter would be applied. If there are more
164           matches with the same specification, the first one is used.
165
166           Examples:
167
168               # apply filter on domain called dom1 only:
169               dom1:(memberOf=cn=admins,ou=groups,dc=dom1,dc=com)
170
171               # apply filter on domain called dom2 only:
172               DOM:dom2:(memberOf=cn=admins,ou=groups,dc=dom2,dc=com)
173
174               # apply filter on forest called EXAMPLE.COM only:
175               FOREST:EXAMPLE.COM:(memberOf=cn=admins,ou=groups,dc=example,dc=com)
176
177               # apply filter for a member of a nested group in dom1:
178               DOM:dom1:(memberOf:1.2.840.113556.1.4.1941:=cn=nestedgroup,ou=groups,dc=example,dc=com)
179
180
181           Default: Not set
182
183       ad_site (string)
184           Specify AD site to which client should try to connect. If this
185           option is not provided, the AD site will be auto-discovered.
186
187           Default: Not set
188
189       ad_enable_gc (boolean)
190           By default, the SSSD connects to the Global Catalog first to
191           retrieve users from trusted domains and uses the LDAP port to
192           retrieve group memberships or as a fallback. Disabling this option
193           makes the SSSD only connect to the LDAP port of the current AD
194           server.
195
196           Please note that disabling Global Catalog support does not disable
197           retrieving users from trusted domains. The SSSD would connect to
198           the LDAP port of trusted domains instead. However, Global Catalog
199           must be used in order to resolve cross-domain group memberships.
200
201           Default: true
202
203       ad_gpo_access_control (string)
204           This option specifies the operation mode for GPO-based access
205           control functionality: whether it operates in disabled mode,
206           enforcing mode, or permissive mode. Please note that the
207           “access_provider” option must be explicitly set to “ad” in order
208           for this option to have an effect.
209
210           GPO-based access control functionality uses GPO policy settings to
211           determine whether or not a particular user is allowed to logon to
212           the host. For more information on the supported policy settings
213           please refer to the “ad_gpo_map” options.
214
215           Please note that current version of SSSD does not support Active
216           Directory's built-in groups. Built-in groups (such as
217           Administrators with SID S-1-5-32-544) in GPO access control rules
218           will be ignored by SSSD. See upstream issue tracker
219           https://github.com/SSSD/sssd/issues/5063 .
220
221           Before performing access control SSSD applies group policy security
222           filtering on the GPOs. For every single user login, the
223           applicability of the GPOs that are linked to the host is checked.
224           In order for a GPO to apply to a user, the user or at least one of
225           the groups to which it belongs must have following permissions on
226           the GPO:
227
228           •   Read: The user or one of its groups must have read access to
229               the properties of the GPO (RIGHT_DS_READ_PROPERTY)
230
231           •   Apply Group Policy: The user or at least one of its groups must
232               be allowed to apply the GPO (RIGHT_DS_CONTROL_ACCESS).
233
234           By default, the Authenticated Users group is present on a GPO and
235           this group has both Read and Apply Group Policy access rights.
236           Since authentication of a user must have been completed
237           successfully before GPO security filtering and access control are
238           started, the Authenticated Users group permissions on the GPO
239           always apply also to the user.
240
241           NOTE: If the operation mode is set to enforcing, it is possible
242           that users that were previously allowed logon access will now be
243           denied logon access (as dictated by the GPO policy settings). In
244           order to facilitate a smooth transition for administrators, a
245           permissive mode is available that will not enforce the access
246           control rules, but will evaluate them and will output a syslog
247           message if access would have been denied. By examining the logs,
248           administrators can then make the necessary changes before setting
249           the mode to enforcing. For logging GPO-based access control debug
250           level 'trace functions' is required (see sssctl(8) manual page).
251
252           There are three supported values for this option:
253
254           •   disabled: GPO-based access control rules are neither evaluated
255               nor enforced.
256
257           •   enforcing: GPO-based access control rules are evaluated and
258               enforced.
259
260           •   permissive: GPO-based access control rules are evaluated, but
261               not enforced. Instead, a syslog message will be emitted
262               indicating that the user would have been denied access if this
263               option's value were set to enforcing.
264
265           Default: enforcing
266
267       ad_gpo_implicit_deny (boolean)
268           Normally when no applicable GPOs are found the users are allowed
269           access. When this option is set to True users will be allowed
270           access only when explicitly allowed by a GPO rule. Otherwise users
271           will be denied access. This can be used to harden security but be
272           careful when using this option because it can deny access even to
273           users in the built-in Administrators group if no GPO rules apply to
274           them.
275
276           Default: False
277
278           The following 2 tables should illustrate when a user is allowed or
279           rejected based on the allow and deny login rights defined on the
280           server-side and the setting of ad_gpo_implicit_deny.
281
282           ┌───────────────────────────────────────────────┐
283ad_gpo_implicit_deny = False (default)         
284           ├────────────┬────────────┬─────────────────────┤
285allow-rules deny-rules results       
286           ├────────────┼────────────┼─────────────────────┤
287           │  missing   │  missing   │    all users are    │
288           │            │            │    allowed          │
289           ├────────────┼────────────┼─────────────────────┤
290           │  missing   │  present   │  only users not in  │
291           │            │            │  deny-rules are     │
292           │            │            │  allowed            │
293           ├────────────┼────────────┼─────────────────────┤
294           │  present   │  missing   │   only users in     │
295           │            │            │   allow-rules are   │
296           │            │            │   allowed           │
297           ├────────────┼────────────┼─────────────────────┤
298           │  present   │  present   │ only users in       │
299           │            │            │ allow-rules and not │
300           │            │            │ in deny-rules are   │
301           │            │            │ allowed             │
302           └────────────┴────────────┴─────────────────────┘
303
304           ┌───────────────────────────────────────────────┐
305ad_gpo_implicit_deny = True                    
306           ├────────────┬────────────┬─────────────────────┤
307allow-rules deny-rules results       
308           ├────────────┼────────────┼─────────────────────┤
309           │  missing   │  missing   │    no users are     │
310           │            │            │    allowed          │
311           ├────────────┼────────────┼─────────────────────┤
312           │  missing   │  present   │    no users are     │
313           │            │            │    allowed          │
314           ├────────────┼────────────┼─────────────────────┤
315           │  present   │  missing   │   only users in     │
316           │            │            │   allow-rules are   │
317           │            │            │   allowed           │
318           ├────────────┼────────────┼─────────────────────┤
319           │  present   │  present   │ only users in       │
320           │            │            │ allow-rules and not │
321           │            │            │ in deny-rules are   │
322           │            │            │ allowed             │
323           └────────────┴────────────┴─────────────────────┘
324
325       ad_gpo_ignore_unreadable (boolean)
326           Normally when some group policy containers (AD object) of
327           applicable group policy objects are not readable by SSSD then users
328           are denied access. This option allows to ignore group policy
329           containers and with them associated policies if their attributes in
330           group policy containers are not readable for SSSD.
331
332           Default: False
333
334       ad_gpo_cache_timeout (integer)
335           The amount of time between lookups of GPO policy files against the
336           AD server. This will reduce the latency and load on the AD server
337           if there are many access-control requests made in a short period.
338
339           Default: 5 (seconds)
340
341       ad_gpo_map_interactive (string)
342           A comma-separated list of PAM service names for which GPO-based
343           access control is evaluated based on the InteractiveLogonRight and
344           DenyInteractiveLogonRight policy settings. Only those GPOs are
345           evaluated for which the user has Read and Apply Group Policy
346           permission (see option “ad_gpo_access_control”). If an evaluated
347           GPO contains the deny interactive logon setting for the user or one
348           of its groups, the user is denied local access. If none of the
349           evaluated GPOs has an interactive logon right defined, the user is
350           granted local access. If at least one evaluated GPO contains
351           interactive logon right settings, the user is granted local access
352           only, if it or at least one of its groups is part of the policy
353           settings.
354
355           Note: Using the Group Policy Management Editor this value is called
356           "Allow log on locally" and "Deny log on locally".
357
358           It is possible to add another PAM service name to the default set
359           by using “+service_name” or to explicitly remove a PAM service name
360           from the default set by using “-service_name”. For example, in
361           order to replace a default PAM service name for this logon right
362           (e.g.  “login”) with a custom pam service name (e.g.
363           “my_pam_service”), you would use the following configuration:
364
365               ad_gpo_map_interactive = +my_pam_service, -login
366
367
368           Default: the default set of PAM service names includes:
369
370           •   login
371
372           •   su
373
374           •   su-l
375
376           •   gdm-fingerprint
377
378           •   gdm-password
379
380           •   gdm-smartcard
381
382           •   kdm
383
384           •   lightdm
385
386           •   lxdm
387
388           •   sddm
389
390           •   unity
391
392           •   xdm
393
394
395       ad_gpo_map_remote_interactive (string)
396           A comma-separated list of PAM service names for which GPO-based
397           access control is evaluated based on the
398           RemoteInteractiveLogonRight and DenyRemoteInteractiveLogonRight
399           policy settings. Only those GPOs are evaluated for which the user
400           has Read and Apply Group Policy permission (see option
401           “ad_gpo_access_control”). If an evaluated GPO contains the deny
402           remote logon setting for the user or one of its groups, the user is
403           denied remote interactive access. If none of the evaluated GPOs has
404           a remote interactive logon right defined, the user is granted
405           remote access. If at least one evaluated GPO contains remote
406           interactive logon right settings, the user is granted remote access
407           only, if it or at least one of its groups is part of the policy
408           settings.
409
410           Note: Using the Group Policy Management Editor this value is called
411           "Allow log on through Remote Desktop Services" and "Deny log on
412           through Remote Desktop Services".
413
414           It is possible to add another PAM service name to the default set
415           by using “+service_name” or to explicitly remove a PAM service name
416           from the default set by using “-service_name”. For example, in
417           order to replace a default PAM service name for this logon right
418           (e.g.  “sshd”) with a custom pam service name (e.g.
419           “my_pam_service”), you would use the following configuration:
420
421               ad_gpo_map_remote_interactive = +my_pam_service, -sshd
422
423
424           Default: the default set of PAM service names includes:
425
426           •   sshd
427
428           •   cockpit
429
430
431       ad_gpo_map_network (string)
432           A comma-separated list of PAM service names for which GPO-based
433           access control is evaluated based on the NetworkLogonRight and
434           DenyNetworkLogonRight policy settings. Only those GPOs are
435           evaluated for which the user has Read and Apply Group Policy
436           permission (see option “ad_gpo_access_control”). If an evaluated
437           GPO contains the deny network logon setting for the user or one of
438           its groups, the user is denied network logon access. If none of the
439           evaluated GPOs has a network logon right defined, the user is
440           granted logon access. If at least one evaluated GPO contains
441           network logon right settings, the user is granted logon access
442           only, if it or at least one of its groups is part of the policy
443           settings.
444
445           Note: Using the Group Policy Management Editor this value is called
446           "Access this computer from the network" and "Deny access to this
447           computer from the network".
448
449           It is possible to add another PAM service name to the default set
450           by using “+service_name” or to explicitly remove a PAM service name
451           from the default set by using “-service_name”. For example, in
452           order to replace a default PAM service name for this logon right
453           (e.g.  “ftp”) with a custom pam service name (e.g.
454           “my_pam_service”), you would use the following configuration:
455
456               ad_gpo_map_network = +my_pam_service, -ftp
457
458
459           Default: the default set of PAM service names includes:
460
461           •   ftp
462
463           •   samba
464
465
466       ad_gpo_map_batch (string)
467           A comma-separated list of PAM service names for which GPO-based
468           access control is evaluated based on the BatchLogonRight and
469           DenyBatchLogonRight policy settings. Only those GPOs are evaluated
470           for which the user has Read and Apply Group Policy permission (see
471           option “ad_gpo_access_control”). If an evaluated GPO contains the
472           deny batch logon setting for the user or one of its groups, the
473           user is denied batch logon access. If none of the evaluated GPOs
474           has a batch logon right defined, the user is granted logon access.
475           If at least one evaluated GPO contains batch logon right settings,
476           the user is granted logon access only, if it or at least one of its
477           groups is part of the policy settings.
478
479           Note: Using the Group Policy Management Editor this value is called
480           "Allow log on as a batch job" and "Deny log on as a batch job".
481
482           It is possible to add another PAM service name to the default set
483           by using “+service_name” or to explicitly remove a PAM service name
484           from the default set by using “-service_name”. For example, in
485           order to replace a default PAM service name for this logon right
486           (e.g.  “crond”) with a custom pam service name (e.g.
487           “my_pam_service”), you would use the following configuration:
488
489               ad_gpo_map_batch = +my_pam_service, -crond
490
491
492           Note: Cron service name may differ depending on Linux distribution
493           used.
494
495           Default: the default set of PAM service names includes:
496
497           •   crond
498
499
500       ad_gpo_map_service (string)
501           A comma-separated list of PAM service names for which GPO-based
502           access control is evaluated based on the ServiceLogonRight and
503           DenyServiceLogonRight policy settings. Only those GPOs are
504           evaluated for which the user has Read and Apply Group Policy
505           permission (see option “ad_gpo_access_control”). If an evaluated
506           GPO contains the deny service logon setting for the user or one of
507           its groups, the user is denied service logon access. If none of the
508           evaluated GPOs has a service logon right defined, the user is
509           granted logon access. If at least one evaluated GPO contains
510           service logon right settings, the user is granted logon access
511           only, if it or at least one of its groups is part of the policy
512           settings.
513
514           Note: Using the Group Policy Management Editor this value is called
515           "Allow log on as a service" and "Deny log on as a service".
516
517           It is possible to add a PAM service name to the default set by
518           using “+service_name”. Since the default set is empty, it is not
519           possible to remove a PAM service name from the default set. For
520           example, in order to add a custom pam service name (e.g.
521           “my_pam_service”), you would use the following configuration:
522
523               ad_gpo_map_service = +my_pam_service
524
525
526           Default: not set
527
528       ad_gpo_map_permit (string)
529           A comma-separated list of PAM service names for which GPO-based
530           access is always granted, regardless of any GPO Logon Rights.
531
532           It is possible to add another PAM service name to the default set
533           by using “+service_name” or to explicitly remove a PAM service name
534           from the default set by using “-service_name”. For example, in
535           order to replace a default PAM service name for unconditionally
536           permitted access (e.g.  “sudo”) with a custom pam service name
537           (e.g.  “my_pam_service”), you would use the following
538           configuration:
539
540               ad_gpo_map_permit = +my_pam_service, -sudo
541
542
543           Default: the default set of PAM service names includes:
544
545           •   polkit-1
546
547           •   sudo
548
549           •   sudo-i
550
551           •   systemd-user
552
553
554       ad_gpo_map_deny (string)
555           A comma-separated list of PAM service names for which GPO-based
556           access is always denied, regardless of any GPO Logon Rights.
557
558           It is possible to add a PAM service name to the default set by
559           using “+service_name”. Since the default set is empty, it is not
560           possible to remove a PAM service name from the default set. For
561           example, in order to add a custom pam service name (e.g.
562           “my_pam_service”), you would use the following configuration:
563
564               ad_gpo_map_deny = +my_pam_service
565
566
567           Default: not set
568
569       ad_gpo_default_right (string)
570           This option defines how access control is evaluated for PAM service
571           names that are not explicitly listed in one of the ad_gpo_map_*
572           options. This option can be set in two different manners. First,
573           this option can be set to use a default logon right. For example,
574           if this option is set to 'interactive', it means that unmapped PAM
575           service names will be processed based on the InteractiveLogonRight
576           and DenyInteractiveLogonRight policy settings. Alternatively, this
577           option can be set to either always permit or always deny access for
578           unmapped PAM service names.
579
580           Supported values for this option include:
581
582           •   interactive
583
584           •   remote_interactive
585
586           •   network
587
588           •   batch
589
590           •   service
591
592           •   permit
593
594           •   deny
595
596           Default: deny
597
598       ad_maximum_machine_account_password_age (integer)
599           SSSD will check once a day if the machine account password is older
600           than the given age in days and try to renew it. A value of 0 will
601           disable the renewal attempt.
602
603           Default: 30 days
604
605       ad_machine_account_password_renewal_opts (string)
606           This option should only be used to test the machine account renewal
607           task. The option expects 2 integers separated by a colon (':'). The
608           first integer defines the interval in seconds how often the task is
609           run. The second specifies the initial timeout in seconds before the
610           task is run for the first time after startup.
611
612           Default: 86400:750 (24h and 15m)
613
614       ad_update_samba_machine_account_password (boolean)
615           If enabled, when SSSD renews the machine account password, it will
616           also be updated in Samba's database. This prevents Samba's copy of
617           the machine account password from getting out of date when it is
618           set up to use AD for authentication.
619
620           Default: false
621
622       ad_use_ldaps (bool)
623           By default SSSD uses the plain LDAP port 389 and the Global Catalog
624           port 3628. If this option is set to True SSSD will use the LDAPS
625           port 636 and Global Catalog port 3629 with LDAPS protection. Since
626           AD does not allow to have multiple encryption layers on a single
627           connection and we still want to use SASL/GSSAPI or SASL/GSS-SPNEGO
628           for authentication the SASL security property maxssf is set to 0
629           (zero) for those connections.
630
631           Default: False
632
633       ad_allow_remote_domain_local_groups (boolean)
634           If this option is set to “true” SSSD will not filter out Domain
635           Local groups from remote domains in the AD forest. By default they
636           are filtered out e.g. when following a nested group hierarchy in
637           remote domains because they are not valid in the local domain. To
638           be compatible with other solutions which make AD users and groups
639           available on Linux client this option was added.
640
641           Please note that setting this option to “true” will be against the
642           intention of Domain Local group in Active Directory and SHOULD ONLY
643           BE USED TO FACILITATE MIGRATION FROM OTHER SOLUTIONS. Although the
644           group exists and user can be member of the group the intention is
645           that the group should be only used in the domain it is defined and
646           in no others. Since there is only one type of POSIX groups the only
647           way to achieve this on the Linux side is to ignore those groups.
648           This is also done by Active Directory as can be seen in the PAC of
649           the Kerberos ticket for a local service or in tokenGroups requests
650           where remote Domain Local groups are missing as well.
651
652           Given the comments above, if this option is set to “true” the
653           tokenGroups request must be disabled by setting
654           “ldap_use_tokengroups” to “false” to get consistent
655           group-memberships of a users. Additionally the Global Catalog
656           lookup should be skipped as well by setting “ad_enable_gc” to
657           “false”. Finally it might be necessary to modify
658           “ldap_group_nesting_level” if the remote Domain Local groups can
659           only be found with a deeper nesting level.
660
661           Default: False
662
663       dyndns_update (boolean)
664           Optional. This option tells SSSD to automatically update the Active
665           Directory DNS server with the IP address of this client. The update
666           is secured using GSS-TSIG. As a consequence, the Active Directory
667           administrator only needs to allow secure updates for the DNS zone.
668           The IP address of the AD LDAP connection is used for the updates,
669           if it is not otherwise specified by using the “dyndns_iface”
670           option.
671
672           NOTE: On older systems (such as RHEL 5), for this behavior to work
673           reliably, the default Kerberos realm must be set properly in
674           /etc/krb5.conf
675
676           Default: true
677
678       dyndns_ttl (integer)
679           The TTL to apply to the client DNS record when updating it. If
680           dyndns_update is false this has no effect. This will override the
681           TTL serverside if set by an administrator.
682
683           Default: 3600 (seconds)
684
685       dyndns_iface (string)
686           Optional. Applicable only when dyndns_update is true. Choose the
687           interface or a list of interfaces whose IP addresses should be used
688           for dynamic DNS updates. Special value “*” implies that IPs from
689           all interfaces should be used.
690
691           Default: Use the IP addresses of the interface which is used for AD
692           LDAP connection
693
694           Example: dyndns_iface = em1, vnet1, vnet2
695
696       dyndns_refresh_interval (integer)
697           How often should the back end perform periodic DNS update in
698           addition to the automatic update performed when the back end goes
699           online. This option is optional and applicable only when
700           dyndns_update is true. Note that the lowest possible value is 60
701           seconds in-case if value is provided less than 60, parameter will
702           assume lowest value only.
703
704           Default: 86400 (24 hours)
705
706       dyndns_update_ptr (bool)
707           Whether the PTR record should also be explicitly updated when
708           updating the client's DNS records. Applicable only when
709           dyndns_update is true.
710
711           Default: True
712
713       dyndns_force_tcp (bool)
714           Whether the nsupdate utility should default to using TCP for
715           communicating with the DNS server.
716
717           Default: False (let nsupdate choose the protocol)
718
719       dyndns_auth (string)
720           Whether the nsupdate utility should use GSS-TSIG authentication for
721           secure updates with the DNS server, insecure updates can be sent by
722           setting this option to 'none'.
723
724           Default: GSS-TSIG
725
726       dyndns_auth_ptr (string)
727           Whether the nsupdate utility should use GSS-TSIG authentication for
728           secure PTR updates with the DNS server, insecure updates can be
729           sent by setting this option to 'none'.
730
731           Default: Same as dyndns_auth
732
733       dyndns_server (string)
734           The DNS server to use when performing a DNS update. In most setups,
735           it's recommended to leave this option unset.
736
737           Setting this option makes sense for environments where the DNS
738           server is different from the identity server.
739
740           Please note that this option will be only used in fallback attempt
741           when previous attempt using autodetected settings failed.
742
743           Default: None (let nsupdate choose the server)
744
745       dyndns_update_per_family (boolean)
746           DNS update is by default performed in two steps - IPv4 update and
747           then IPv6 update. In some cases it might be desirable to perform
748           IPv4 and IPv6 update in single step.
749
750           Default: true
751
752       override_homedir (string)
753           Override the user's home directory. You can either provide an
754           absolute value or a template. In the template, the following
755           sequences are substituted:
756
757           %u
758               login name
759
760           %U
761               UID number
762
763           %d
764               domain name
765
766           %f
767               fully qualified user name (user@domain)
768
769           %l
770               The first letter of the login name.
771
772           %P
773               UPN - User Principal Name (name@REALM)
774
775           %o
776               The original home directory retrieved from the identity
777               provider.
778
779           %H
780               The value of configure option homedir_substring.
781
782           %%
783               a literal '%'
784
785           This option can also be set per-domain.
786
787           example:
788
789               override_homedir = /home/%u
790
791
792           Default: Not set (SSSD will use the value retrieved from LDAP)
793
794           Please note, the home directory from a specific override for the
795           user, either locally (see sss_override(8)) or centrally managed IPA
796           id-overrides, has a higher precedence and will be used instead of
797           the value given by override_homedir.
798
799       homedir_substring (string)
800           The value of this option will be used in the expansion of the
801           override_homedir option if the template contains the format string
802           %H. An LDAP directory entry can directly contain this template so
803           that this option can be used to expand the home directory path for
804           each client machine (or operating system). It can be set per-domain
805           or globally in the [nss] section. A value specified in a domain
806           section will override one set in the [nss] section.
807
808           Default: /home
809
810       krb5_confd_path (string)
811           Absolute path of a directory where SSSD should place Kerberos
812           configuration snippets.
813
814           To disable the creation of the configuration snippets set the
815           parameter to 'none'.
816
817           Default: not set (krb5.include.d subdirectory of SSSD's pubconf
818           directory)
819

MODIFIED DEFAULT OPTIONS

821       Certain option defaults do not match their respective backend provider
822       defaults, these option names and AD provider-specific defaults are
823       listed below:
824
825   KRB5 Provider
826       •   krb5_validate = true
827
828       •   krb5_use_enterprise_principal = true
829
830   LDAP Provider
831       •   ldap_schema = ad
832
833       •   ldap_force_upper_case_realm = true
834
835       •   ldap_id_mapping = true
836
837       •   ldap_sasl_mech = GSS-SPNEGO
838
839       •   ldap_referrals = false
840
841       •   ldap_account_expire_policy = ad
842
843       •   ldap_use_tokengroups = true
844
845       •   ldap_sasl_authid = sAMAccountName@REALM (typically
846           SHORTNAME$@REALM)
847
848           The AD provider looks for a different principal than the LDAP
849           provider by default, because in an Active Directory environment the
850           principals are divided into two groups - User Principals and
851           Service Principals. Only User Principal can be used to obtain a TGT
852           and by default, computer object's principal is constructed from its
853           sAMAccountName and the AD realm. The well-known host/hostname@REALM
854           principal is a Service Principal and thus cannot be used to get a
855           TGT with.
856
857   NSS configuration
858       •   fallback_homedir = /home/%d/%u
859
860           The AD provider automatically sets "fallback_homedir = /home/%d/%u"
861           to provide personal home directories for users without the
862           homeDirectory attribute. If your AD Domain is properly populated
863           with Posix attributes, and you want to avoid this fallback
864           behavior, you can explicitly set "fallback_homedir = %o".
865
866           Note that the system typically expects a home directory in /home/%u
867           folder. If you decide to use a different directory structure, some
868           other parts of your system may need adjustments.
869
870           For example automated creation of home directories in combination
871           with selinux requires selinux adjustment, otherwise the home
872           directory will be created with wrong selinux context.
873

FAILOVER

875       The failover feature allows back ends to automatically switch to a
876       different server if the current server fails.
877
878   Failover Syntax
879       The list of servers is given as a comma-separated list; any number of
880       spaces is allowed around the comma. The servers are listed in order of
881       preference. The list can contain any number of servers.
882
883       For each failover-enabled config option, two variants exist: primary
884       and backup. The idea is that servers in the primary list are preferred
885       and backup servers are only searched if no primary servers can be
886       reached. If a backup server is selected, a timeout of 31 seconds is
887       set. After this timeout SSSD will periodically try to reconnect to one
888       of the primary servers. If it succeeds, it will replace the current
889       active (backup) server.
890
891   The Failover Mechanism
892       The failover mechanism distinguishes between a machine and a service.
893       The back end first tries to resolve the hostname of a given machine; if
894       this resolution attempt fails, the machine is considered offline. No
895       further attempts are made to connect to this machine for any other
896       service. If the resolution attempt succeeds, the back end tries to
897       connect to a service on this machine. If the service connection attempt
898       fails, then only this particular service is considered offline and the
899       back end automatically switches over to the next service. The machine
900       is still considered online and might still be tried for another
901       service.
902
903       Further connection attempts are made to machines or services marked as
904       offline after a specified period of time; this is currently hard coded
905       to 30 seconds.
906
907       If there are no more machines to try, the back end as a whole switches
908       to offline mode, and then attempts to reconnect every 30 seconds.
909
910   Failover time outs and tuning
911       Resolving a server to connect to can be as simple as running a single
912       DNS query or can involve several steps, such as finding the correct
913       site or trying out multiple host names in case some of the configured
914       servers are not reachable. The more complex scenarios can take some
915       time and SSSD needs to balance between providing enough time to finish
916       the resolution process but on the other hand, not trying for too long
917       before falling back to offline mode. If the SSSD debug logs show that
918       the server resolution is timing out before a live server is contacted,
919       you can consider changing the time outs.
920
921       This section lists the available tunables. Please refer to their
922       description in the sssd.conf(5), manual page.
923
924       dns_resolver_server_timeout
925           Time in milliseconds that sets how long would SSSD talk to a single
926           DNS server before trying next one.
927
928           Default: 1000
929
930       dns_resolver_op_timeout
931           Time in seconds to tell how long would SSSD try to resolve single
932           DNS query (e.g. resolution of a hostname or an SRV record) before
933           trying the next hostname or discovery domain.
934
935           Default: 3
936
937       dns_resolver_timeout
938           How long would SSSD try to resolve a failover service. This service
939           resolution internally might include several steps, such as
940           resolving DNS SRV queries or locating the site.
941
942           Default: 6
943
944       For LDAP-based providers, the resolve operation is performed as part of
945       an LDAP connection operation. Therefore, also the “ldap_opt_timeout”
946       timeout should be set to a larger value than “dns_resolver_timeout”
947       which in turn should be set to a larger value than
948       “dns_resolver_op_timeout” which should be larger than
949       “dns_resolver_server_timeout”.
950

SERVICE DISCOVERY

952       The service discovery feature allows back ends to automatically find
953       the appropriate servers to connect to using a special DNS query. This
954       feature is not supported for backup servers.
955
956   Configuration
957       If no servers are specified, the back end automatically uses service
958       discovery to try to find a server. Optionally, the user may choose to
959       use both fixed server addresses and service discovery by inserting a
960       special keyword, “_srv_”, in the list of servers. The order of
961       preference is maintained. This feature is useful if, for example, the
962       user prefers to use service discovery whenever possible, and fall back
963       to a specific server when no servers can be discovered using DNS.
964
965   The domain name
966       Please refer to the “dns_discovery_domain” parameter in the
967       sssd.conf(5) manual page for more details.
968
969   The protocol
970       The queries usually specify _tcp as the protocol. Exceptions are
971       documented in respective option description.
972
973   See Also
974       For more information on the service discovery mechanism, refer to RFC
975       2782.
976

ID MAPPING

978       The ID-mapping feature allows SSSD to act as a client of Active
979       Directory without requiring administrators to extend user attributes to
980       support POSIX attributes for user and group identifiers.
981
982       NOTE: When ID-mapping is enabled, the uidNumber and gidNumber
983       attributes are ignored. This is to avoid the possibility of conflicts
984       between automatically-assigned and manually-assigned values. If you
985       need to use manually-assigned values, ALL values must be
986       manually-assigned.
987
988       Please note that changing the ID mapping related configuration options
989       will cause user and group IDs to change. At the moment, SSSD does not
990       support changing IDs, so the SSSD database must be removed. Because
991       cached passwords are also stored in the database, removing the database
992       should only be performed while the authentication servers are
993       reachable, otherwise users might get locked out. In order to cache the
994       password, an authentication must be performed. It is not sufficient to
995       use sss_cache(8) to remove the database, rather the process consists
996       of:
997
998       •   Making sure the remote servers are reachable
999
1000       •   Stopping the SSSD service
1001
1002       •   Removing the database
1003
1004       •   Starting the SSSD service
1005
1006       Moreover, as the change of IDs might necessitate the adjustment of
1007       other system properties such as file and directory ownership, it's
1008       advisable to plan ahead and test the ID mapping configuration
1009       thoroughly.
1010
1011   Mapping Algorithm
1012       Active Directory provides an objectSID for every user and group object
1013       in the directory. This objectSID can be broken up into components that
1014       represent the Active Directory domain identity and the relative
1015       identifier (RID) of the user or group object.
1016
1017       The SSSD ID-mapping algorithm takes a range of available UIDs and
1018       divides it into equally-sized component sections - called "slices"-.
1019       Each slice represents the space available to an Active Directory
1020       domain.
1021
1022       When a user or group entry for a particular domain is encountered for
1023       the first time, the SSSD allocates one of the available slices for that
1024       domain. In order to make this slice-assignment repeatable on different
1025       client machines, we select the slice based on the following algorithm:
1026
1027       The SID string is passed through the murmurhash3 algorithm to convert
1028       it to a 32-bit hashed value. We then take the modulus of this value
1029       with the total number of available slices to pick the slice.
1030
1031       NOTE: It is possible to encounter collisions in the hash and subsequent
1032       modulus. In these situations, we will select the next available slice,
1033       but it may not be possible to reproduce the same exact set of slices on
1034       other machines (since the order that they are encountered will
1035       determine their slice). In this situation, it is recommended to either
1036       switch to using explicit POSIX attributes in Active Directory
1037       (disabling ID-mapping) or configure a default domain to guarantee that
1038       at least one is always consistent. See “Configuration” for details.
1039
1040   Configuration
1041       Minimum configuration (in the “[domain/DOMAINNAME]” section):
1042
1043           ldap_id_mapping = True
1044           ldap_schema = ad
1045
1046       The default configuration results in configuring 10,000 slices, each
1047       capable of holding up to 200,000 IDs, starting from 200,000 and going
1048       up to 2,000,200,000. This should be sufficient for most deployments.
1049
1050       Advanced Configuration
1051           ldap_idmap_range_min (integer)
1052               Specifies the lower (inclusive) bound of the range of POSIX IDs
1053               to use for mapping Active Directory user and group SIDs. It is
1054               the first POSIX ID which can be used for the mapping.
1055
1056               NOTE: This option is different from “min_id” in that “min_id”
1057               acts to filter the output of requests to this domain, whereas
1058               this option controls the range of ID assignment. This is a
1059               subtle distinction, but the good general advice would be to
1060               have “min_id” be less-than or equal to “ldap_idmap_range_min”
1061
1062               Default: 200000
1063
1064           ldap_idmap_range_max (integer)
1065               Specifies the upper (exclusive) bound of the range of POSIX IDs
1066               to use for mapping Active Directory user and group SIDs. It is
1067               the first POSIX ID which cannot be used for the mapping
1068               anymore, i.e. one larger than the last one which can be used
1069               for the mapping.
1070
1071               NOTE: This option is different from “max_id” in that “max_id”
1072               acts to filter the output of requests to this domain, whereas
1073               this option controls the range of ID assignment. This is a
1074               subtle distinction, but the good general advice would be to
1075               have “max_id” be greater-than or equal to
1076               “ldap_idmap_range_max”
1077
1078               Default: 2000200000
1079
1080           ldap_idmap_range_size (integer)
1081               Specifies the number of IDs available for each slice. If the
1082               range size does not divide evenly into the min and max values,
1083               it will create as many complete slices as it can.
1084
1085               NOTE: The value of this option must be at least as large as the
1086               highest user RID planned for use on the Active Directory
1087               server. User lookups and login will fail for any user whose RID
1088               is greater than this value.
1089
1090               For example, if your most recently-added Active Directory user
1091               has objectSid=S-1-5-21-2153326666-2176343378-3404031434-1107,
1092               “ldap_idmap_range_size” must be at least 1108 as range size is
1093               equal to maximal SID minus minimal SID plus one (e.g. 1108 =
1094               1107 - 0 + 1).
1095
1096               It is important to plan ahead for future expansion, as changing
1097               this value will result in changing all of the ID mappings on
1098               the system, leading to users with different local IDs than they
1099               previously had.
1100
1101               Default: 200000
1102
1103           ldap_idmap_default_domain_sid (string)
1104               Specify the domain SID of the default domain. This will
1105               guarantee that this domain will always be assigned to slice
1106               zero in the ID map, bypassing the murmurhash algorithm
1107               described above.
1108
1109               Default: not set
1110
1111           ldap_idmap_default_domain (string)
1112               Specify the name of the default domain.
1113
1114               Default: not set
1115
1116           ldap_idmap_autorid_compat (boolean)
1117               Changes the behavior of the ID-mapping algorithm to behave more
1118               similarly to winbind's “idmap_autorid” algorithm.
1119
1120               When this option is configured, domains will be allocated
1121               starting with slice zero and increasing monatomically with each
1122               additional domain.
1123
1124               NOTE: This algorithm is non-deterministic (it depends on the
1125               order that users and groups are requested). If this mode is
1126               required for compatibility with machines running winbind, it is
1127               recommended to also use the “ldap_idmap_default_domain_sid”
1128               option to guarantee that at least one domain is consistently
1129               allocated to slice zero.
1130
1131               Default: False
1132
1133           ldap_idmap_helper_table_size (integer)
1134               Maximal number of secondary slices that is tried when
1135               performing mapping from UNIX id to SID.
1136
1137               Note: Additional secondary slices might be generated when SID
1138               is being mapped to UNIX id and RID part of SID is out of range
1139               for secondary slices generated so far. If value of
1140               ldap_idmap_helper_table_size is equal to 0 then no additional
1141               secondary slices are generated.
1142
1143               Default: 10
1144
1145   Well-Known SIDs
1146       SSSD supports to look up the names of Well-Known SIDs, i.e. SIDs with a
1147       special hardcoded meaning. Since the generic users and groups related
1148       to those Well-Known SIDs have no equivalent in a Linux/UNIX environment
1149       no POSIX IDs are available for those objects.
1150
1151       The SID name space is organized in authorities which can be seen as
1152       different domains. The authorities for the Well-Known SIDs are
1153
1154       •   Null Authority
1155
1156       •   World Authority
1157
1158       •   Local Authority
1159
1160       •   Creator Authority
1161
1162       •   NT Authority
1163
1164       •   Built-in
1165
1166       The capitalized version of these names are used as domain names when
1167       returning the fully qualified name of a Well-Known SID.
1168
1169       Since some utilities allow to modify SID based access control
1170       information with the help of a name instead of using the SID directly
1171       SSSD supports to look up the SID by the name as well. To avoid
1172       collisions only the fully qualified names can be used to look up
1173       Well-Known SIDs. As a result the domain names “NULL AUTHORITY”, “WORLD
1174       AUTHORITY”, “ LOCAL AUTHORITY”, “CREATOR AUTHORITY”, “NT AUTHORITY” and
1175       “BUILTIN” should not be used as domain names in sssd.conf.
1176

EXAMPLE

1178       The following example assumes that SSSD is correctly configured and
1179       example.com is one of the domains in the [sssd] section. This example
1180       shows only the AD provider-specific options.
1181
1182           [domain/EXAMPLE]
1183           id_provider = ad
1184           auth_provider = ad
1185           access_provider = ad
1186           chpass_provider = ad
1187
1188           ad_server = dc1.example.com
1189           ad_hostname = client.example.com
1190           ad_domain = example.com
1191
1192

NOTES

1194       The AD access control provider checks if the account is expired. It has
1195       the same effect as the following configuration of the LDAP provider:
1196
1197           access_provider = ldap
1198           ldap_access_order = expire
1199           ldap_account_expire_policy = ad
1200
1201       However, unless the “ad” access control provider is explicitly
1202       configured, the default access provider is “permit”. Please note that
1203       if you configure an access provider other than “ad”, you need to set
1204       all the connection parameters (such as LDAP URIs and encryption
1205       details) manually.
1206
1207       When the autofs provider is set to “ad”, the RFC2307 schema attribute
1208       mapping (nisMap, nisObject, ...) is used, because these attributes are
1209       included in the default Active Directory schema.
1210

SEE ALSO

1212       sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
1213       sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-sudo(5), sssd-session-
1214       recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8),
1215       sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
1216       sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8).  sss_rpcidmapd(5)
1217       sssd-systemtap(5)
1218

AUTHORS

1220       The SSSD upstream - https://github.com/SSSD/sssd/
1221

NOTES

1223        1. [MS-ADTS] section LDAP extensions
1224           https://msdn.microsoft.com/en-us/library/cc223367.aspx
1225
1226
1227
1228SSSD                              07/04/2022                        SSSD-AD(5)
Impressum