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 ipa_deskprofile_search_base (string)
165 Optional. Use the given string as search base for Desktop Profile
166 related objects.
167 Default: Use base DN
169 ipa_hbac_search_base (string)
171 Optional. Use the given string as search base for HBAC related
172 objects.
173 Default: Use base DN
175 ipa_host_search_base (string)
177 Deprecated. Use ldap_host_search_base instead.
178 ipa_selinux_search_base (string)
180 Optional. Use the given string as search base for SELinux user
181 maps.
182 See “ldap_search_base” for information about configuring multiple
184 search bases.
185 Default: the value of ldap_search_base
187 ipa_subdomains_search_base (string)
189 Optional. Use the given string as search base for trusted domains.
190 See “ldap_search_base” for information about configuring multiple
192 search bases.
193 Default: the value of cn=trusts,%basedn
195 ipa_master_domain_search_base (string)
197 Optional. Use the given string as search base for master domain
198 object.
199 See “ldap_search_base” for information about configuring multiple
201 search bases.
202 Default: the value of cn=ad,cn=etc,%basedn
204 ipa_views_search_base (string)
206 Optional. Use the given string as search base for views containers.
207 See “ldap_search_base” for information about configuring multiple
209 search bases.
210 Default: the value of cn=views,cn=accounts,%basedn
212 krb5_realm (string)
214 The name of the Kerberos realm. This is optional and defaults to
215 the value of “ipa_domain”.
216 The name of the Kerberos realm has a special meaning in IPA - it is
218 converted into the base DN to use for performing LDAP operations.
219 krb5_confd_path (string)
221 Absolute path of a directory where SSSD should place Kerberos
222 configuration snippets.
223 To disable the creation of the configuration snippets set the
225 parameter to 'none'.
226 Default: not set (krb5.include.d subdirectory of SSSD's pubconf
228 directory)
229 ipa_deskprofile_refresh (integer)
231 The amount of time between lookups of the Desktop Profile rules
232 against the IPA server. This will reduce the latency and load on
233 the IPA server if there are many desktop profiles requests made in
234 a short period.
235 Default: 5 (seconds)
237 ipa_deskprofile_request_interval (integer)
239 The amount of time between lookups of the Desktop Profile rules
240 against the IPA server in case the last request did not return any
241 rule.
242 Default: 60 (minutes)
244 ipa_hbac_refresh (integer)
246 The amount of time between lookups of the HBAC rules against the
247 IPA server. This will reduce the latency and load on the IPA server
248 if there are many access-control requests made in a short period.
249 Default: 5 (seconds)
251 ipa_hbac_selinux (integer)
253 The amount of time between lookups of the SELinux maps against the
254 IPA server. This will reduce the latency and load on the IPA server
255 if there are many user login requests made in a short period.
256 Default: 5 (seconds)
258 ipa_server_mode (boolean)
260 This option will be set by the IPA installer (ipa-server-install)
261 automatically and denotes if SSSD is running on an IPA server or
262 not.
263 On an IPA server SSSD will lookup users and groups from trusted
265 domains directly while on a client it will ask an IPA server.
266 NOTE: There are currently some assumptions that must be met when
268 SSSD is running on an IPA server.
269 · The “ipa_server” option must be configured to point to the IPA
271 server itself. This is already the default set by the IPA
272 installer, so no manual change is required.
273 · The “full_name_format” option must not be tweaked to only print
275 short names for users from trusted domains.
276 Default: false
278 ipa_automount_location (string)
280 The automounter location this IPA client will be using
281 Default: The location named "default"
283 Please note that the automounter only reads the master map on
285 startup, so if any autofs-related changes are made to the
286 sssd.conf, you typically also need to restart the automounter
287 daemon after restarting the SSSD.
288 VIEWS AND OVERRIDES
290 SSSD can handle views and overrides which are offered by FreeIPA 4.1
291 and later version. Since all paths and objectclasses are fixed on the
292 server side there is basically no need to configure anything. For
293 completeness the related options are listed here with their default
294 values.
295 ipa_view_class (string)
297 Objectclass of the view container.
298 Default: nsContainer
300 ipa_view_name (string)
302 Name of the attribute holding the name of the view.
303 Default: cn
305 ipa_override_object_class (string)
307 Objectclass of the override objects.
308 Default: ipaOverrideAnchor
310 ipa_anchor_uuid (string)
312 Name of the attribute containing the reference to the original
313 object in a remote domain.
314 Default: ipaAnchorUUID
316 ipa_user_override_object_class (string)
318 Name of the objectclass for user overrides. It is used to determine
319 if the found override object is related to a user or a group.
320 User overrides can contain attributes given by
322 · ldap_user_name
324 · ldap_user_uid_number
326 · ldap_user_gid_number
328 · ldap_user_gecos
330 · ldap_user_home_directory
332 · ldap_user_shell
334 · ldap_user_ssh_public_key
336 Default: ipaUserOverride
338 ipa_group_override_object_class (string)
340 Name of the objectclass for group overrides. It is used to
341 determine if the found override object is related to a user or a
342 group.
343 Group overrides can contain attributes given by
345 · ldap_group_name
347 · ldap_group_gid_number
349 Default: ipaGroupOverride
351
353 Certain option defaults do not match their respective backend provider
354 defaults, these option names and IPA provider-specific defaults are
355 listed below:
356 KRB5 Provider
358 · krb5_validate = true
359 · krb5_use_fast = try
361 · krb5_canonicalize = true
363 LDAP Provider - General
365 · ldap_schema = ipa_v1
366 · ldap_force_upper_case_realm = true
368 · ldap_sasl_mech = GSSAPI
370 · ldap_sasl_minssf = 56
372 · ldap_account_expire_policy = ipa
374 · ldap_use_tokengroups = true
376 LDAP Provider - User options
378 · ldap_user_member_of = memberOf
379 · ldap_user_uuid = ipaUniqueID
381 · ldap_user_ssh_public_key = ipaSshPubKey
383 · ldap_user_auth_type = ipaUserAuthType
385 LDAP Provider - Group options
387 · ldap_group_object_class = ipaUserGroup
388 · ldap_group_object_class_alt = posixGroup
390 · ldap_group_member = member
392 · ldap_group_uuid = ipaUniqueID
394 · ldap_group_objectsid = ipaNTSecurityIdentifier
396 · ldap_group_external_member = ipaExternalMember
398
400 The IPA subdomains provider behaves slightly differently if it is
401 configured explicitly or implicitly.
402 If the option 'subdomains_provider = ipa' is found in the domain
404 section of sssd.conf, the IPA subdomains provider is configured
405 explicitly, and all subdomain requests are sent to the IPA server if
406 necessary.
407 If the option 'subdomains_provider' is not set in the domain section of
409 sssd.conf but there is the option 'id_provider = ipa', the IPA
410 subdomains provider is configured implicitly. In this case, if a
411 subdomain request fails and indicates that the server does not support
412 subdomains, i.e. is not configured for trusts, the IPA subdomains
413 provider is disabled. After an hour or after the IPA provider goes
414 online, the subdomains provider is enabled again.
415
417 Some configuration options can be also set for a trusted domain. A
418 trusted domain configuration can either be done using a subsection, for
419 example:
420 [domain/ipa.domain.com/ad.domain.com]
422 ad_server = dc.ad.domain.com
423 In addition, some options can be set in the parent domain and inherited
425 by the trusted domain using the “subdomain_inherit” option. For more
426 details, see the sssd.conf(5) manual page.
427 Different configuration options are tunable for a trusted domain
429 depending on whether you are configuring SSSD on an IPA server or an
430 IPA client.
431 OPTIONS TUNABLE ON IPA MASTERS
433 The following options can be set in a subdomain section on an IPA
434 master:
435 · ad_server
437 · ad_backup_server
439 · ad_site
441 · ldap_search_base
443 · ldap_user_search_base
445 · ldap_group_search_base
447 · use_fully_qualified_names
449 OPTIONS TUNABLE ON IPA CLIENTS
452 The following options can be set in a subdomain section on an IPA
453 client:
454 · ad_server
456 · ad_site
458 Note that if both options are set, only “ad_server” is evaluated.
460 Since any request for a user or a group identity from a trusted domain
462 triggered from an IPA client is resolved by the IPA server, the
463 “ad_server” and “ad_site” options only affect which AD DC will the
464 authentication be performed against. In particular, the addresses
465 resolved from these lists will be written to “kdcinfo” files read by
466 the Kerberos locator plugin. Please refer to the
467 sssd_krb5_locator_plugin(8) manual page for more details on the
468 Kerberos locator plugin.
469
471 The failover feature allows back ends to automatically switch to a
472 different server if the current server fails.
473 Failover Syntax
475 The list of servers is given as a comma-separated list; any number of
476 spaces is allowed around the comma. The servers are listed in order of
477 preference. The list can contain any number of servers.
478 For each failover-enabled config option, two variants exist: primary
480 and backup. The idea is that servers in the primary list are preferred
481 and backup servers are only searched if no primary servers can be
482 reached. If a backup server is selected, a timeout of 31 seconds is
483 set. After this timeout SSSD will periodically try to reconnect to one
484 of the primary servers. If it succeeds, it will replace the current
485 active (backup) server.
486 The Failover Mechanism
488 The failover mechanism distinguishes between a machine and a service.
489 The back end first tries to resolve the hostname of a given machine; if
490 this resolution attempt fails, the machine is considered offline. No
491 further attempts are made to connect to this machine for any other
492 service. If the resolution attempt succeeds, the back end tries to
493 connect to a service on this machine. If the service connection attempt
494 fails, then only this particular service is considered offline and the
495 back end automatically switches over to the next service. The machine
496 is still considered online and might still be tried for another
497 service.
498 Further connection attempts are made to machines or services marked as
500 offline after a specified period of time; this is currently hard coded
501 to 30 seconds.
502 If there are no more machines to try, the back end as a whole switches
504 to offline mode, and then attempts to reconnect every 30 seconds.
505 Failover time outs and tuning
507 Resolving a server to connect to can be as simple as running a single
508 DNS query or can involve several steps, such as finding the correct
509 site or trying out multiple host names in case some of the configured
510 servers are not reachable. The more complex scenarios can take some
511 time and SSSD needs to balance between providing enough time to finish
512 the resolution process but on the other hand, not trying for too long
513 before falling back to offline mode. If the SSSD debug logs show that
514 the server resolution is timing out before a live server is contacted,
515 you can consider changing the time outs.
516 This section lists the available tunables. Please refer to their
518 description in the sssd.conf(5), manual page.
519 dns_resolver_op_timeout
521 How long would SSSD talk to a single DNS server.
522 dns_resolver_timeout
524 How long would SSSD try to resolve a failover service. This service
525 resolution internally might include several steps, such as
526 resolving DNS SRV queries or locating the site.
527 For LDAP-based providers, the resolve operation is performed as part of
529 an LDAP connection operation. Therefore, also the “ldap_opt_timeout>”
530 timeout should be set to a larger value than “dns_resolver_timeout”
531 which in turn should be set to a larger value than
532 “dns_resolver_op_timeout”.
533
535 The service discovery feature allows back ends to automatically find
536 the appropriate servers to connect to using a special DNS query. This
537 feature is not supported for backup servers.
538 Configuration
540 If no servers are specified, the back end automatically uses service
541 discovery to try to find a server. Optionally, the user may choose to
542 use both fixed server addresses and service discovery by inserting a
543 special keyword, “_srv_”, in the list of servers. The order of
544 preference is maintained. This feature is useful if, for example, the
545 user prefers to use service discovery whenever possible, and fall back
546 to a specific server when no servers can be discovered using DNS.
547 The domain name
549 Please refer to the “dns_discovery_domain” parameter in the
550 sssd.conf(5) manual page for more details.
551 The protocol
553 The queries usually specify _tcp as the protocol. Exceptions are
554 documented in respective option description.
555 See Also
557 For more information on the service discovery mechanism, refer to RFC
558 2782.
559
561 The following example assumes that SSSD is correctly configured and
562 example.com is one of the domains in the [sssd] section. This examples
563 shows only the ipa provider-specific options.
564 [domain/example.com]
566 id_provider = ipa
567 ipa_server = ipaserver.example.com
568 ipa_hostname = myhost.example.com
569
572 sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
573 sssd-ipa(5), sssd-ad(5), sssd-sudo(5),sssd-secrets(5),sssd-session-
574 recording(5), sss_cache(8), sss_debuglevel(8), sss_groupadd(8),
575 sss_groupdel(8), sss_groupshow(8), sss_groupmod(8), sss_useradd(8),
576 sss_userdel(8), sss_usermod(8), sss_obfuscate(8), sss_seed(8),
577 sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
578 sss_ssh_knownhostsproxy(8),sssd-ifp(5),pam_sss(8).
579 sss_rpcidmapd(5)sssd-systemtap(5)
580
582 The SSSD upstream - https://pagure.io/SSSD/sssd/
583SSSD 04/25/2019 SSSD-IPA(5)