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

NAME

6       sssd-krb5 - SSSD Kerberos provider
7

DESCRIPTION

9       This manual page describes the configuration of the Kerberos 5
10       authentication backend for sssd(8). For a detailed syntax reference,
11       please refer to the “FILE FORMAT” section of the sssd.conf(5) manual
12       page.
13
14       The Kerberos 5 authentication backend contains auth and chpass
15       providers. It must be paired with an identity provider in order to
16       function properly (for example, id_provider = ldap). Some information
17       required by the Kerberos 5 authentication backend must be provided by
18       the identity provider, such as the user's Kerberos Principal Name
19       (UPN). The configuration of the identity provider should have an entry
20       to specify the UPN. Please refer to the man page for the applicable
21       identity provider for details on how to configure this.
22
23       This backend also provides access control based on the .k5login file in
24       the home directory of the user. See k5login(5) for more details. Please
25       note that an empty .k5login file will deny all access to this user. To
26       activate this feature, use 'access_provider = krb5' in your SSSD
27       configuration.
28
29       In the case where the UPN is not available in the identity backend,
30       sssd will construct a UPN using the format username@krb5_realm.
31

CONFIGURATION OPTIONS

33       If the auth-module krb5 is used in an SSSD domain, the following
34       options must be used. See the sssd.conf(5) manual page, section “DOMAIN
35       SECTIONS”, for details on the configuration of an SSSD domain.
36
37       krb5_server, krb5_backup_server (string)
38           Specifies the comma-separated list of IP addresses or hostnames of
39           the Kerberos servers to which SSSD should connect, in the order of
40           preference. For more information on failover and server redundancy,
41           see the “FAILOVER” section. An optional port number (preceded by a
42           colon) may be appended to the addresses or hostnames. If empty,
43           service discovery is enabled; for more information, refer to the
44           “SERVICE DISCOVERY” section.
45
46           When using service discovery for KDC or kpasswd servers, SSSD first
47           searches for DNS entries that specify _udp as the protocol and
48           falls back to _tcp if none are found.
49
50           This option was named “krb5_kdcip” in earlier releases of SSSD.
51           While the legacy name is recognized for the time being, users are
52           advised to migrate their config files to use “krb5_server” instead.
53
54       krb5_realm (string)
55           The name of the Kerberos realm. This option is required and must be
56           specified.
57
58       krb5_kpasswd, krb5_backup_kpasswd (string)
59           If the change password service is not running on the KDC,
60           alternative servers can be defined here. An optional port number
61           (preceded by a colon) may be appended to the addresses or
62           hostnames.
63
64           For more information on failover and server redundancy, see the
65           “FAILOVER” section. NOTE: Even if there are no more kpasswd servers
66           to try, the backend is not switched to operate offline if
67           authentication against the KDC is still possible.
68
69           Default: Use the KDC
70
71       krb5_ccachedir (string)
72           Directory to store credential caches. All the substitution
73           sequences of krb5_ccname_template can be used here, too, except %d
74           and %P. The directory is created as private and owned by the user,
75           with permissions set to 0700.
76
77           Default: /tmp
78
79       krb5_ccname_template (string)
80           Location of the user's credential cache. Three credential cache
81           types are currently supported: “FILE”, “DIR” and
82           “KEYRING:persistent”. The cache can be specified either as
83           TYPE:RESIDUAL, or as an absolute path, which implies the “FILE”
84           type. In the template, the following sequences are substituted:
85
86           %u
87               login name
88
89           %U
90               login UID
91
92           %p
93               principal name
94
95           %r
96               realm name
97
98           %h
99               home directory
100
101           %d
102               value of krb5_ccachedir
103
104           %P
105               the process ID of the SSSD client
106
107           %%
108               a literal '%'
109
110           If the template ends with 'XXXXXX' mkstemp(3) is used to create a
111           unique filename in a safe way.
112
113           When using KEYRING types, the only supported mechanism is
114           “KEYRING:persistent:%U”, which uses the Linux kernel keyring to
115           store credentials on a per-UID basis. This is also the recommended
116           choice, as it is the most secure and predictable method.
117
118           The default value for the credential cache name is sourced from the
119           profile stored in the system wide krb5.conf configuration file in
120           the [libdefaults] section. The option name is default_ccache_name.
121           See krb5.conf(5)'s PARAMETER EXPANSION paragraph for additional
122           information on the expansion format defined by krb5.conf.
123
124           NOTE: Please be aware that libkrb5 ccache expansion template from
125           krb5.conf(5) uses different expansion sequences than SSSD.
126
127           Default: (from libkrb5)
128
129       krb5_keytab (string)
130           The location of the keytab to use when validating credentials
131           obtained from KDCs.
132
133           Default: System keytab, normally /etc/krb5.keytab
134
135       krb5_store_password_if_offline (boolean)
136           Store the password of the user if the provider is offline and use
137           it to request a TGT when the provider comes online again.
138
139           NOTE: this feature is only available on Linux. Passwords stored in
140           this way are kept in plaintext in the kernel keyring and are
141           potentially accessible by the root user (with difficulty).
142
143           Default: false
144
145       krb5_use_fast (string)
146           Enables flexible authentication secure tunneling (FAST) for
147           Kerberos pre-authentication. The following options are supported:
148
149           never use FAST. This is equivalent to not setting this option at
150           all.
151
152           try to use FAST. If the server does not support FAST, continue the
153           authentication without it.
154
155           demand to use FAST. The authentication fails if the server does not
156           require fast.
157
158           Default: not set, i.e. FAST is not used.
159
160           NOTE: a keytab or support for anonymous PKINIT is required to use
161           FAST.
162
163           NOTE: SSSD supports FAST only with MIT Kerberos version 1.8 and
164           later. If SSSD is used with an older version of MIT Kerberos, using
165           this option is a configuration error.
166
167       krb5_fast_principal (string)
168           Specifies the server principal to use for FAST.
169
170       krb5_fast_use_anonymous_pkinit (boolean)
171           If set to true try to use anonymous PKINIT instead of a keytab to
172           get the required credential for FAST. The krb5_fast_principal
173           options is ignored in this case.
174
175           Default: false
176
177       krb5_use_kdcinfo (boolean)
178           Specifies if the SSSD should instruct the Kerberos libraries what
179           realm and which KDCs to use. This option is on by default, if you
180           disable it, you need to configure the Kerberos library using the
181           krb5.conf(5) configuration file.
182
183           See the sssd_krb5_locator_plugin(8) manual page for more
184           information on the locator plugin.
185
186           Default: true
187
188       krb5_kdcinfo_lookahead (string)
189           When krb5_use_kdcinfo is set to true, you can limit the amount of
190           servers handed to sssd_krb5_locator_plugin(8). This might be
191           helpful when there are too many servers discovered using SRV
192           record.
193
194           The krb5_kdcinfo_lookahead option contains two numbers separated by
195           a colon. The first number represents number of primary servers used
196           and the second number specifies the number of backup servers.
197
198           For example 10:0 means that up to 10 primary servers will be handed
199           to sssd_krb5_locator_plugin(8) but no backup servers.
200
201           Default: 3:1
202
203       krb5_use_enterprise_principal (boolean)
204           Specifies if the user principal should be treated as enterprise
205           principal. See section 5 of RFC 6806 for more details about
206           enterprise principals.
207
208           Default: false (AD provider: true)
209
210           The IPA provider will set to option to 'true' if it detects that
211           the server is capable of handling enterprise principals and the
212           option is not set explicitly in the config file.
213
214       krb5_use_subdomain_realm (boolean)
215           Specifies to use subdomains realms for the authentication of users
216           from trusted domains. This option can be set to 'true' if
217           enterprise principals are used with upnSuffixes which are not known
218           on the parent domain KDCs. If the option is set to 'true' SSSD will
219           try to send the request directly to a KDC of the trusted domain the
220           user is coming from.
221
222           Default: false
223
224       krb5_map_user (string)
225           The list of mappings is given as a comma-separated list of pairs
226           “username:primary” where “username” is a UNIX user name and
227           “primary” is a user part of a kerberos principal. This mapping is
228           used when user is authenticating using “auth_provider = krb5”.
229
230           example:
231
232               krb5_realm = REALM
233               krb5_map_user = joe:juser,dick:richard
234
235           “joe” and “dick” are UNIX user names and “juser” and “richard” are
236           primaries of kerberos principals. For user “joe” resp.  “dick” SSSD
237           will try to kinit as “juser@REALM” resp.  “richard@REALM”.
238
239           Default: not set
240
241       krb5_auth_timeout (integer)
242           Timeout in seconds after an online authentication request or change
243           password request is aborted. If possible, the authentication
244           request is continued offline.
245
246           Default: 6
247
248       krb5_validate (boolean)
249           Verify with the help of krb5_keytab that the TGT obtained has not
250           been spoofed. The keytab is checked for entries sequentially, and
251           the first entry with a matching realm is used for validation. If no
252           entry matches the realm, the last entry in the keytab is used. This
253           process can be used to validate environments using cross-realm
254           trust by placing the appropriate keytab entry as the last entry or
255           the only entry in the keytab file.
256
257           Default: false (IPA and AD provider: true)
258
259           Please note that the ticket validation is the first step when
260           checking the PAC (see 'pac_check' in the sssd.conf(5) manual page
261           for details). If ticket validation is disabled the PAC checks will
262           be skipped as well.
263
264       krb5_renewable_lifetime (string)
265           Request a renewable ticket with a total lifetime, given as an
266           integer immediately followed by a time unit:
267
268           s for seconds
269
270           m for minutes
271
272           h for hours
273
274           d for days.
275
276           If there is no unit given, s is assumed.
277
278           NOTE: It is not possible to mix units. To set the renewable
279           lifetime to one and a half hours, use '90m' instead of '1h30m'.
280
281           Default: not set, i.e. the TGT is not renewable
282
283       krb5_lifetime (string)
284           Request ticket with a lifetime, given as an integer immediately
285           followed by a time unit:
286
287           s for seconds
288
289           m for minutes
290
291           h for hours
292
293           d for days.
294
295           If there is no unit given s is assumed.
296
297           NOTE: It is not possible to mix units. To set the lifetime to one
298           and a half hours please use '90m' instead of '1h30m'.
299
300           Default: not set, i.e. the default ticket lifetime configured on
301           the KDC.
302
303       krb5_renew_interval (string)
304           The time in seconds between two checks if the TGT should be
305           renewed. TGTs are renewed if about half of their lifetime is
306           exceeded, given as an integer immediately followed by a time unit:
307
308           s for seconds
309
310           m for minutes
311
312           h for hours
313
314           d for days.
315
316           If there is no unit given, s is assumed.
317
318           NOTE: It is not possible to mix units. To set the renewable
319           lifetime to one and a half hours, use '90m' instead of '1h30m'.
320
321           If this option is not set or is 0 the automatic renewal is
322           disabled.
323
324           Default: not set
325
326       krb5_canonicalize (boolean)
327           Specifies if the host and user principal should be canonicalized.
328           This feature is available with MIT Kerberos 1.7 and later versions.
329
330           Default: false
331

