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.
25       Please note that an empty .k5login file will deny all access to this
26       user. To activate this feature, use 'access_provider = krb5' in your
27       SSSD 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_auth_timeout (integer)
130           Timeout in seconds after an online authentication request or change
131           password request is aborted. If possible, the authentication
132           request is continued offline.
133
134           Default: 6
135
136       krb5_validate (boolean)
137           Verify with the help of krb5_keytab that the TGT obtained has not
138           been spoofed. The keytab is checked for entries sequentially, and
139           the first entry with a matching realm is used for validation. If no
140           entry matches the realm, the last entry in the keytab is used. This
141           process can be used to validate environments using cross-realm
142           trust by placing the appropriate keytab entry as the last entry or
143           the only entry in the keytab file.
144
145           Default: false
146
147       krb5_keytab (string)
148           The location of the keytab to use when validating credentials
149           obtained from KDCs.
150
151           Default: /etc/krb5.keytab
152
153       krb5_store_password_if_offline (boolean)
154           Store the password of the user if the provider is offline and use
155           it to request a TGT when the provider comes online again.
156
157           NOTE: this feature is only available on Linux. Passwords stored in
158           this way are kept in plaintext in the kernel keyring and are
159           potentially accessible by the root user (with difficulty).
160
161           Default: false
162
163       krb5_renewable_lifetime (string)
164           Request a renewable ticket with a total lifetime, given as an
165           integer immediately followed by a time unit:
166
167           s for seconds
168
169           m for minutes
170
171           h for hours
172
173           d for days.
174
175           If there is no unit given, s is assumed.
176
177           NOTE: It is not possible to mix units. To set the renewable
178           lifetime to one and a half hours, use '90m' instead of '1h30m'.
179
180           Default: not set, i.e. the TGT is not renewable
181
182       krb5_lifetime (string)
183           Request ticket with a lifetime, given as an integer immediately
184           followed by a time unit:
185
186           s for seconds
187
188           m for minutes
189
190           h for hours
191
192           d for days.
193
194           If there is no unit given s is assumed.
195
196           NOTE: It is not possible to mix units. To set the lifetime to one
197           and a half hours please use '90m' instead of '1h30m'.
198
199           Default: not set, i.e. the default ticket lifetime configured on
200           the KDC.
201
202       krb5_renew_interval (string)
203           The time in seconds between two checks if the TGT should be
204           renewed. TGTs are renewed if about half of their lifetime is
205           exceeded, given as an integer immediately followed by a time unit:
206
207           s for seconds
208
209           m for minutes
210
211           h for hours
212
213           d for days.
214
215           If there is no unit given, s is assumed.
216
217           NOTE: It is not possible to mix units. To set the renewable
218           lifetime to one and a half hours, use '90m' instead of '1h30m'.
219
220           If this option is not set or is 0 the automatic renewal is
221           disabled.
222
223           Default: not set
224
225       krb5_use_fast (string)
226           Enables flexible authentication secure tunneling (FAST) for
227           Kerberos pre-authentication. The following options are supported:
228
229           never use FAST. This is equivalent to not setting this option at
230           all.
231
232           try to use FAST. If the server does not support FAST, continue the
233           authentication without it.
234
235           demand to use FAST. The authentication fails if the server does not
236           require fast.
237
238           Default: not set, i.e. FAST is not used.
239
240           NOTE: a keytab is required to use FAST.
241
242           NOTE: SSSD supports FAST only with MIT Kerberos version 1.8 and
243           later. If SSSD is used with an older version of MIT Kerberos, using
244           this option is a configuration error.
245
246       krb5_fast_principal (string)
247           Specifies the server principal to use for FAST.
248
249       krb5_canonicalize (boolean)
250           Specifies if the host and user principal should be canonicalized.
251           This feature is available with MIT Kerberos 1.7 and later versions.
252
253           Default: false
254
255       krb5_use_kdcinfo (boolean)
256           Specifies if the SSSD should instruct the Kerberos libraries what
257           realm and which KDCs to use. This option is on by default, if you
258           disable it, you need to configure the Kerberos library using the
259           krb5.conf(5) configuration file.
260
261           See the sssd_krb5_locator_plugin(8) manual page for more
262           information on the locator plugin.
263
264           Default: true
265
266       krb5_use_enterprise_principal (boolean)
267           Specifies if the user principal should be treated as enterprise
268           principal. See section 5 of RFC 6806 for more details about
269           enterprise principals.
270
271           Default: false (AD provider: true)
272
273           The IPA provider will set to option to 'true' if it detects that
274           the server is capable of handling enterprise principals and the
275           option is not set explicitly in the config file.
276
277       krb5_map_user (string)
278           The list of mappings is given as a comma-separated list of pairs
279           “username:primary” where “username” is a UNIX user name and
280           “primary” is a user part of a kerberos principal. This mapping is
281           used when user is authenticating using “auth_provider = krb5”.
282
283           example:
284
285               krb5_realm = REALM
286               krb5_map_user = joe:juser,dick:richard
287
288           “joe” and “dick” are UNIX user names and “juser” and “richard” are
289           primaries of kerberos principals. For user “joe” resp.  “dick” SSSD
290           will try to kinit as “juser@REALM” resp.  “richard@REALM”.
291
292           Default: not set
293

