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       ipa_enable_dns_sites (boolean)
114           Enables DNS sites - location based service discovery.
115
116           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
125           Default: false
126
127       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
133           Default: 0 (disabled)
134
135       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
140           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
144           Default: False (disabled)
145
146       dyndns_force_tcp (bool)
147           Whether the nsupdate utility should default to using TCP for
148           communicating with the DNS server.
149
150           Default: False (let nsupdate choose the protocol)
151
152       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
156           Setting this option makes sense for environments where the DNS
157           server is different from the identity server.
158
159           Please note that this option will be only used in fallback attempt
160           when previous attempt using autodetected settings failed.
161
162           Default: None (let nsupdate choose the server)
163
164       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
169           Default: true
170
171       ipa_deskprofile_search_base (string)
172           Optional. Use the given string as search base for Desktop Profile
173           related objects.
174
175           Default: Use base DN
176
177       ipa_hbac_search_base (string)
178           Optional. Use the given string as search base for HBAC related
179           objects.
180
181           Default: Use base DN
182
183       ipa_host_search_base (string)
184           Deprecated. Use ldap_host_search_base instead.
185
186       ipa_selinux_search_base (string)
187           Optional. Use the given string as search base for SELinux user
188           maps.
189
190           See “ldap_search_base” for information about configuring multiple
191           search bases.
192
193           Default: the value of ldap_search_base
194
195       ipa_subdomains_search_base (string)
196           Optional. Use the given string as search base for trusted domains.
197
198           See “ldap_search_base” for information about configuring multiple
199           search bases.
200
201           Default: the value of cn=trusts,%basedn
202
203       ipa_master_domain_search_base (string)
204           Optional. Use the given string as search base for master domain
205           object.
206
207           See “ldap_search_base” for information about configuring multiple
208           search bases.
209
210           Default: the value of cn=ad,cn=etc,%basedn
211
212       ipa_views_search_base (string)
213           Optional. Use the given string as search base for views containers.
214
215           See “ldap_search_base” for information about configuring multiple
216           search bases.
217
218           Default: the value of cn=views,cn=accounts,%basedn
219
220       krb5_realm (string)
221           The name of the Kerberos realm. This is optional and defaults to
222           the value of “ipa_domain”.
223
224           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
227       krb5_confd_path (string)
228           Absolute path of a directory where SSSD should place Kerberos
229           configuration snippets.
230
231           To disable the creation of the configuration snippets set the
232           parameter to 'none'.
233
234           Default: not set (krb5.include.d subdirectory of SSSD's pubconf
235           directory)
236
237       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
243           Default: 5 (seconds)
244
245       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
250           Default: 60 (minutes)
251
252       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
257           Default: 5 (seconds)
258
259       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
264           Default: 5 (seconds)
265
266       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
271           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
274           NOTE: There are currently some assumptions that must be met when
275           SSSD is running on an IPA server.
276
277           ·   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
281           ·   The “full_name_format” option must not be tweaked to only print
282               short names for users from trusted domains.
283
284           Default: false
285
286       ipa_automount_location (string)
287           The automounter location this IPA client will be using
288
289           Default: The location named "default"
290
291           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
296   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
303       ipa_view_class (string)
304           Objectclass of the view container.
305
306           Default: nsContainer
307
308       ipa_view_name (string)
309           Name of the attribute holding the name of the view.
310
311           Default: cn
312
313       ipa_override_object_class (string)
314           Objectclass of the override objects.
315
316           Default: ipaOverrideAnchor
317
318       ipa_anchor_uuid (string)
319           Name of the attribute containing the reference to the original
320           object in a remote domain.
321
322           Default: ipaAnchorUUID
323
324       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
328           User overrides can contain attributes given by
329
330           ·   ldap_user_name
331
332           ·   ldap_user_uid_number
333
334           ·   ldap_user_gid_number
335
336           ·   ldap_user_gecos
337
338           ·   ldap_user_home_directory
339
340           ·   ldap_user_shell
341
342           ·   ldap_user_ssh_public_key
343
344           Default: ipaUserOverride
345
346       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
351           Group overrides can contain attributes given by
352
353           ·   ldap_group_name
354
355           ·   ldap_group_gid_number
356
357           Default: ipaGroupOverride
358

