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       ipa_deskprofile_search_base (string)
165           Optional. Use the given string as search base for Desktop Profile
166           related objects.
167
168           Default: Use base DN
169
170       ipa_hbac_search_base (string)
171           Optional. Use the given string as search base for HBAC related
172           objects.
173
174           Default: Use base DN
175
176       ipa_host_search_base (string)
177           Deprecated. Use ldap_host_search_base instead.
178
179       ipa_selinux_search_base (string)
180           Optional. Use the given string as search base for SELinux user
181           maps.
182
183           See “ldap_search_base” for information about configuring multiple
184           search bases.
185
186           Default: the value of ldap_search_base
187
188       ipa_subdomains_search_base (string)
189           Optional. Use the given string as search base for trusted domains.
190
191           See “ldap_search_base” for information about configuring multiple
192           search bases.
193
194           Default: the value of cn=trusts,%basedn
195
196       ipa_master_domain_search_base (string)
197           Optional. Use the given string as search base for master domain
198           object.
199
200           See “ldap_search_base” for information about configuring multiple
201           search bases.
202
203           Default: the value of cn=ad,cn=etc,%basedn
204
205       ipa_views_search_base (string)
206           Optional. Use the given string as search base for views containers.
207
208           See “ldap_search_base” for information about configuring multiple
209           search bases.
210
211           Default: the value of cn=views,cn=accounts,%basedn
212
213       krb5_realm (string)
214           The name of the Kerberos realm. This is optional and defaults to
215           the value of “ipa_domain”.
216
217           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
220       krb5_confd_path (string)
221           Absolute path of a directory where SSSD should place Kerberos
222           configuration snippets.
223
224           To disable the creation of the configuration snippets set the
225           parameter to 'none'.
226
227           Default: not set (krb5.include.d subdirectory of SSSD's pubconf
228           directory)
229
230       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
236           Default: 5 (seconds)
237
238       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
243           Default: 60 (minutes)
244
245       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
250           Default: 5 (seconds)
251
252       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
257           Default: 5 (seconds)
258
259       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
264           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
267           NOTE: There are currently some assumptions that must be met when
268           SSSD is running on an IPA server.
269
270           ·   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
274           ·   The “full_name_format” option must not be tweaked to only print
275               short names for users from trusted domains.
276
277           Default: false
278
279       ipa_automount_location (string)
280           The automounter location this IPA client will be using
281
282           Default: The location named "default"
283
284           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
289   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
296       ipa_view_class (string)
297           Objectclass of the view container.
298
299           Default: nsContainer
300
301       ipa_view_name (string)
302           Name of the attribute holding the name of the view.
303
304           Default: cn
305
306       ipa_override_object_class (string)
307           Objectclass of the override objects.
308
309           Default: ipaOverrideAnchor
310
311       ipa_anchor_uuid (string)
312           Name of the attribute containing the reference to the original
313           object in a remote domain.
314
315           Default: ipaAnchorUUID
316
317       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
321           User overrides can contain attributes given by
322
323           ·   ldap_user_name
324
325           ·   ldap_user_uid_number
326
327           ·   ldap_user_gid_number
328
329           ·   ldap_user_gecos
330
331           ·   ldap_user_home_directory
332
333           ·   ldap_user_shell
334
335           ·   ldap_user_ssh_public_key
336
337           Default: ipaUserOverride
338
339       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
344           Group overrides can contain attributes given by
345
346           ·   ldap_group_name
347
348           ·   ldap_group_gid_number
349
350           Default: ipaGroupOverride
351

MODIFIED DEFAULT OPTIONS

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

SUBDOMAINS PROVIDER

400       The IPA subdomains provider behaves slightly differently if it is
401       configured explicitly or implicitly.
402
403       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
408       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

TRUSTED DOMAINS CONFIGURATION

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

FAILOVER

471       The failover feature allows back ends to automatically switch to a
472       different server if the current server fails.
473
474   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
479       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
487   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
499       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
503       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
506   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
517       This section lists the available tunables. Please refer to their
518       description in the sssd.conf(5), manual page.
519
520       dns_resolver_op_timeout
521           How long would SSSD talk to a single DNS server.
522
523       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
528       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

SERVICE DISCOVERY

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
539   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
548   The domain name
549       Please refer to the “dns_discovery_domain” parameter in the
550       sssd.conf(5) manual page for more details.
551
552   The protocol
553       The queries usually specify _tcp as the protocol. Exceptions are
554       documented in respective option description.
555
556   See Also
557       For more information on the service discovery mechanism, refer to RFC
558       2782.
559

EXAMPLE

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
565           [domain/example.com]
566           id_provider = ipa
567           ipa_server = ipaserver.example.com
568           ipa_hostname = myhost.example.com
569
570

SEE ALSO

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-session-recording(5),
574       sss_cache(8), sss_debuglevel(8), sss_obfuscate(8), sss_seed(8),
575       sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
576       sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8).  sss_rpcidmapd(5)
577       sssd-systemtap(5)
578

AUTHORS

580       The SSSD upstream - https://pagure.io/SSSD/sssd/
581
582
583
584SSSD                              07/01/2019                       SSSD-IPA(5)
Impressum