1SSSD-IPA(5) File Formats and Conventions SSSD-IPA(5)
2
3
4
6 sssd-ipa - SSSD IPA provider
7
9 This manual page describes the configuration of the IPA 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 IPA provider is a back end used to connect to an IPA server. (Refer
14 to the freeipa.org web site for information about IPA servers.) This
15 provider requires that the machine be joined to the IPA domain;
16 configuration is almost entirely self-discovered and obtained directly
17 from the server.
18
19 The IPA provider enables SSSD to use the sssd-ldap(5) identity provider
20 and the sssd-krb5(5) authentication provider with optimizations for IPA
21 environments. The IPA provider accepts the same options used by the
22 sssd-ldap and sssd-krb5 providers with some exceptions. However, it is
23 neither necessary nor recommended to set these options.
24
25 The IPA provider primarily copies the traditional ldap and krb5
26 provider default options with some exceptions, the differences are
27 listed in the “MODIFIED DEFAULT OPTIONS” section.
28
29 As an access provider, the IPA provider uses HBAC (host-based access
30 control) rules. Please refer to freeipa.org for more information about
31 HBAC. No configuration of access provider is required on the client
32 side.
33
34 If “auth_provider=ipa” or “access_provider=ipa” is configured in
35 sssd.conf then the id_provider must also be set to “ipa”.
36
37 The IPA provider will use the PAC responder if the Kerberos tickets of
38 users from trusted realms contain a PAC. To make configuration easier
39 the PAC responder is started automatically if the IPA ID provider is
40 configured.
41
43 Refer to the section “DOMAIN SECTIONS” of the sssd.conf(5) manual page
44 for details on the configuration of an SSSD domain.
45
46 ipa_domain (string)
47 Specifies the name of the IPA domain. This is optional. If not
48 provided, the configuration domain name is used.
49
50 ipa_server, ipa_backup_server (string)
51 The comma-separated list of IP addresses or hostnames of the IPA
52 servers to which SSSD should connect in the order of preference.
53 For more information on failover and server redundancy, see the
54 “FAILOVER” section. This is optional if autodiscovery is enabled.
55 For more information on service discovery, refer to the “SERVICE
56 DISCOVERY” section.
57
58 ipa_hostname (string)
59 Optional. May be set on machines where the hostname(5) does not
60 reflect the fully qualified name used in the IPA domain to identify
61 this host. The hostname must be fully qualified.
62
63 dyndns_update (boolean)
64 Optional. This option tells SSSD to automatically update the DNS
65 server built into FreeIPA with the IP address of this client. The
66 update is secured using GSS-TSIG. The IP address of the IPA LDAP
67 connection is used for the updates, if it is not otherwise
68 specified by using the “dyndns_iface” option.
69
70 NOTE: On older systems (such as RHEL 5), for this behavior to work
71 reliably, the default Kerberos realm must be set properly in
72 /etc/krb5.conf
73
74 NOTE: While it is still possible to use the old ipa_dyndns_update
75 option, users should migrate to using dyndns_update in their config
76 file.
77
78 Default: false
79
80 dyndns_ttl (integer)
81 The TTL to apply to the client DNS record when updating it. If
82 dyndns_update is false this has no effect. This will override the
83 TTL serverside if set by an administrator.
84
85 NOTE: While it is still possible to use the old ipa_dyndns_ttl
86 option, users should migrate to using dyndns_ttl in their config
87 file.
88
89 Default: 1200 (seconds)
90
91 dyndns_iface (string)
92 Optional. Applicable only when dyndns_update is true. Choose the
93 interface or a list of interfaces whose IP addresses should be used
94 for dynamic DNS updates. Special value “*” implies that IPs from
95 all interfaces should be used.
96
97 NOTE: While it is still possible to use the old ipa_dyndns_iface
98 option, users should migrate to using dyndns_iface in their config
99 file.
100
101 Default: Use the IP addresses of the interface which is used for
102 IPA LDAP connection
103
104 Example: dyndns_iface = em1, vnet1, vnet2
105
106 dyndns_auth (string)
107 Whether the nsupdate utility should use GSS-TSIG authentication for
108 secure updates with the DNS server, insecure updates can be sent by
109 setting this option to 'none'.
110
111 Default: GSS-TSIG
112
113 dyndns_auth_ptr (string)
114 Whether the nsupdate utility should use GSS-TSIG authentication for
115 secure PTR updates with the DNS server, insecure updates can be
116 sent by setting this option to 'none'.
117
118 Default: Same as dyndns_auth
119
120 ipa_enable_dns_sites (boolean)
121 Enables DNS sites - location based service discovery.
122
123 If true and service discovery (see Service Discovery paragraph at
124 the bottom of the man page) is enabled, then the SSSD will first
125 attempt location based discovery using a query that contains
126 "_location.hostname.example.com" and then fall back to traditional
127 SRV discovery. If the location based discovery succeeds, the IPA
128 servers located with the location based discovery are treated as
129 primary servers and the IPA servers located using the traditional
130 SRV discovery are used as back up servers
131
132 Default: false
133
134 dyndns_refresh_interval (integer)
135 How often should the back end perform periodic DNS update in
136 addition to the automatic update performed when the back end goes
137 online. This option is optional and applicable only when
138 dyndns_update is true.
139
140 Default: 0 (disabled)
141
142 dyndns_update_ptr (bool)
143 Whether the PTR record should also be explicitly updated when
144 updating the client's DNS records. Applicable only when
145 dyndns_update is true.
146
147 This option should be False in most IPA deployments as the IPA
148 server generates the PTR records automatically when forward records
149 are changed.
150
151 Default: False (disabled)
152
153 dyndns_force_tcp (bool)
154 Whether the nsupdate utility should default to using TCP for
155 communicating with the DNS server.
156
157 Default: False (let nsupdate choose the protocol)
158
159 dyndns_server (string)
160 The DNS server to use when performing a DNS update. In most setups,
161 it's recommended to leave this option unset.
162
163 Setting this option makes sense for environments where the DNS
164 server is different from the identity server.
165
166 Please note that this option will be only used in fallback attempt
167 when previous attempt using autodetected settings failed.
168
169 Default: None (let nsupdate choose the server)
170
171 dyndns_update_per_family (boolean)
172 DNS update is by default performed in two steps - IPv4 update and
173 then IPv6 update. In some cases it might be desirable to perform
174 IPv4 and IPv6 update in single step.
175
176 Default: true
177
178 ipa_deskprofile_search_base (string)
179 Optional. Use the given string as search base for Desktop Profile
180 related objects.
181
182 Default: Use base DN
183
184 ipa_hbac_search_base (string)
185 Optional. Use the given string as search base for HBAC related
186 objects.
187
188 Default: Use base DN
189
190 ipa_host_search_base (string)
191 Deprecated. Use ldap_host_search_base instead.
192
193 ipa_selinux_search_base (string)
194 Optional. Use the given string as search base for SELinux user
195 maps.
196
197 See “ldap_search_base” for information about configuring multiple
198 search bases.
199
200 Default: the value of ldap_search_base
201
202 ipa_subdomains_search_base (string)
203 Optional. Use the given string as search base for trusted domains.
204
205 See “ldap_search_base” for information about configuring multiple
206 search bases.
207
208 Default: the value of cn=trusts,%basedn
209
210 ipa_master_domain_search_base (string)
211 Optional. Use the given string as search base for master domain
212 object.
213
214 See “ldap_search_base” for information about configuring multiple
215 search bases.
216
217 Default: the value of cn=ad,cn=etc,%basedn
218
219 ipa_views_search_base (string)
220 Optional. Use the given string as search base for views containers.
221
222 See “ldap_search_base” for information about configuring multiple
223 search bases.
224
225 Default: the value of cn=views,cn=accounts,%basedn
226
227 krb5_realm (string)
228 The name of the Kerberos realm. This is optional and defaults to
229 the value of “ipa_domain”.
230
231 The name of the Kerberos realm has a special meaning in IPA - it is
232 converted into the base DN to use for performing LDAP operations.
233
234 krb5_confd_path (string)
235 Absolute path of a directory where SSSD should place Kerberos
236 configuration snippets.
237
238 To disable the creation of the configuration snippets set the
239 parameter to 'none'.
240
241 Default: not set (krb5.include.d subdirectory of SSSD's pubconf
242 directory)
243
244 ipa_deskprofile_refresh (integer)
245 The amount of time between lookups of the Desktop Profile rules
246 against the IPA server. This will reduce the latency and load on
247 the IPA server if there are many desktop profiles requests made in
248 a short period.
249
250 Default: 5 (seconds)
251
252 ipa_deskprofile_request_interval (integer)
253 The amount of time between lookups of the Desktop Profile rules
254 against the IPA server in case the last request did not return any
255 rule.
256
257 Default: 60 (minutes)
258
259 ipa_hbac_refresh (integer)
260 The amount of time between lookups of the HBAC rules against the
261 IPA server. This will reduce the latency and load on the IPA server
262 if there are many access-control requests made in a short period.
263
264 Default: 5 (seconds)
265
266 ipa_hbac_selinux (integer)
267 The amount of time between lookups of the SELinux maps against the
268 IPA server. This will reduce the latency and load on the IPA server
269 if there are many user login requests made in a short period.
270
271 Default: 5 (seconds)
272
273 ipa_server_mode (boolean)
274 This option will be set by the IPA installer (ipa-server-install)
275 automatically and denotes if SSSD is running on an IPA server or
276 not.
277
278 On an IPA server SSSD will lookup users and groups from trusted
279 domains directly while on a client it will ask an IPA server.
280
281 NOTE: There are currently some assumptions that must be met when
282 SSSD is running on an IPA server.
283
284 · The “ipa_server” option must be configured to point to the IPA
285 server itself. This is already the default set by the IPA
286 installer, so no manual change is required.
287
288 · The “full_name_format” option must not be tweaked to only print
289 short names for users from trusted domains.
290
291 Default: false
292
293 ipa_automount_location (string)
294 The automounter location this IPA client will be using
295
296 Default: The location named "default"
297
298 Please note that the automounter only reads the master map on
299 startup, so if any autofs-related changes are made to the
300 sssd.conf, you typically also need to restart the automounter
301 daemon after restarting the SSSD.
302
303 VIEWS AND OVERRIDES
304 SSSD can handle views and overrides which are offered by FreeIPA 4.1
305 and later version. Since all paths and objectclasses are fixed on the
306 server side there is basically no need to configure anything. For
307 completeness the related options are listed here with their default
308 values.
309
310 ipa_view_class (string)
311 Objectclass of the view container.
312
313 Default: nsContainer
314
315 ipa_view_name (string)
316 Name of the attribute holding the name of the view.
317
318 Default: cn
319
320 ipa_override_object_class (string)
321 Objectclass of the override objects.
322
323 Default: ipaOverrideAnchor
324
325 ipa_anchor_uuid (string)
326 Name of the attribute containing the reference to the original
327 object in a remote domain.
328
329 Default: ipaAnchorUUID
330
331 ipa_user_override_object_class (string)
332 Name of the objectclass for user overrides. It is used to determine
333 if the found override object is related to a user or a group.
334
335 User overrides can contain attributes given by
336
337 · ldap_user_name
338
339 · ldap_user_uid_number
340
341 · ldap_user_gid_number
342
343 · ldap_user_gecos
344
345 · ldap_user_home_directory
346
347 · ldap_user_shell
348
349 · ldap_user_ssh_public_key
350
351 Default: ipaUserOverride
352
353 ipa_group_override_object_class (string)
354 Name of the objectclass for group overrides. It is used to
355 determine if the found override object is related to a user or a
356 group.
357
358 Group overrides can contain attributes given by
359
360 · ldap_group_name
361
362 · ldap_group_gid_number
363
364 Default: ipaGroupOverride
365
367 Certain option defaults do not match their respective backend provider
368 defaults, these option names and IPA provider-specific defaults are
369 listed below:
370
371 KRB5 Provider
372 · krb5_validate = true
373
374 · krb5_use_fast = try
375
376 · krb5_canonicalize = true
377
378 LDAP Provider - General
379 · ldap_schema = ipa_v1
380
381 · ldap_force_upper_case_realm = true
382
383 · ldap_sasl_mech = GSSAPI
384
385 · ldap_sasl_minssf = 56
386
387 · ldap_account_expire_policy = ipa
388
389 · ldap_use_tokengroups = true
390
391 LDAP Provider - User options
392 · ldap_user_member_of = memberOf
393
394 · ldap_user_uuid = ipaUniqueID
395
396 · ldap_user_ssh_public_key = ipaSshPubKey
397
398 · ldap_user_auth_type = ipaUserAuthType
399
400 LDAP Provider - Group options
401 · ldap_group_object_class = ipaUserGroup
402
403 · ldap_group_object_class_alt = posixGroup
404
405 · ldap_group_member = member
406
407 · ldap_group_uuid = ipaUniqueID
408
409 · ldap_group_objectsid = ipaNTSecurityIdentifier
410
411 · ldap_group_external_member = ipaExternalMember
412
414 The IPA subdomains provider behaves slightly differently if it is
415 configured explicitly or implicitly.
416
417 If the option 'subdomains_provider = ipa' is found in the domain
418 section of sssd.conf, the IPA subdomains provider is configured
419 explicitly, and all subdomain requests are sent to the IPA server if
420 necessary.
421
422 If the option 'subdomains_provider' is not set in the domain section of
423 sssd.conf but there is the option 'id_provider = ipa', the IPA
424 subdomains provider is configured implicitly. In this case, if a
425 subdomain request fails and indicates that the server does not support
426 subdomains, i.e. is not configured for trusts, the IPA subdomains
427 provider is disabled. After an hour or after the IPA provider goes
428 online, the subdomains provider is enabled again.
429
431 Some configuration options can also be set for a trusted domain. A
432 trusted domain configuration can be set using the trusted domain
433 subsection as shown in the example below. Alternatively, the
434 “subdomain_inherit” option can be used in the parent domain.
435
436 [domain/ipa.domain.com/ad.domain.com]
437 ad_server = dc.ad.domain.com
438
439 For more details, see the sssd.conf(5) manual page.
440
441 Different configuration options are tunable for a trusted domain
442 depending on whether you are configuring SSSD on an IPA server or an
443 IPA client.
444
445 OPTIONS TUNABLE ON IPA MASTERS
446 The following options can be set in a subdomain section on an IPA
447 master:
448
449 · ad_server
450
451 · ad_backup_server
452
453 · ad_site
454
455 · ldap_search_base
456
457 · ldap_user_search_base
458
459 · ldap_group_search_base
460
461 · use_fully_qualified_names
462
463
464 OPTIONS TUNABLE ON IPA CLIENTS
465 The following options can be set in a subdomain section on an IPA
466 client:
467
468 · ad_server
469
470 · ad_site
471
472 Note that if both options are set, only “ad_server” is evaluated.
473
474 Since any request for a user or a group identity from a trusted domain
475 triggered from an IPA client is resolved by the IPA server, the
476 “ad_server” and “ad_site” options only affect which AD DC will the
477 authentication be performed against. In particular, the addresses
478 resolved from these lists will be written to “kdcinfo” files read by
479 the Kerberos locator plugin. Please refer to the
480 sssd_krb5_locator_plugin(8) manual page for more details on the
481 Kerberos locator plugin.
482
484 The failover feature allows back ends to automatically switch to a
485 different server if the current server fails.
486
487 Failover Syntax
488 The list of servers is given as a comma-separated list; any number of
489 spaces is allowed around the comma. The servers are listed in order of
490 preference. The list can contain any number of servers.
491
492 For each failover-enabled config option, two variants exist: primary
493 and backup. The idea is that servers in the primary list are preferred
494 and backup servers are only searched if no primary servers can be
495 reached. If a backup server is selected, a timeout of 31 seconds is
496 set. After this timeout SSSD will periodically try to reconnect to one
497 of the primary servers. If it succeeds, it will replace the current
498 active (backup) server.
499
500 The Failover Mechanism
501 The failover mechanism distinguishes between a machine and a service.
502 The back end first tries to resolve the hostname of a given machine; if
503 this resolution attempt fails, the machine is considered offline. No
504 further attempts are made to connect to this machine for any other
505 service. If the resolution attempt succeeds, the back end tries to
506 connect to a service on this machine. If the service connection attempt
507 fails, then only this particular service is considered offline and the
508 back end automatically switches over to the next service. The machine
509 is still considered online and might still be tried for another
510 service.
511
512 Further connection attempts are made to machines or services marked as
513 offline after a specified period of time; this is currently hard coded
514 to 30 seconds.
515
516 If there are no more machines to try, the back end as a whole switches
517 to offline mode, and then attempts to reconnect every 30 seconds.
518
519 Failover time outs and tuning
520 Resolving a server to connect to can be as simple as running a single
521 DNS query or can involve several steps, such as finding the correct
522 site or trying out multiple host names in case some of the configured
523 servers are not reachable. The more complex scenarios can take some
524 time and SSSD needs to balance between providing enough time to finish
525 the resolution process but on the other hand, not trying for too long
526 before falling back to offline mode. If the SSSD debug logs show that
527 the server resolution is timing out before a live server is contacted,
528 you can consider changing the time outs.
529
530 This section lists the available tunables. Please refer to their
531 description in the sssd.conf(5), manual page.
532
533 dns_resolver_server_timeout
534 Time in milliseconds that sets how long would SSSD talk to a single
535 DNS server before trying next one.
536
537 Default: 1000
538
539 dns_resolver_op_timeout
540 Time in seconds to tell how long would SSSD try to resolve single
541 DNS query (e.g. resolution of a hostname or an SRV record) before
542 trying the next hostname or discovery domain.
543
544 Default: 3
545
546 dns_resolver_timeout
547 How long would SSSD try to resolve a failover service. This service
548 resolution internally might include several steps, such as
549 resolving DNS SRV queries or locating the site.
550
551 Default: 6
552
553 For LDAP-based providers, the resolve operation is performed as part of
554 an LDAP connection operation. Therefore, also the “ldap_opt_timeout”
555 timeout should be set to a larger value than “dns_resolver_timeout”
556 which in turn should be set to a larger value than
557 “dns_resolver_op_timeout” which should be larger than
558 “dns_resolver_server_timeout”.
559
561 The service discovery feature allows back ends to automatically find
562 the appropriate servers to connect to using a special DNS query. This
563 feature is not supported for backup servers.
564
565 Configuration
566 If no servers are specified, the back end automatically uses service
567 discovery to try to find a server. Optionally, the user may choose to
568 use both fixed server addresses and service discovery by inserting a
569 special keyword, “_srv_”, in the list of servers. The order of
570 preference is maintained. This feature is useful if, for example, the
571 user prefers to use service discovery whenever possible, and fall back
572 to a specific server when no servers can be discovered using DNS.
573
574 The domain name
575 Please refer to the “dns_discovery_domain” parameter in the
576 sssd.conf(5) manual page for more details.
577
578 The protocol
579 The queries usually specify _tcp as the protocol. Exceptions are
580 documented in respective option description.
581
582 See Also
583 For more information on the service discovery mechanism, refer to RFC
584 2782.
585
587 The following example assumes that SSSD is correctly configured and
588 example.com is one of the domains in the [sssd] section. This examples
589 shows only the ipa provider-specific options.
590
591 [domain/example.com]
592 id_provider = ipa
593 ipa_server = ipaserver.example.com
594 ipa_hostname = myhost.example.com
595
596
598 sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
599 sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-sudo(5), sssd-session-
600 recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8),
601 sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
602 sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5)
603 sssd-systemtap(5)
604
606 The SSSD upstream - https://github.com/SSSD/sssd/
607
608
609
610SSSD 02/19/2021 SSSD-IPA(5)