FAILOVER

333       The failover feature allows back ends to automatically switch to a
334       different server if the current server fails.
335
336   Failover Syntax
337       The list of servers is given as a comma-separated list; any number of
338       spaces is allowed around the comma. The servers are listed in order of
339       preference. The list can contain any number of servers.
340
341       For each failover-enabled config option, two variants exist: primary
342       and backup. The idea is that servers in the primary list are preferred
343       and backup servers are only searched if no primary servers can be
344       reached. If a backup server is selected, a timeout of 31 seconds is
345       set. After this timeout SSSD will periodically try to reconnect to one
346       of the primary servers. If it succeeds, it will replace the current
347       active (backup) server.
348
349   The Failover Mechanism
350       The failover mechanism distinguishes between a machine and a service.
351       The back end first tries to resolve the hostname of a given machine; if
352       this resolution attempt fails, the machine is considered offline. No
353       further attempts are made to connect to this machine for any other
354       service. If the resolution attempt succeeds, the back end tries to
355       connect to a service on this machine. If the service connection attempt
356       fails, then only this particular service is considered offline and the
357       back end automatically switches over to the next service. The machine
358       is still considered online and might still be tried for another
359       service.
360
361       Further connection attempts are made to machines or services marked as
362       offline after a specified period of time; this is currently hard coded
363       to 30 seconds.
364
365       If there are no more machines to try, the back end as a whole switches
366       to offline mode, and then attempts to reconnect every 30 seconds.
367
368   Failover time outs and tuning
369       Resolving a server to connect to can be as simple as running a single
370       DNS query or can involve several steps, such as finding the correct
371       site or trying out multiple host names in case some of the configured
372       servers are not reachable. The more complex scenarios can take some
373       time and SSSD needs to balance between providing enough time to finish
374       the resolution process but on the other hand, not trying for too long
375       before falling back to offline mode. If the SSSD debug logs show that
376       the server resolution is timing out before a live server is contacted,
377       you can consider changing the time outs.
378
379       This section lists the available tunables. Please refer to their
380       description in the sssd.conf(5), manual page.
381
382       dns_resolver_server_timeout
383           Time in milliseconds that sets how long would SSSD talk to a single
384           DNS server before trying next one.
385
386           Default: 1000
387
388       dns_resolver_op_timeout
389           Time in seconds to tell how long would SSSD try to resolve single
390           DNS query (e.g. resolution of a hostname or an SRV record) before
391           trying the next hostname or discovery domain.
392
393           Default: 3
394
395       dns_resolver_timeout
396           How long would SSSD try to resolve a failover service. This service
397           resolution internally might include several steps, such as
398           resolving DNS SRV queries or locating the site.
399
400           Default: 6
401
402       For LDAP-based providers, the resolve operation is performed as part of
403       an LDAP connection operation. Therefore, also the “ldap_opt_timeout”
404       timeout should be set to a larger value than “dns_resolver_timeout”
405       which in turn should be set to a larger value than
406       “dns_resolver_op_timeout” which should be larger than
407       “dns_resolver_server_timeout”.
408

