1SSSD-IPA(5)              File Formats and Conventions              SSSD-IPA(5)
2
3
4

NAME

6       sssd-ipa - SSSD IPA provider
7

DESCRIPTION

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

CONFIGURATION OPTIONS

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

MODIFIED DEFAULT OPTIONS

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

SUBDOMAINS PROVIDER

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

TRUSTED DOMAINS CONFIGURATION

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

FAILOVER

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

SERVICE DISCOVERY

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

EXAMPLE

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

SEE ALSO

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

AUTHORS

606       The SSSD upstream - https://github.com/SSSD/sssd/
607
608
609
610SSSD                              12/09/2022                       SSSD-IPA(5)
Impressum