1SSSD-IPA(5) File Formats and Conventions SSSD-IPA(5)
2
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 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 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 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 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 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 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 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 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 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 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 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 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 Default: false
79 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 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 Default: 1200 (seconds)
90 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 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 Default: Use the IP addresses of the interface which is used for
102 IPA LDAP connection
103 Example: dyndns_iface = em1, vnet1, vnet2
105 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 Default: GSS-TSIG
112 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 Default: Same as dyndns_auth
119 ipa_enable_dns_sites (boolean)
121 Enables DNS sites - location based service discovery.
122 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 Default: false
133 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 Default: 0 (disabled)
141 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 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 Default: False (disabled)
152 dyndns_force_tcp (bool)
154 Whether the nsupdate utility should default to using TCP for
155 communicating with the DNS server.
156 Default: False (let nsupdate choose the protocol)
158 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 Setting this option makes sense for environments where the DNS
164 server is different from the identity server.
165 Please note that this option will be only used in fallback attempt
167 when previous attempt using autodetected settings failed.
168 Default: None (let nsupdate choose the server)
170 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 Default: true
177 ipa_deskprofile_search_base (string)
179 Optional. Use the given string as search base for Desktop Profile
180 related objects.
181 Default: Use base DN
183 ipa_hbac_search_base (string)
185 Optional. Use the given string as search base for HBAC related
186 objects.
187 Default: Use base DN
189 ipa_host_search_base (string)
191 Deprecated. Use ldap_host_search_base instead.
192 ipa_selinux_search_base (string)
194 Optional. Use the given string as search base for SELinux user
195 maps.
196 See “ldap_search_base” for information about configuring multiple
198 search bases.
199 Default: the value of ldap_search_base
201 ipa_subdomains_search_base (string)
203 Optional. Use the given string as search base for trusted domains.
204 See “ldap_search_base” for information about configuring multiple
206 search bases.
207 Default: the value of cn=trusts,%basedn
209 ipa_master_domain_search_base (string)
211 Optional. Use the given string as search base for master domain
212 object.
213 See “ldap_search_base” for information about configuring multiple
215 search bases.
216 Default: the value of cn=ad,cn=etc,%basedn
218 ipa_views_search_base (string)
220 Optional. Use the given string as search base for views containers.
221 See “ldap_search_base” for information about configuring multiple
223 search bases.
224 Default: the value of cn=views,cn=accounts,%basedn
226 krb5_realm (string)
228 The name of the Kerberos realm. This is optional and defaults to
229 the value of “ipa_domain”.
230 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 krb5_confd_path (string)
235 Absolute path of a directory where SSSD should place Kerberos
236 configuration snippets.
237 To disable the creation of the configuration snippets set the
239 parameter to 'none'.
240 Default: not set (krb5.include.d subdirectory of SSSD's pubconf
242 directory)
243 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 Default: 5 (seconds)
251 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 Default: 60 (minutes)
258 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 Default: 5 (seconds)
265 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 Default: 5 (seconds)
272 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 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 NOTE: There are currently some assumptions that must be met when
282 SSSD is running on an IPA server.
283 • 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 • The “full_name_format” option must not be tweaked to only print
289 short names for users from trusted domains.
290 Default: false
292 ipa_automount_location (string)
294 The automounter location this IPA client will be using
295 Default: The location named "default"
297 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 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 ipa_view_class (string)
311 Objectclass of the view container.
312 Default: nsContainer
314 ipa_view_name (string)
316 Name of the attribute holding the name of the view.
317 Default: cn
319 ipa_override_object_class (string)
321 Objectclass of the override objects.
322 Default: ipaOverrideAnchor
324 ipa_anchor_uuid (string)
326 Name of the attribute containing the reference to the original
327 object in a remote domain.
328 Default: ipaAnchorUUID
330 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 User overrides can contain attributes given by
336 • ldap_user_name
338 • ldap_user_uid_number
340 • ldap_user_gid_number
342 • ldap_user_gecos
344 • ldap_user_home_directory
346 • ldap_user_shell
348 • ldap_user_ssh_public_key
350 Default: ipaUserOverride
352 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 Group overrides can contain attributes given by
359 • ldap_group_name
361 • ldap_group_gid_number
363 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 KRB5 Provider
372 • krb5_validate = true
373 • krb5_use_fast = try
375 • krb5_canonicalize = true
377 LDAP Provider - General
379 • ldap_schema = ipa_v1
380 • ldap_force_upper_case_realm = true
382 • ldap_sasl_mech = GSSAPI
384 • ldap_sasl_minssf = 56
386 • ldap_account_expire_policy = ipa
388 • ldap_use_tokengroups = true
390 LDAP Provider - User options
392 • ldap_user_member_of = memberOf
393 • ldap_user_uuid = ipaUniqueID
395 • ldap_user_ssh_public_key = ipaSshPubKey
397 • ldap_user_auth_type = ipaUserAuthType
399 LDAP Provider - Group options
401 • ldap_group_object_class = ipaUserGroup
402 • ldap_group_object_class_alt = posixGroup
404 • ldap_group_member = member
406 • ldap_group_uuid = ipaUniqueID
408 • ldap_group_objectsid = ipaNTSecurityIdentifier
410 • ldap_group_external_member = ipaExternalMember
412
414 The IPA subdomains provider behaves slightly differently if it is
415 configured explicitly or implicitly.
416 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 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 [domain/ipa.domain.com/ad.domain.com]
437 ad_server = dc.ad.domain.com
438 For more details, see the sssd.conf(5) manual page.
440 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 OPTIONS TUNABLE ON IPA MASTERS
446 The following options can be set in a subdomain section on an IPA
447 master:
448 • ad_server
450 • ad_backup_server
452 • ad_site
454 • ldap_search_base
456 • ldap_user_search_base
458 • ldap_group_search_base
460 • use_fully_qualified_names
462 OPTIONS TUNABLE ON IPA CLIENTS
465 The following options can be set in a subdomain section on an IPA
466 client:
467 • ad_server
469 • ad_site
471 Note that if both options are set, only “ad_server” is evaluated.
473 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 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 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 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 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 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 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 This section lists the available tunables. Please refer to their
531 description in the sssd.conf(5), manual page.
532 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 Default: 1000
538 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 Default: 3
545 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 Default: 6
552 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 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 The domain name
575 Please refer to the “dns_discovery_domain” parameter in the
576 sssd.conf(5) manual page for more details.
577 The protocol
579 The queries usually specify _tcp as the protocol. Exceptions are
580 documented in respective option description.
581 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 [domain/example.com]
592 id_provider = ipa
593 ipa_server = ipaserver.example.com
594 ipa_hostname = myhost.example.com
595
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/
607SSSD 12/09/2022 SSSD-IPA(5)