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 ipa_enable_dns_sites (boolean)
114 Enables DNS sites - location based service discovery.
115 If true and service discovery (see Service Discovery paragraph at
117 the bottom of the man page) is enabled, then the SSSD will first
118 attempt location based discovery using a query that contains
119 "_location.hostname.example.com" and then fall back to traditional
120 SRV discovery. If the location based discovery succeeds, the IPA
121 servers located with the location based discovery are treated as
122 primary servers and the IPA servers located using the traditional
123 SRV discovery are used as back up servers
124 Default: false
126 dyndns_refresh_interval (integer)
128 How often should the back end perform periodic DNS update in
129 addition to the automatic update performed when the back end goes
130 online. This option is optional and applicable only when
131 dyndns_update is true.
132 Default: 0 (disabled)
134 dyndns_update_ptr (bool)
136 Whether the PTR record should also be explicitly updated when
137 updating the client's DNS records. Applicable only when
138 dyndns_update is true.
139 This option should be False in most IPA deployments as the IPA
141 server generates the PTR records automatically when forward records
142 are changed.
143 Default: False (disabled)
145 dyndns_force_tcp (bool)
147 Whether the nsupdate utility should default to using TCP for
148 communicating with the DNS server.
149 Default: False (let nsupdate choose the protocol)
151 dyndns_server (string)
153 The DNS server to use when performing a DNS update. In most setups,
154 it's recommended to leave this option unset.
155 Setting this option makes sense for environments where the DNS
157 server is different from the identity server.
158 Please note that this option will be only used in fallback attempt
160 when previous attempt using autodetected settings failed.
161 Default: None (let nsupdate choose the server)
163 dyndns_update_per_family (boolean)
165 DNS update is by default performed in two steps - IPv4 update and
166 then IPv6 update. In some cases it might be desirable to perform
167 IPv4 and IPv6 update in single step.
168 Default: true
170 ipa_deskprofile_search_base (string)
172 Optional. Use the given string as search base for Desktop Profile
173 related objects.
174 Default: Use base DN
176 ipa_hbac_search_base (string)
178 Optional. Use the given string as search base for HBAC related
179 objects.
180 Default: Use base DN
182 ipa_host_search_base (string)
184 Deprecated. Use ldap_host_search_base instead.
185 ipa_selinux_search_base (string)
187 Optional. Use the given string as search base for SELinux user
188 maps.
189 See “ldap_search_base” for information about configuring multiple
191 search bases.
192 Default: the value of ldap_search_base
194 ipa_subdomains_search_base (string)
196 Optional. Use the given string as search base for trusted domains.
197 See “ldap_search_base” for information about configuring multiple
199 search bases.
200 Default: the value of cn=trusts,%basedn
202 ipa_master_domain_search_base (string)
204 Optional. Use the given string as search base for master domain
205 object.
206 See “ldap_search_base” for information about configuring multiple
208 search bases.
209 Default: the value of cn=ad,cn=etc,%basedn
211 ipa_views_search_base (string)
213 Optional. Use the given string as search base for views containers.
214 See “ldap_search_base” for information about configuring multiple
216 search bases.
217 Default: the value of cn=views,cn=accounts,%basedn
219 krb5_realm (string)
221 The name of the Kerberos realm. This is optional and defaults to
222 the value of “ipa_domain”.
223 The name of the Kerberos realm has a special meaning in IPA - it is
225 converted into the base DN to use for performing LDAP operations.
226 krb5_confd_path (string)
228 Absolute path of a directory where SSSD should place Kerberos
229 configuration snippets.
230 To disable the creation of the configuration snippets set the
232 parameter to 'none'.
233 Default: not set (krb5.include.d subdirectory of SSSD's pubconf
235 directory)
236 ipa_deskprofile_refresh (integer)
238 The amount of time between lookups of the Desktop Profile rules
239 against the IPA server. This will reduce the latency and load on
240 the IPA server if there are many desktop profiles requests made in
241 a short period.
242 Default: 5 (seconds)
244 ipa_deskprofile_request_interval (integer)
246 The amount of time between lookups of the Desktop Profile rules
247 against the IPA server in case the last request did not return any
248 rule.
249 Default: 60 (minutes)
251 ipa_hbac_refresh (integer)
253 The amount of time between lookups of the HBAC rules against the
254 IPA server. This will reduce the latency and load on the IPA server
255 if there are many access-control requests made in a short period.
256 Default: 5 (seconds)
258 ipa_hbac_selinux (integer)
260 The amount of time between lookups of the SELinux maps against the
261 IPA server. This will reduce the latency and load on the IPA server
262 if there are many user login requests made in a short period.
263 Default: 5 (seconds)
265 ipa_server_mode (boolean)
267 This option will be set by the IPA installer (ipa-server-install)
268 automatically and denotes if SSSD is running on an IPA server or
269 not.
270 On an IPA server SSSD will lookup users and groups from trusted
272 domains directly while on a client it will ask an IPA server.
273 NOTE: There are currently some assumptions that must be met when
275 SSSD is running on an IPA server.
276 · The “ipa_server” option must be configured to point to the IPA
278 server itself. This is already the default set by the IPA
279 installer, so no manual change is required.
280 · The “full_name_format” option must not be tweaked to only print
282 short names for users from trusted domains.
283 Default: false
285 ipa_automount_location (string)
287 The automounter location this IPA client will be using
288 Default: The location named "default"
290 Please note that the automounter only reads the master map on
292 startup, so if any autofs-related changes are made to the
293 sssd.conf, you typically also need to restart the automounter
294 daemon after restarting the SSSD.
295 VIEWS AND OVERRIDES
297 SSSD can handle views and overrides which are offered by FreeIPA 4.1
298 and later version. Since all paths and objectclasses are fixed on the
299 server side there is basically no need to configure anything. For
300 completeness the related options are listed here with their default
301 values.
302 ipa_view_class (string)
304 Objectclass of the view container.
305 Default: nsContainer
307 ipa_view_name (string)
309 Name of the attribute holding the name of the view.
310 Default: cn
312 ipa_override_object_class (string)
314 Objectclass of the override objects.
315 Default: ipaOverrideAnchor
317 ipa_anchor_uuid (string)
319 Name of the attribute containing the reference to the original
320 object in a remote domain.
321 Default: ipaAnchorUUID
323 ipa_user_override_object_class (string)
325 Name of the objectclass for user overrides. It is used to determine
326 if the found override object is related to a user or a group.
327 User overrides can contain attributes given by
329 · ldap_user_name
331 · ldap_user_uid_number
333 · ldap_user_gid_number
335 · ldap_user_gecos
337 · ldap_user_home_directory
339 · ldap_user_shell
341 · ldap_user_ssh_public_key
343 Default: ipaUserOverride
345 ipa_group_override_object_class (string)
347 Name of the objectclass for group overrides. It is used to
348 determine if the found override object is related to a user or a
349 group.
350 Group overrides can contain attributes given by
352 · ldap_group_name
354 · ldap_group_gid_number
356 Default: ipaGroupOverride
358
360 Certain option defaults do not match their respective backend provider
361 defaults, these option names and IPA provider-specific defaults are
362 listed below:
363 KRB5 Provider
365 · krb5_validate = true
366 · krb5_use_fast = try
368 · krb5_canonicalize = true
370 LDAP Provider - General
372 · ldap_schema = ipa_v1
373 · ldap_force_upper_case_realm = true
375 · ldap_sasl_mech = GSSAPI
377 · ldap_sasl_minssf = 56
379 · ldap_account_expire_policy = ipa
381 · ldap_use_tokengroups = true
383 LDAP Provider - User options
385 · ldap_user_member_of = memberOf
386 · ldap_user_uuid = ipaUniqueID
388 · ldap_user_ssh_public_key = ipaSshPubKey
390 · ldap_user_auth_type = ipaUserAuthType
392 LDAP Provider - Group options
394 · ldap_group_object_class = ipaUserGroup
395 · ldap_group_object_class_alt = posixGroup
397 · ldap_group_member = member
399 · ldap_group_uuid = ipaUniqueID
401 · ldap_group_objectsid = ipaNTSecurityIdentifier
403 · ldap_group_external_member = ipaExternalMember
405
407 The IPA subdomains provider behaves slightly differently if it is
408 configured explicitly or implicitly.
409 If the option 'subdomains_provider = ipa' is found in the domain
411 section of sssd.conf, the IPA subdomains provider is configured
412 explicitly, and all subdomain requests are sent to the IPA server if
413 necessary.
414 If the option 'subdomains_provider' is not set in the domain section of
416 sssd.conf but there is the option 'id_provider = ipa', the IPA
417 subdomains provider is configured implicitly. In this case, if a
418 subdomain request fails and indicates that the server does not support
419 subdomains, i.e. is not configured for trusts, the IPA subdomains
420 provider is disabled. After an hour or after the IPA provider goes
421 online, the subdomains provider is enabled again.
422
424 Some configuration options can be also set for a trusted domain. A
425 trusted domain configuration can either be done using a subsection, for
426 example:
427 [domain/ipa.domain.com/ad.domain.com]
429 ad_server = dc.ad.domain.com
430 In addition, some options can be set in the parent domain and inherited
432 by the trusted domain using the “subdomain_inherit” option. For more
433 details, see the sssd.conf(5) manual page.
434 Different configuration options are tunable for a trusted domain
436 depending on whether you are configuring SSSD on an IPA server or an
437 IPA client.
438 OPTIONS TUNABLE ON IPA MASTERS
440 The following options can be set in a subdomain section on an IPA
441 master:
442 · ad_server
444 · ad_backup_server
446 · ad_site
448 · ldap_search_base
450 · ldap_user_search_base
452 · ldap_group_search_base
454 · use_fully_qualified_names
456 OPTIONS TUNABLE ON IPA CLIENTS
459 The following options can be set in a subdomain section on an IPA
460 client:
461 · ad_server
463 · ad_site
465 Note that if both options are set, only “ad_server” is evaluated.
467 Since any request for a user or a group identity from a trusted domain
469 triggered from an IPA client is resolved by the IPA server, the
470 “ad_server” and “ad_site” options only affect which AD DC will the
471 authentication be performed against. In particular, the addresses
472 resolved from these lists will be written to “kdcinfo” files read by
473 the Kerberos locator plugin. Please refer to the
474 sssd_krb5_locator_plugin(8) manual page for more details on the
475 Kerberos locator plugin.
476
478 The failover feature allows back ends to automatically switch to a
479 different server if the current server fails.
480 Failover Syntax
482 The list of servers is given as a comma-separated list; any number of
483 spaces is allowed around the comma. The servers are listed in order of
484 preference. The list can contain any number of servers.
485 For each failover-enabled config option, two variants exist: primary
487 and backup. The idea is that servers in the primary list are preferred
488 and backup servers are only searched if no primary servers can be
489 reached. If a backup server is selected, a timeout of 31 seconds is
490 set. After this timeout SSSD will periodically try to reconnect to one
491 of the primary servers. If it succeeds, it will replace the current
492 active (backup) server.
493 The Failover Mechanism
495 The failover mechanism distinguishes between a machine and a service.
496 The back end first tries to resolve the hostname of a given machine; if
497 this resolution attempt fails, the machine is considered offline. No
498 further attempts are made to connect to this machine for any other
499 service. If the resolution attempt succeeds, the back end tries to
500 connect to a service on this machine. If the service connection attempt
501 fails, then only this particular service is considered offline and the
502 back end automatically switches over to the next service. The machine
503 is still considered online and might still be tried for another
504 service.
505 Further connection attempts are made to machines or services marked as
507 offline after a specified period of time; this is currently hard coded
508 to 30 seconds.
509 If there are no more machines to try, the back end as a whole switches
511 to offline mode, and then attempts to reconnect every 30 seconds.
512 Failover time outs and tuning
514 Resolving a server to connect to can be as simple as running a single
515 DNS query or can involve several steps, such as finding the correct
516 site or trying out multiple host names in case some of the configured
517 servers are not reachable. The more complex scenarios can take some
518 time and SSSD needs to balance between providing enough time to finish
519 the resolution process but on the other hand, not trying for too long
520 before falling back to offline mode. If the SSSD debug logs show that
521 the server resolution is timing out before a live server is contacted,
522 you can consider changing the time outs.
523 This section lists the available tunables. Please refer to their
525 description in the sssd.conf(5), manual page.
526 dns_resolver_server_timeout
528 Time in milliseconds that sets how long would SSSD talk to a single
529 DNS server before trying next one.
530 Default: 1000
532 dns_resolver_op_timeout
534 Time in seconds to tell how long would SSSD try to resolve single
535 DNS query (e.g. resolution of a hostname or an SRV record) before
536 trying the next hostname or discovery domain.
537 Default: 2
539 dns_resolver_timeout
541 How long would SSSD try to resolve a failover service. This service
542 resolution internally might include several steps, such as
543 resolving DNS SRV queries or locating the site.
544 Default: 4
546 For LDAP-based providers, the resolve operation is performed as part of
548 an LDAP connection operation. Therefore, also the “ldap_opt_timeout>”
549 timeout should be set to a larger value than “dns_resolver_timeout”
550 which in turn should be set to a larger value than
551 “dns_resolver_op_timeout” which should be larger than
552 “dns_resolver_server_timeout”.
553
555 The service discovery feature allows back ends to automatically find
556 the appropriate servers to connect to using a special DNS query. This
557 feature is not supported for backup servers.
558 Configuration
560 If no servers are specified, the back end automatically uses service
561 discovery to try to find a server. Optionally, the user may choose to
562 use both fixed server addresses and service discovery by inserting a
563 special keyword, “_srv_”, in the list of servers. The order of
564 preference is maintained. This feature is useful if, for example, the
565 user prefers to use service discovery whenever possible, and fall back
566 to a specific server when no servers can be discovered using DNS.
567 The domain name
569 Please refer to the “dns_discovery_domain” parameter in the
570 sssd.conf(5) manual page for more details.
571 The protocol
573 The queries usually specify _tcp as the protocol. Exceptions are
574 documented in respective option description.
575 See Also
577 For more information on the service discovery mechanism, refer to RFC
578 2782.
579
581 The following example assumes that SSSD is correctly configured and
582 example.com is one of the domains in the [sssd] section. This examples
583 shows only the ipa provider-specific options.
584 [domain/example.com]
586 id_provider = ipa
587 ipa_server = ipaserver.example.com
588 ipa_hostname = myhost.example.com
589
592 sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
593 sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-sudo(5), sssd-session-
594 recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8),
595 sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
596 sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5)
597 sssd-systemtap(5)
598
600 The SSSD upstream - https://pagure.io/SSSD/sssd/
601SSSD 02/26/2020 SSSD-IPA(5)