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.
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 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_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 Default: 6
135 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 Default: false
146 krb5_keytab (string)
148 The location of the keytab to use when validating credentials
149 obtained from KDCs.
150 Default: /etc/krb5.keytab
152 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 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 Default: false
162 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 s for seconds
169 m for minutes
172 h for hours
175 d for days.
178 If there is no unit given, s is assumed.
180 NOTE: It is not possible to mix units. To set the renewable
182 lifetime to one and a half hours, use ´90m´ instead of ´1h30m´.
183 Default: not set, i.e. the TGT is not renewable
185 krb5_lifetime (string)
187 Request ticket with a lifetime, given as an integer immediately
188 followed by a time unit:
189 s for seconds
192 m for minutes
195 h for hours
198 d for days.
201 If there is no unit given s is assumed.
203 NOTE: It is not possible to mix units. To set the lifetime to one
205 and a half hours please use ´90m´ instead of ´1h30m´.
206 Default: not set, i.e. the default ticket lifetime configured on
208 the KDC.
209 krb5_renew_interval (string)
211 The time in seconds between two checks if the TGT should be
212 renewed. TGTs are renewed if about half of their lifetime is
213 exceeded, given as an integer immediately followed by a time unit:
214 s for seconds
217 m for minutes
220 h for hours
223 d for days.
226 If there is no unit given, s is assumed.
228 NOTE: It is not possible to mix units. To set the renewable
230 lifetime to one and a half hours, use ´90m´ instead of ´1h30m´.
231 If this option is not set or is 0 the automatic renewal is
233 disabled.
234 Default: not set
236 krb5_use_fast (string)
238 Enables flexible authentication secure tunneling (FAST) for
239 Kerberos pre-authentication. The following options are supported:
240 never use FAST. This is equivalent to not setting this option at
243 all.
244 try to use FAST. If the server does not support FAST, continue the
247 authentication without it.
248 demand to use FAST. The authentication fails if the server does not
251 require fast.
252 Default: not set, i.e. FAST is not used.
254 NOTE: a keytab is required to use FAST.
256 NOTE: SSSD supports FAST only with MIT Kerberos version 1.8 and
258 later. If SSSD is used with an older version of MIT Kerberos, using
259 this option is a configuration error.
260 krb5_fast_principal (string)
262 Specifies the server principal to use for FAST.
263 krb5_canonicalize (boolean)
265 Specifies if the host and user principal should be canonicalized.
266 This feature is available with MIT Kerberos 1.7 and later versions.
267 Default: false
269 krb5_use_kdcinfo (boolean)
271 Specifies if the SSSD should instruct the Kerberos libraries what
272 realm and which KDCs to use. This option is on by default, if you
273 disable it, you need to configure the Kerberos library using the
274 krb5.conf(5) configuration file.
275 See the sssd_krb5_locator_plugin(8) manual page for more
277 information on the locator plugin.
278 Default: true
280 krb5_use_enterprise_principal (boolean)
282 Specifies if the user principal should be treated as enterprise
283 principal. See section 5 of RFC 6806 for more details about
284 enterprise principals.
285 Default: false (AD provider: true)
287 krb5_map_user (string)
289 The list of mappings is given as a comma-separated list of pairs
290 “username:primary” where “username” is a UNIX user name and
291 “primary” is a user part of a kerberos principal. This mapping is
292 used when user is authenticating using “auth_provider = krb5”.
293 example:
295 krb5_realm = REALM
297 krb5_map_user = joe:juser,dick:richard
298 “joe” and “dick” are UNIX user names and “juser” and “richard” are
301 primaries of kerberos principals. For user “joe” resp. “dick” SSSD
302 will try to kinit as “juser@REALM” resp. “richard@REALM”.
303 Default: not set
305
307 The failover feature allows back ends to automatically switch to a
308 different server if the current server fails.
309 Failover Syntax
311 The list of servers is given as a comma-separated list; any number of
312 spaces is allowed around the comma. The servers are listed in order of
313 preference. The list can contain any number of servers.
314 For each failover-enabled config option, two variants exist: primary
316 and backup. The idea is that servers in the primary list are preferred
317 and backup servers are only searched if no primary servers can be
318 reached. If a backup server is selected, a timeout of 31 seconds is
319 set. After this timeout SSSD will periodically try to reconnect to one
320 of the primary servers. If it succeeds, it will replace the current
321 active (backup) server.
322 The Failover Mechanism
324 The failover mechanism distinguishes between a machine and a service.
325 The back end first tries to resolve the hostname of a given machine; if
326 this resolution attempt fails, the machine is considered offline. No
327 further attempts are made to connect to this machine for any other
328 service. If the resolution attempt succeeds, the back end tries to
329 connect to a service on this machine. If the service connection attempt
330 fails, then only this particular service is considered offline and the
331 back end automatically switches over to the next service. The machine
332 is still considered online and might still be tried for another
333 service.
334 Further connection attempts are made to machines or services marked as
336 offline after a specified period of time; this is currently hard coded
337 to 30 seconds.
338 If there are no more machines to try, the back end as a whole switches
340 to offline mode, and then attempts to reconnect every 30 seconds.
341
343 The service discovery feature allows back ends to automatically find
344 the appropriate servers to connect to using a special DNS query. This
345 feature is not supported for backup servers.
346 Configuration
348 If no servers are specified, the back end automatically uses service
349 discovery to try to find a server. Optionally, the user may choose to
350 use both fixed server addresses and service discovery by inserting a
351 special keyword, “_srv_”, in the list of servers. The order of
352 preference is maintained. This feature is useful if, for example, the
353 user prefers to use service discovery whenever possible, and fall back
354 to a specific server when no servers can be discovered using DNS.
355 The domain name
357 Please refer to the “dns_discovery_domain” parameter in the
358 sssd.conf(5) manual page for more details.
359 The protocol
361 The queries usually specify _tcp as the protocol. Exceptions are
362 documented in respective option description.
363 See Also
365 For more information on the service discovery mechanism, refer to RFC
366 2782.
367
369 The following example assumes that SSSD is correctly configured and FOO
370 is one of the domains in the [sssd] section. This example shows only
371 configuration of Kerberos authentication; it does not include any
372 identity provider.
373 [domain/FOO]
375 auth_provider = krb5
376 krb5_server = 192.168.1.1
377 krb5_realm = EXAMPLE.COM
378
381 sssd(8), sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
382 sssd-ipa(5), sssd-ad(5), sssd-sudo(5), sss_cache(8), sss_debuglevel(8),
383 sss_groupadd(8), sss_groupdel(8), sss_groupshow(8), sss_groupmod(8),
384 sss_useradd(8), sss_userdel(8), sss_usermod(8), sss_obfuscate(8),
385 sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
386 sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5)
387
389 The SSSD upstream - http://fedorahosted.org/sssd
390SSSD 01/15/2019 SSSD-KRB5(5)