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 has a minimal configuration
30 (see “ipa_access_order”) as it mainly uses HBAC (host-based access
31 control) rules. Please refer to freeipa.org for more information about
32 HBAC.
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 Note that dyndns_update_per_family parameter does not apply for PTR
152 record updates. Those updates are always sent separately.
153 Default: False (disabled)
155 dyndns_force_tcp (bool)
157 Whether the nsupdate utility should default to using TCP for
158 communicating with the DNS server.
159 Default: False (let nsupdate choose the protocol)
161 dyndns_server (string)
163 The DNS server to use when performing a DNS update. In most setups,
164 it's recommended to leave this option unset.
165 Setting this option makes sense for environments where the DNS
167 server is different from the identity server.
168 Please note that this option will be only used in fallback attempt
170 when previous attempt using autodetected settings failed.
171 Default: None (let nsupdate choose the server)
173 dyndns_update_per_family (boolean)
175 DNS update is by default performed in two steps - IPv4 update and
176 then IPv6 update. In some cases it might be desirable to perform
177 IPv4 and IPv6 update in single step.
178 Default: true
180 ipa_access_order (string)
182 Comma separated list of access control options. Allowed values are:
183 expire: use IPA's account expiration policy.
185 pwd_expire_policy_reject, pwd_expire_policy_warn,
187 pwd_expire_policy_renew: These options are useful if users are
188 interested in being warned that password is about to expire and
189 authentication is based on using a different method than passwords
190 - for example SSH keys.
191 The difference between these options is the action taken if user
193 password is expired:
194 • pwd_expire_policy_reject - user is denied to log in,
196 • pwd_expire_policy_warn - user is still able to log in,
198 • pwd_expire_policy_renew - user is prompted to change their
200 password immediately.
201 Please note that 'access_provider = ipa' must be set for this
203 feature to work.
204 ipa_deskprofile_search_base (string)
206 Optional. Use the given string as search base for Desktop Profile
207 related objects.
208 Default: Use base DN
210 ipa_hbac_search_base (string)
212 Optional. Use the given string as search base for HBAC related
213 objects.
214 Default: Use base DN
216 ipa_host_search_base (string)
218 Deprecated. Use ldap_host_search_base instead.
219 ipa_selinux_search_base (string)
221 Optional. Use the given string as search base for SELinux user
222 maps.
223 See “ldap_search_base” for information about configuring multiple
225 search bases.
226 Default: the value of ldap_search_base
228 ipa_subdomains_search_base (string)
230 Optional. Use the given string as search base for trusted domains.
231 See “ldap_search_base” for information about configuring multiple
233 search bases.
234 Default: the value of cn=trusts,%basedn
236 ipa_master_domain_search_base (string)
238 Optional. Use the given string as search base for master domain
239 object.
240 See “ldap_search_base” for information about configuring multiple
242 search bases.
243 Default: the value of cn=ad,cn=etc,%basedn
245 ipa_views_search_base (string)
247 Optional. Use the given string as search base for views containers.
248 See “ldap_search_base” for information about configuring multiple
250 search bases.
251 Default: the value of cn=views,cn=accounts,%basedn
253 krb5_realm (string)
255 The name of the Kerberos realm. This is optional and defaults to
256 the value of “ipa_domain”.
257 The name of the Kerberos realm has a special meaning in IPA - it is
259 converted into the base DN to use for performing LDAP operations.
260 krb5_confd_path (string)
262 Absolute path of a directory where SSSD should place Kerberos
263 configuration snippets.
264 To disable the creation of the configuration snippets set the
266 parameter to 'none'.
267 Default: not set (krb5.include.d subdirectory of SSSD's pubconf
269 directory)
270 ipa_deskprofile_refresh (integer)
272 The amount of time between lookups of the Desktop Profile rules
273 against the IPA server. This will reduce the latency and load on
274 the IPA server if there are many desktop profiles requests made in
275 a short period.
276 Default: 5 (seconds)
278 ipa_deskprofile_request_interval (integer)
280 The amount of time between lookups of the Desktop Profile rules
281 against the IPA server in case the last request did not return any
282 rule.
283 Default: 60 (minutes)
285 ipa_hbac_refresh (integer)
287 The amount of time between lookups of the HBAC rules against the
288 IPA server. This will reduce the latency and load on the IPA server
289 if there are many access-control requests made in a short period.
290 Default: 5 (seconds)
292 ipa_hbac_selinux (integer)
294 The amount of time between lookups of the SELinux maps against the
295 IPA server. This will reduce the latency and load on the IPA server
296 if there are many user login requests made in a short period.
297 Default: 5 (seconds)
299 ipa_server_mode (boolean)
301 This option will be set by the IPA installer (ipa-server-install)
302 automatically and denotes if SSSD is running on an IPA server or
303 not.
304 On an IPA server SSSD will lookup users and groups from trusted
306 domains directly while on a client it will ask an IPA server.
307 NOTE: There are currently some assumptions that must be met when
309 SSSD is running on an IPA server.
310 • The “ipa_server” option must be configured to point to the IPA
312 server itself. This is already the default set by the IPA
313 installer, so no manual change is required.
314 • The “full_name_format” option must not be tweaked to only print
316 short names for users from trusted domains.
317 Default: false
319 ipa_automount_location (string)
321 The automounter location this IPA client will be using
322 Default: The location named "default"
324 Please note that the automounter only reads the master map on
326 startup, so if any autofs-related changes are made to the
327 sssd.conf, you typically also need to restart the automounter
328 daemon after restarting the SSSD.
329 VIEWS AND OVERRIDES
331 SSSD can handle views and overrides which are offered by FreeIPA 4.1
332 and later version. Since all paths and objectclasses are fixed on the
333 server side there is basically no need to configure anything. For
334 completeness the related options are listed here with their default
335 values.
336 ipa_view_class (string)
338 Objectclass of the view container.
339 Default: nsContainer
341 ipa_view_name (string)
343 Name of the attribute holding the name of the view.
344 Default: cn
346 ipa_override_object_class (string)
348 Objectclass of the override objects.
349 Default: ipaOverrideAnchor
351 ipa_anchor_uuid (string)
353 Name of the attribute containing the reference to the original
354 object in a remote domain.
355 Default: ipaAnchorUUID
357 ipa_user_override_object_class (string)
359 Name of the objectclass for user overrides. It is used to determine
360 if the found override object is related to a user or a group.
361 User overrides can contain attributes given by
363 • ldap_user_name
365 • ldap_user_uid_number
367 • ldap_user_gid_number
369 • ldap_user_gecos
371 • ldap_user_home_directory
373 • ldap_user_shell
375 • ldap_user_ssh_public_key
377 Default: ipaUserOverride
379 ipa_group_override_object_class (string)
381 Name of the objectclass for group overrides. It is used to
382 determine if the found override object is related to a user or a
383 group.
384 Group overrides can contain attributes given by
386 • ldap_group_name
388 • ldap_group_gid_number
390 Default: ipaGroupOverride
392
394 Certain option defaults do not match their respective backend provider
395 defaults, these option names and IPA provider-specific defaults are
396 listed below:
397 KRB5 Provider
399 • krb5_validate = true
400 • krb5_use_fast = try
402 • krb5_canonicalize = true
404 LDAP Provider - General
406 • ldap_schema = ipa_v1
407 • ldap_force_upper_case_realm = true
409 • ldap_sasl_mech = GSSAPI
411 • ldap_sasl_minssf = 56
413 • ldap_account_expire_policy = ipa
415 • ldap_use_tokengroups = true
417 LDAP Provider - User options
419 • ldap_user_member_of = memberOf
420 • ldap_user_uuid = ipaUniqueID
422 • ldap_user_ssh_public_key = ipaSshPubKey
424 • ldap_user_auth_type = ipaUserAuthType
426 LDAP Provider - Group options
428 • ldap_group_object_class = ipaUserGroup
429 • ldap_group_object_class_alt = posixGroup
431 • ldap_group_member = member
433 • ldap_group_uuid = ipaUniqueID
435 • ldap_group_objectsid = ipaNTSecurityIdentifier
437 • ldap_group_external_member = ipaExternalMember
439
441 The IPA subdomains provider behaves slightly differently if it is
442 configured explicitly or implicitly.
443 If the option 'subdomains_provider = ipa' is found in the domain
445 section of sssd.conf, the IPA subdomains provider is configured
446 explicitly, and all subdomain requests are sent to the IPA server if
447 necessary.
448 If the option 'subdomains_provider' is not set in the domain section of
450 sssd.conf but there is the option 'id_provider = ipa', the IPA
451 subdomains provider is configured implicitly. In this case, if a
452 subdomain request fails and indicates that the server does not support
453 subdomains, i.e. is not configured for trusts, the IPA subdomains
454 provider is disabled. After an hour or after the IPA provider goes
455 online, the subdomains provider is enabled again.
456
458 Some configuration options can also be set for a trusted domain. A
459 trusted domain configuration can be set using the trusted domain
460 subsection as shown in the example below. Alternatively, the
461 “subdomain_inherit” option can be used in the parent domain.
462 [domain/ipa.domain.com/ad.domain.com]
464 ad_server = dc.ad.domain.com
465 For more details, see the sssd.conf(5) manual page.
467 Different configuration options are tunable for a trusted domain
469 depending on whether you are configuring SSSD on an IPA server or an
470 IPA client.
471 OPTIONS TUNABLE ON IPA MASTERS
473 The following options can be set in a subdomain section on an IPA
474 master:
475 • ad_server
477 • ad_backup_server
479 • ad_site
481 • ldap_search_base
483 • ldap_user_search_base
485 • ldap_group_search_base
487 • use_fully_qualified_names
489 OPTIONS TUNABLE ON IPA CLIENTS
492 The following options can be set in a subdomain section on an IPA
493 client:
494 • ad_server
496 • ad_site
498 Note that if both options are set, only “ad_server” is evaluated.
500 Since any request for a user or a group identity from a trusted domain
502 triggered from an IPA client is resolved by the IPA server, the
503 “ad_server” and “ad_site” options only affect which AD DC will the
504 authentication be performed against. In particular, the addresses
505 resolved from these lists will be written to “kdcinfo” files read by
506 the Kerberos locator plugin. Please refer to the
507 sssd_krb5_locator_plugin(8) manual page for more details on the
508 Kerberos locator plugin.
509
511 The failover feature allows back ends to automatically switch to a
512 different server if the current server fails.
513 Failover Syntax
515 The list of servers is given as a comma-separated list; any number of
516 spaces is allowed around the comma. The servers are listed in order of
517 preference. The list can contain any number of servers.
518 For each failover-enabled config option, two variants exist: primary
520 and backup. The idea is that servers in the primary list are preferred
521 and backup servers are only searched if no primary servers can be
522 reached. If a backup server is selected, a timeout of 31 seconds is
523 set. After this timeout SSSD will periodically try to reconnect to one
524 of the primary servers. If it succeeds, it will replace the current
525 active (backup) server.
526 The Failover Mechanism
528 The failover mechanism distinguishes between a machine and a service.
529 The back end first tries to resolve the hostname of a given machine; if
530 this resolution attempt fails, the machine is considered offline. No
531 further attempts are made to connect to this machine for any other
532 service. If the resolution attempt succeeds, the back end tries to
533 connect to a service on this machine. If the service connection attempt
534 fails, then only this particular service is considered offline and the
535 back end automatically switches over to the next service. The machine
536 is still considered online and might still be tried for another
537 service.
538 Further connection attempts are made to machines or services marked as
540 offline after a specified period of time; this is currently hard coded
541 to 30 seconds.
542 If there are no more machines to try, the back end as a whole switches
544 to offline mode, and then attempts to reconnect every 30 seconds.
545 Failover time outs and tuning
547 Resolving a server to connect to can be as simple as running a single
548 DNS query or can involve several steps, such as finding the correct
549 site or trying out multiple host names in case some of the configured
550 servers are not reachable. The more complex scenarios can take some
551 time and SSSD needs to balance between providing enough time to finish
552 the resolution process but on the other hand, not trying for too long
553 before falling back to offline mode. If the SSSD debug logs show that
554 the server resolution is timing out before a live server is contacted,
555 you can consider changing the time outs.
556 This section lists the available tunables. Please refer to their
558 description in the sssd.conf(5), manual page.
559 dns_resolver_server_timeout
561 Time in milliseconds that sets how long would SSSD talk to a single
562 DNS server before trying next one.
563 Default: 1000
565 dns_resolver_op_timeout
567 Time in seconds to tell how long would SSSD try to resolve single
568 DNS query (e.g. resolution of a hostname or an SRV record) before
569 trying the next hostname or discovery domain.
570 Default: 3
572 dns_resolver_timeout
574 How long would SSSD try to resolve a failover service. This service
575 resolution internally might include several steps, such as
576 resolving DNS SRV queries or locating the site.
577 Default: 6
579 For LDAP-based providers, the resolve operation is performed as part of
581 an LDAP connection operation. Therefore, also the “ldap_opt_timeout”
582 timeout should be set to a larger value than “dns_resolver_timeout”
583 which in turn should be set to a larger value than
584 “dns_resolver_op_timeout” which should be larger than
585 “dns_resolver_server_timeout”.
586
588 The service discovery feature allows back ends to automatically find
589 the appropriate servers to connect to using a special DNS query. This
590 feature is not supported for backup servers.
591 Configuration
593 If no servers are specified, the back end automatically uses service
594 discovery to try to find a server. Optionally, the user may choose to
595 use both fixed server addresses and service discovery by inserting a
596 special keyword, “_srv_”, in the list of servers. The order of
597 preference is maintained. This feature is useful if, for example, the
598 user prefers to use service discovery whenever possible, and fall back
599 to a specific server when no servers can be discovered using DNS.
600 The domain name
602 Please refer to the “dns_discovery_domain” parameter in the
603 sssd.conf(5) manual page for more details.
604 The protocol
606 The queries usually specify _tcp as the protocol. Exceptions are
607 documented in respective option description.
608 See Also
610 For more information on the service discovery mechanism, refer to RFC
611 2782.
612
614 The following example assumes that SSSD is correctly configured and
615 example.com is one of the domains in the [sssd] section. This examples
616 shows only the ipa provider-specific options.
617 [domain/example.com]
619 id_provider = ipa
620 ipa_server = ipaserver.example.com
621 ipa_hostname = myhost.example.com
622
625 sssd(8), sssd.conf(5), sssd-ldap(5), sssd-ldap-attributes(5), sssd-
626 krb5(5), sssd-simple(5), sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-
627 sudo(5), sssd-session-recording(5), sss_cache(8), sss_debuglevel(8),
628 sss_obfuscate(8), sss_seed(8), sssd_krb5_locator_plugin(8),
629 sss_ssh_authorizedkeys(8), sss_ssh_knownhostsproxy(8), sssd-ifp(5),
630 pam_sss(8). sss_rpcidmapd(5) sssd-systemtap(5)
631
633 The SSSD upstream - https://github.com/SSSD/sssd/
634SSSD 11/15/2023 SSSD-IPA(5)