1SSSD-KCM(8) File Formats and Conventions SSSD-KCM(8)
2
6 sssd-kcm - SSSD Kerberos Cache Manager
7
9 This manual page describes the configuration of the SSSD Kerberos Cache
10 Manager (KCM). KCM is a process that stores, tracks and manages
11 Kerberos credential caches. It originates in the Heimdal Kerberos
12 project, although the MIT Kerberos library also provides client side
13 (more details on that below) support for the KCM credential cache.
14 In a setup where Kerberos caches are managed by KCM, the Kerberos
16 library (typically used through an application, like e.g., kinit(1), is
17 a “"KCM client"” and the KCM daemon is being referred to as a “"KCM
18 server"”. The client and server communicate over a UNIX socket.
19 The KCM server keeps track of each credential caches's owner and
21 performs access check control based on the UID and GID of the KCM
22 client. The root user has access to all credential caches.
23 The KCM credential cache has several interesting properties:
25 • since the process runs in userspace, it is subject to UID
27 namespacing, unlike the kernel keyring
28 • unlike the kernel keyring-based cache, which is shared between all
30 containers, the KCM server is a separate process whose entry point
31 is a UNIX socket
32 • the SSSD implementation stores the ccaches in a database, typically
34 located at /var/lib/sss/secrets allowing the ccaches to survive KCM
35 server restarts or machine reboots.
36 This allows the system to use a collection-aware credential cache, yet
38 share the credential cache between some or no containers by
39 bind-mounting the socket.
40 The KCM default client idle timeout is 5 minutes, this allows more time
42 for user interaction with command line tools such as kinit.
43
45 In order to use KCM credential cache, it must be selected as the
46 default credential type in krb5.conf(5), The credentials cache name
47 must be only “KCM:” without any template expansions. For example:
48 [libdefaults]
50 default_ccache_name = KCM:
51 Next, make sure the Kerberos client libraries and the KCM server must
54 agree on the UNIX socket path. By default, both use the same path
55 /var/run/.heim_org.h5l.kcm-socket. To configure the Kerberos library,
56 change its “kcm_socket” option which is described in the krb5.conf(5)
57 manual page.
58 Finally, make sure the SSSD KCM server can be contacted. The KCM
60 service is typically socket-activated by systemd(1). Unlike other SSSD
61 services, it cannot be started by adding the “kcm” string to the
62 “service” directive.
63 systemctl start sssd-kcm.socket
65 systemctl enable sssd-kcm.socket
66 Please note your distribution may already configure the units for you.
69
71 The credential caches are stored in a database, much like SSSD caches
72 user or group entries. The database is typically located at
73 “/var/lib/sss/secrets”.
74
76 The sssd-kcm service is typically socket-activated systemd(1). To
77 generate debug logs, add the following either to the
78 /etc/sssd/sssd.conf file directly or as a configuration snippet to
79 /etc/sssd/conf.d/ directory:
80 [kcm]
82 debug_level = 10
83 Then, restart the sssd-kcm service:
86 systemctl restart sssd-kcm.service
88 Finally, run whatever use-case doesn't work for you. The KCM logs will
91 be generated at /var/log/sssd/sssd_kcm.log. It is recommended to
92 disable the debug logs when you no longer need the debugging to be
93 enabled as the sssd-kcm service can generate quite a large amount of
94 debugging information.
95 Please note that configuration snippets are, at the moment, only
97 processed if the main configuration file at /etc/sssd/sssd.conf exists
98 at all.
99
101 The sssd-kcm service can be configured to attempt TGT renewal for
102 renewable TGTs stored in the KCM ccache. Renewals are only attempted
103 when half of the ticket lifetime has been reached. KCM Renewals are
104 configured when the following options are set in the [kcm] section:
105 tgt_renewal = true
107 krb5_renew_interval = 60m
108 SSSD can also inherit krb5 options for renewals from an existing
111 domain.
112 tgt_renewal = true
114 tgt_renewal_inherit = domain-name
115 The following krb5 options can be configured in the [kcm] section to
118 control renewal behavior, these options are described in detail below
119 krb5_renew_interval
121 krb5_renewable_lifetime
122 krb5_lifetime
123 krb5_validate
124 krb5_canonicalize
125 krb5_auth_timeout
126
130 The KCM service is configured in the “kcm” section of the sssd.conf
131 file. Please note that because the KCM service is typically
132 socket-activated, it is enough to just restart the “sssd-kcm” service
133 after changing options in the “kcm” section of sssd.conf:
134 systemctl restart sssd-kcm.service
136 The KCM service is configured in the “kcm” For a detailed syntax
139 reference, refer to the “FILE FORMAT” section of the sssd.conf(5)
140 manual page.
141 The generic SSSD service options such as “debug_level” or “fd_limit”
143 are accepted by the kcm service. Please refer to the sssd.conf(5)
144 manual page for a complete list. In addition, there are some
145 KCM-specific options as well.
146 socket_path (string)
148 The socket the KCM service will listen on.
149 Default: /var/run/.heim_org.h5l.kcm-socket
151 Note: on platforms where systemd is supported, the socket path is
153 overwritten by the one defined in the sssd-kcm.socket unit file.
154 max_ccaches (integer)
156 How many credential caches does the KCM database allow for all
157 users.
158 Default: 0 (unlimited, only the per-UID quota is enforced)
160 max_uid_ccaches (integer)
162 How many credential caches does the KCM database allow per UID.
163 This is equivalent to “with how many principals you can kinit”.
164 Default: 64
166 max_ccache_size (integer)
168 How big can a credential cache be per ccache. Each service ticket
169 accounts into this quota.
170 Default: 65536
172 tgt_renewal (bool)
174 Enables TGT renewals functionality.
175 Default: False (Automatic renewals disabled)
177 tgt_renewal_inherit (string)
179 Domain to inherit krb5_* options from, for use with TGT renewals.
180 Default: NULL
182 krb5_auth_timeout (integer)
184 Timeout in seconds after an online authentication request or change
185 password request is aborted. If possible, the authentication
186 request is continued offline.
187 Default: 6
189 krb5_validate (boolean)
191 Verify with the help of krb5_keytab that the TGT obtained has not
192 been spoofed. The keytab is checked for entries sequentially, and
193 the first entry with a matching realm is used for validation. If no
194 entry matches the realm, the last entry in the keytab is used. This
195 process can be used to validate environments using cross-realm
196 trust by placing the appropriate keytab entry as the last entry or
197 the only entry in the keytab file.
198 Default: false (IPA and AD provider: true)
200 Please note that the ticket validation is the first step when
202 checking the PAC (see 'pac_check' in the sssd.conf(5) manual page
203 for details). If ticket validation is disabled the PAC checks will
204 be skipped as well.
205 krb5_renewable_lifetime (string)
207 Request a renewable ticket with a total lifetime, given as an
208 integer immediately followed by a time unit:
209 s for seconds
211 m for minutes
213 h for hours
215 d for days.
217 If there is no unit given, s is assumed.
219 NOTE: It is not possible to mix units. To set the renewable
221 lifetime to one and a half hours, use '90m' instead of '1h30m'.
222 Default: not set, i.e. the TGT is not renewable
224 krb5_lifetime (string)
226 Request ticket with a lifetime, given as an integer immediately
227 followed by a time unit:
228 s for seconds
230 m for minutes
232 h for hours
234 d for days.
236 If there is no unit given s is assumed.
238 NOTE: It is not possible to mix units. To set the lifetime to one
240 and a half hours please use '90m' instead of '1h30m'.
241 Default: not set, i.e. the default ticket lifetime configured on
243 the KDC.
244 krb5_renew_interval (string)
246 The time in seconds between two checks if the TGT should be
247 renewed. TGTs are renewed if about half of their lifetime is
248 exceeded, given as an integer immediately followed by a time unit:
249 s for seconds
251 m for minutes
253 h for hours
255 d for days.
257 If there is no unit given, s is assumed.
259 NOTE: It is not possible to mix units. To set the renewable
261 lifetime to one and a half hours, use '90m' instead of '1h30m'.
262 If this option is not set or is 0 the automatic renewal is
264 disabled.
265 Default: not set
267 krb5_canonicalize (boolean)
269 Specifies if the host and user principal should be canonicalized.
270 This feature is available with MIT Kerberos 1.7 and later versions.
271 Default: false
273
275 sssd(8), sssd.conf(5),
276
278 The SSSD upstream - https://github.com/SSSD/sssd/
279SSSD 12/09/2022 SSSD-KCM(8)