FAILOVER

295       The failover feature allows back ends to automatically switch to a
296       different server if the current server fails.
297
298   Failover Syntax
299       The list of servers is given as a comma-separated list; any number of
300       spaces is allowed around the comma. The servers are listed in order of
301       preference. The list can contain any number of servers.
302
303       For each failover-enabled config option, two variants exist: primary
304       and backup. The idea is that servers in the primary list are preferred
305       and backup servers are only searched if no primary servers can be
306       reached. If a backup server is selected, a timeout of 31 seconds is
307       set. After this timeout SSSD will periodically try to reconnect to one
308       of the primary servers. If it succeeds, it will replace the current
309       active (backup) server.
310
311   The Failover Mechanism
312       The failover mechanism distinguishes between a machine and a service.
313       The back end first tries to resolve the hostname of a given machine; if
314       this resolution attempt fails, the machine is considered offline. No
315       further attempts are made to connect to this machine for any other
316       service. If the resolution attempt succeeds, the back end tries to
317       connect to a service on this machine. If the service connection attempt
318       fails, then only this particular service is considered offline and the
319       back end automatically switches over to the next service. The machine
320       is still considered online and might still be tried for another
321       service.
322
323       Further connection attempts are made to machines or services marked as
324       offline after a specified period of time; this is currently hard coded
325       to 30 seconds.
326
327       If there are no more machines to try, the back end as a whole switches
328       to offline mode, and then attempts to reconnect every 30 seconds.
329
330   Failover time outs and tuning
331       Resolving a server to connect to can be as simple as running a single
332       DNS query or can involve several steps, such as finding the correct
333       site or trying out multiple host names in case some of the configured
334       servers are not reachable. The more complex scenarios can take some
335       time and SSSD needs to balance between providing enough time to finish
336       the resolution process but on the other hand, not trying for too long
337       before falling back to offline mode. If the SSSD debug logs show that
338       the server resolution is timing out before a live server is contacted,
339       you can consider changing the time outs.
340
341       This section lists the available tunables. Please refer to their
342       description in the sssd.conf(5), manual page.
343
344       dns_resolver_op_timeout
345           How long would SSSD talk to a single DNS server.
346
347       dns_resolver_timeout
348           How long would SSSD try to resolve a failover service. This service
349           resolution internally might include several steps, such as
350           resolving DNS SRV queries or locating the site.
351
352       For LDAP-based providers, the resolve operation is performed as part of
353       an LDAP connection operation. Therefore, also the “ldap_opt_timeout>”
354       timeout should be set to a larger value than “dns_resolver_timeout”
355       which in turn should be set to a larger value than
356       “dns_resolver_op_timeout”.
357

SERVICE DISCOVERY

359       The service discovery feature allows back ends to automatically find
360       the appropriate servers to connect to using a special DNS query. This
361       feature is not supported for backup servers.
362
363   Configuration
364       If no servers are specified, the back end automatically uses service
365       discovery to try to find a server. Optionally, the user may choose to
366       use both fixed server addresses and service discovery by inserting a
367       special keyword, “_srv_”, in the list of servers. The order of
368       preference is maintained. This feature is useful if, for example, the
369       user prefers to use service discovery whenever possible, and fall back
370       to a specific server when no servers can be discovered using DNS.
371
372   The domain name
373       Please refer to the “dns_discovery_domain” parameter in the
374       sssd.conf(5) manual page for more details.
375
376   The protocol
377       The queries usually specify _tcp as the protocol. Exceptions are
378       documented in respective option description.
379
380   See Also
381       For more information on the service discovery mechanism, refer to RFC
382       2782.
383

EXAMPLE

385       The following example assumes that SSSD is correctly configured and FOO
386       is one of the domains in the [sssd] section. This example shows only
387       configuration of Kerberos authentication; it does not include any
388       identity provider.
389
390           [domain/FOO]
391           auth_provider = krb5
392           krb5_server = 192.168.1.1
393           krb5_realm = EXAMPLE.COM
394
395

SEE ALSO

397       sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
398       sssd-ipa(5), sssd-ad(5), sssd-sudo(5), sssd-session-recording(5),
399       sss_cache(8), sss_debuglevel(8), sss_obfuscate(8), sss_seed(8),
400       sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
401       sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8).  sss_rpcidmapd(5)
402       sssd-systemtap(5)
403

AUTHORS

405       The SSSD upstream - https://pagure.io/SSSD/sssd/
406
407
408
409SSSD                              07/01/2019                      SSSD-KRB5(5)
Impressum