1SSSD-KRB5(5) File Formats and Conventions SSSD-KRB5(5)
2
6 sssd-krb5 - SSSD Kerberos provider
7
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 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 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 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
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 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 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 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 krb5_realm (string)
55 The name of the Kerberos realm. This option is required and must be
56 specified.
57 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 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 Default: Use the KDC
70 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 Default: /tmp
78 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 %u
87 login name
88 %U
90 login UID
91 %p
93 principal name
94 %r
96 realm name
97 %h
99 home directory
100 %d
102 value of krb5_ccachedir
103 %P
105 the process ID of the SSSD client
106 %%
108 a literal '%'
109 If the template ends with 'XXXXXX' mkstemp(3) is used to create a
111 unique filename in a safe way.
112 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 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 NOTE: Please be aware that libkrb5 ccache expansion template from
125 krb5.conf(5) uses different expansion sequences than SSSD.
126 Default: (from libkrb5)
128 krb5_keytab (string)
130 The location of the keytab to use when validating credentials
131 obtained from KDCs.
132 Default: System keytab, normally /etc/krb5.keytab
134 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 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 Default: false
144 krb5_use_fast (string)
146 Enables flexible authentication secure tunneling (FAST) for
147 Kerberos pre-authentication. The following options are supported:
148 never use FAST. This is equivalent to not setting this option at
150 all.
151 try to use FAST. If the server does not support FAST, continue the
153 authentication without it.
154 demand to use FAST. The authentication fails if the server does not
156 require fast.
157 Default: not set, i.e. FAST is not used.
159 NOTE: a keytab or support for anonymous PKINIT is required to use
161 FAST.
162 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 krb5_fast_principal (string)
168 Specifies the server principal to use for FAST.
169 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 Default: false
176 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 See the sssd_krb5_locator_plugin(8) manual page for more
184 information on the locator plugin.
185 Default: true
187 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 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 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 Default: 3:1
202 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 Default: false (AD provider: true)
209 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 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 Default: false
223 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 example:
231 krb5_realm = REALM
233 krb5_map_user = joe:juser,dick:richard
234 “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 Default: not set
240 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 Default: 6
247 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 Default: false (IPA and AD provider: true)
258 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 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 s for seconds
269 m for minutes
271 h for hours
273 d for days.
275 If there is no unit given, s is assumed.
277 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 Default: not set, i.e. the TGT is not renewable
282 krb5_lifetime (string)
284 Request ticket with a lifetime, given as an integer immediately
285 followed by a time unit:
286 s for seconds
288 m for minutes
290 h for hours
292 d for days.
294 If there is no unit given s is assumed.
296 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 Default: not set, i.e. the default ticket lifetime configured on
301 the KDC.
302 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 s for seconds
309 m for minutes
311 h for hours
313 d for days.
315 If there is no unit given, s is assumed.
317 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 If this option is not set or is 0 the automatic renewal is
322 disabled.
323 Default: not set
325 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 Default: false
331
333 The failover feature allows back ends to automatically switch to a
334 different server if the current server fails.
335 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 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 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 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 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 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 This section lists the available tunables. Please refer to their
380 description in the sssd.conf(5), manual page.
381 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 Default: 1000
387 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 Default: 3
394 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 Default: 6
401 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
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 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 The domain name
424 Please refer to the “dns_discovery_domain” parameter in the
425 sssd.conf(5) manual page for more details.
426 The protocol
428 The queries usually specify _tcp as the protocol. Exceptions are
429 documented in respective option description.
430 See Also
432 For more information on the service discovery mechanism, refer to RFC
433 2782.
434
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 [domain/FOO]
442 auth_provider = krb5
443 krb5_server = 192.168.1.1
444 krb5_realm = EXAMPLE.COM
445
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
456 The SSSD upstream - https://github.com/SSSD/sssd/
457SSSD 11/15/2023 SSSD-KRB5(5)