MODIFIED DEFAULT OPTIONS

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
364   KRB5 Provider
365       ·   krb5_validate = true
366
367       ·   krb5_use_fast = try
368
369       ·   krb5_canonicalize = true
370
371   LDAP Provider - General
372       ·   ldap_schema = ipa_v1
373
374       ·   ldap_force_upper_case_realm = true
375
376       ·   ldap_sasl_mech = GSSAPI
377
378       ·   ldap_sasl_minssf = 56
379
380       ·   ldap_account_expire_policy = ipa
381
382       ·   ldap_use_tokengroups = true
383
384   LDAP Provider - User options
385       ·   ldap_user_member_of = memberOf
386
387       ·   ldap_user_uuid = ipaUniqueID
388
389       ·   ldap_user_ssh_public_key = ipaSshPubKey
390
391       ·   ldap_user_auth_type = ipaUserAuthType
392
393   LDAP Provider - Group options
394       ·   ldap_group_object_class = ipaUserGroup
395
396       ·   ldap_group_object_class_alt = posixGroup
397
398       ·   ldap_group_member = member
399
400       ·   ldap_group_uuid = ipaUniqueID
401
402       ·   ldap_group_objectsid = ipaNTSecurityIdentifier
403
404       ·   ldap_group_external_member = ipaExternalMember
405

SUBDOMAINS PROVIDER

407       The IPA subdomains provider behaves slightly differently if it is
408       configured explicitly or implicitly.
409
410       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
415       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

TRUSTED DOMAINS CONFIGURATION

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
428           [domain/ipa.domain.com/ad.domain.com]
429           ad_server = dc.ad.domain.com
430
431       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
435       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
439   OPTIONS TUNABLE ON IPA MASTERS
440       The following options can be set in a subdomain section on an IPA
441       master:
442
443       ·   ad_server
444
445       ·   ad_backup_server
446
447       ·   ad_site
448
449       ·   ldap_search_base
450
451       ·   ldap_user_search_base
452
453       ·   ldap_group_search_base
454
455       ·   use_fully_qualified_names
456
457
458   OPTIONS TUNABLE ON IPA CLIENTS
459       The following options can be set in a subdomain section on an IPA
460       client:
461
462       ·   ad_server
463
464       ·   ad_site
465
466       Note that if both options are set, only “ad_server” is evaluated.
467
468       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

FAILOVER

478       The failover feature allows back ends to automatically switch to a
479       different server if the current server fails.
480
481   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
486       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
494   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
506       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
510       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
513   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
524       This section lists the available tunables. Please refer to their
525       description in the sssd.conf(5), manual page.
526
527       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
531           Default: 1000
532
533       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
538           Default: 2
539
540       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
545           Default: 4
546
547       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

SERVICE DISCOVERY

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
559   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
568   The domain name
569       Please refer to the “dns_discovery_domain” parameter in the
570       sssd.conf(5) manual page for more details.
571
572   The protocol
573       The queries usually specify _tcp as the protocol. Exceptions are
574       documented in respective option description.
575
576   See Also
577       For more information on the service discovery mechanism, refer to RFC
578       2782.
579

EXAMPLE

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
585           [domain/example.com]
586           id_provider = ipa
587           ipa_server = ipaserver.example.com
588           ipa_hostname = myhost.example.com
589
590

SEE ALSO

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

AUTHORS

600       The SSSD upstream - https://pagure.io/SSSD/sssd/
601
602
603
604SSSD                              02/26/2020                       SSSD-IPA(5)
Impressum