SERVICE DISCOVERY

410       The service discovery feature allows back ends to automatically find
411       the appropriate servers to connect to using a special DNS query. This
412       feature is not supported for backup servers.
413
414   Configuration
415       If no servers are specified, the back end automatically uses service
416       discovery to try to find a server. Optionally, the user may choose to
417       use both fixed server addresses and service discovery by inserting a
418       special keyword, “_srv_”, in the list of servers. The order of
419       preference is maintained. This feature is useful if, for example, the
420       user prefers to use service discovery whenever possible, and fall back
421       to a specific server when no servers can be discovered using DNS.
422
423   The domain name
424       Please refer to the “dns_discovery_domain” parameter in the
425       sssd.conf(5) manual page for more details.
426
427   The protocol
428       The queries usually specify _tcp as the protocol. Exceptions are
429       documented in respective option description.
430
431   See Also
432       For more information on the service discovery mechanism, refer to RFC
433       2782.
434

EXAMPLE

436       The following example assumes that SSSD is correctly configured and FOO
437       is one of the domains in the [sssd] section. This example shows only
438       configuration of Kerberos authentication; it does not include any
439       identity provider.
440
441           [domain/FOO]
442           auth_provider = krb5
443           krb5_server = 192.168.1.1
444           krb5_realm = EXAMPLE.COM
445
446

SEE ALSO

448       sssd(8), sssd.conf(5), sssd-ldap(5), sssd-ldap-attributes(5), sssd-
449       krb5(5), sssd-simple(5), sssd-ipa(5), sssd-ad(5), sssd-files(5), sssd-
450       sudo(5), sssd-session-recording(5), sss_cache(8), sss_debuglevel(8),
451       sss_obfuscate(8), sss_seed(8), sssd_krb5_locator_plugin(8),
452       sss_ssh_authorizedkeys(8), sss_ssh_knownhostsproxy(8), sssd-ifp(5),
453       pam_sss(8).  sss_rpcidmapd(5) sssd-systemtap(5)
454

AUTHORS

456       The SSSD upstream - https://github.com/SSSD/sssd/
457
458
459
460SSSD                              11/15/2023                      SSSD-KRB5(5)
Impressum