forked from cockpit-project/cockpit-project.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathcert-authentication.html
More file actions
276 lines (270 loc) · 15.8 KB
/
cert-authentication.html
File metadata and controls
276 lines (270 loc) · 15.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
---
layout: guide
---
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Certificate/smart card authentication</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Cockpit Guide">
<link rel="up" href="guide.html" title="Part I. Deployment Guide">
<link rel="prev" href="sso.html" title="Single Sign On">
<link rel="next" href="privileges.html" title="Privileges and Permissions">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="sso.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="guide.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Cockpit Guide</th>
<td><a accesskey="n" href="privileges.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="cert-authentication"></a>Certificate/smart card authentication</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="cert-authentication.html#certauth-server-cert-generation">User certificate generation</a></span></dt>
<dt><span class="section"><a href="cert-authentication.html#certauth-server-ipa">Certificate mapping with FreeIPA</a></span></dt>
<dt><span class="section"><a href="cert-authentication.html#certauth-server-ms-ad">Certificate mapping with Microsoft Active Directory</a></span></dt>
<dt><span class="section"><a href="cert-authentication.html#certauth-server-samba-ad">Certificate mapping with Samba Active Directory</a></span></dt>
<dt><span class="section"><a href="cert-authentication.html#certauth-server-cockpitconf">Cockpit web server configuration</a></span></dt>
<dt><span class="section"><a href="cert-authentication.html#certauth-server-resourcelimits">Cockpit web server resource limits</a></span></dt>
<dt><span class="section"><a href="cert-authentication.html#certauth-forwarding">Authentication to other services like sudo and ssh</a></span></dt>
</dl></div>
<p>
Cockpit can use TLS client certificates for authenticating users. Commonly
these are provided by a smart card, but it's equally possible to import
certificates directly into the web browser.
</p>
<p>
This requires the host to be in an Identity Management domain like
<a class="ulink" href="https://www.freeipa.org" target="_top">FreeIPA</a> or
<a class="ulink" href="https://en.wikipedia.org/wiki/Active_Directory" target="_top">Active Directory</a>,
which can associate certificates to users.
</p>
<p>To authenticate users from a Identity Management domain, the server that
Cockpit is running on must be joined to that domain. See the
<a class="link" href="sso.html#sso-server" title="Server Requirements">SSO server requirements</a> for details.</p>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="certauth-server-cert-generation"></a>User certificate generation</h2></div></div></div>
<p>Generating the certificates for users is usually done with a certificate management system like
<a class="ulink" href="https://pagure.io/certmonger" target="_top">certmonger</a> or
<a class="ulink" href="https://www.freeipa.org/page/PKI" target="_top">FreeIPA</a>, which are not documented here.
This command generates a simple key and certificate request for the "alice" user:</p>
<pre class="programlisting">
openssl req -new -newkey rsa:2048 -days 365 \
-keyout alice.key -out alice.csr -subj "/CN=alice"
</pre>
<p>Now get this certificate request signed by the Certificate Authority of your Identity
Management domain, to get a PEM certificate. Browsers and smart cart utilities accept PKCS#12 format
for importing/transfer, so convert the certificate/key pair; it will ask for and protect it
with a transfer password:</p>
<pre class="programlisting">
openssl pkcs12 -export -in alice.pem -inkey alice.key -out alice.p12
</pre>
<p>Don't forget to clean up the key file when you do not need it any more:</p>
<pre class="programlisting">
shred -u alice.key
</pre>
<p>You can now import <code class="code">alice.p12</code> directly into your browser,
with giving the transfer password set above. Or
<a class="ulink" href="https://linux.die.net/man/1/pkcs15-init" target="_top">put the certificate onto a smart card</a>:</p>
<pre class="programlisting">
pkcs15-init --store-private-key alice.p12 --format pkcs12 --auth-id 01
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="certauth-server-ipa"></a>Certificate mapping with FreeIPA</h2></div></div></div>
<p>The recommended method to sign a user certificate request and associate it to a user is
<span class="command"><strong>ipa cert-request</strong></span>: </p>
<pre class="programlisting">
ipa cert-request alice.csr --principal=alice --certificate-out=alice.pem
</pre>
<p>Alternatively, if you are using a different CA, you can use
<span class="command"><strong>ipa user-add-cert</strong></span> to associate the signed certificate to the user.
This expects PEM format, but without the <code class="code">-----BEGIN</code>/<code class="code">-----END</code>
markers:</p>
<pre class="programlisting">
ipa user-add-cert alice --certificate="$(grep -v ^---- alice.pem)"
</pre>
<p>See the <a class="ulink" href="https://www.freeipa.org/page/V4/User_Certificates#Feature_Management" target="_top">
FreeIPA User Certificates documentation</a> for details.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="certauth-server-ms-ad"></a>Certificate mapping with Microsoft Active Directory</h2></div></div></div>
<p>The domain user certificates get imported into the <code class="code">userCertificate;binary</code>
LDAP attribute. The following commands convert the PEM certificate into binary DER form, create an
<a class="ulink" href="https://ldap.com/ldif-the-ldap-data-interchange-format/" target="_top">LDIF</a>
file and apply it to the LDAP server running on the domain controller
"dc.example.com":</p>
<pre class="programlisting">
openssl x509 -outform der -in alice.pem -out alice.der
cat <<EOF > alice.ldif
version: 1
dn: cn=alice,ou=users,ou=YOUR_NETBIOS_NAME,dc=example,dc=com
changetype: modify
add: userCertificate;binary
userCertificate;binary:< file://$(pwd)/alice.der
EOF
ldapmodify -H ldap://dc.example.com -f alice.ldif
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="certauth-server-samba-ad"></a>Certificate mapping with Samba Active Directory</h2></div></div></div>
<p>At least some versions of <a class="ulink" href="https://www.samba.org/" target="_top">Samba</a>
do not support the <code class="code">userCertificate;binary</code> LDAP attribute, so the
import has to happen in base64 PEM form into the textual
<code class="code">userCertificate</code> attribute instead. Also, Samba uses a slightly
different user hierarchy:</p>
<pre class="programlisting">
cat <<EOF > alice.ldif
version: 1
dn: cn=alice,cn=users,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate: $(grep -v ^---- alice.pem | tr -d '\n')
EOF
ldapmodify -H ldap://dc.example.com -f alice.ldif
</pre>
<p>As <code class="code">userCertificate</code> is a text instead of binary field, you need to set up a
<a class="ulink" href="https://www.mankier.com/5/sssd.conf#Certificate_Mapping_Section" target="_top">certificate mapping rule</a>
in <span class="citerefentry"><span class="refentrytitle">sssd.conf</span>(5)</span>
in a <code class="code">[certmap/domain/rulename]</code> section, for example:</p>
<pre class="programlisting">
[certmap/example.com/adcerts]
# we match full certificates, so it is not important to check anything here
matchrule = <KU>digitalSignature
maprule = LDAP:(userCertificate={cert!base64})
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="certauth-server-cockpitconf"></a>Cockpit web server configuration</h2></div></div></div>
<p>Set the trusted Certificate Authority of your user certificates in <span class="command"><strong>sssd</strong></span>,
either by copying the CA PEM file to <code class="code">/etc/sssd/pki/sssd_auth_ca_db.pem</code> or setting the
<a class="ulink" href="https://www.mankier.com/5/sssd.conf#Services_Sections-PAM_configuration_options" target="_top">
<span class="command"><strong>pam_cert_db_path</strong></span></a> configuration option to the path of the CA.
If you use FreeIPA and its CA:</p>
<pre class="programlisting">
cp /etc/ipa/ca.crt /etc/sssd/pki/sssd_auth_ca_db.pem
</pre>
<p>Certificate authentication needs to be enabled in
<a class="ulink" href="./cockpit.conf.5.html" target="_top">cockpit.conf</a> explicitly:</p>
<pre class="programlisting">
[WebService]
ClientCertAuthentication = yes
</pre>
<p>When enabling this mode,
<a class="ulink" href="https://github.com/cockpit-project/cockpit/blob/main/doc/authentication.md" target="_top">
other authentication types</a> commonly get disabled, so that <span class="emphasis"><em>only</em></span>
client certificate authentication will be accepted. By default, after a failed certificate
authentication attempt, Cockpit's normal login page will appear and permit other login types
such as <code class="code">basic</code> (passwords) or <code class="code">negotiate</code> (Kerberos). For example,
password authentication gets disabled with:</p>
<pre class="programlisting">
[basic]
action = none
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="certauth-server-resourcelimits"></a>Cockpit web server resource limits</h2></div></div></div>
<p>When using certificate authentication, all requests with a particular
certificate will be handled by a separate and isolated instance of the
<a class="ulink" href="./cockpit-ws.8.html" target="_top">cockpit-ws</a> web server. This
protects against possible vulnerabilities in the web server and prevents
an attacker from impersonating another user. However, this introduces a
potential Denial of Service: Some remote attacker could create a
large number of certificates and send a large number of http requests
to Cockpit with these.</p>
<p>To mitigate that, all <code class="code">cockpit-ws</code> instances run
in a <code class="code">system-cockpithttps.slice</code>
<a class="ulink" href="https://www.freedesktop.org/software/systemd/man/systemd.slice.html" target="_top">systemd slice unit</a>
which <a class="ulink" href="https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html" target="_top">limits
the collective resources</a> of these web server instances: by default,
this slice sets a limit of 200 threads (roughly 100 instances of <code class="code">cockpit-ws</code> -- in other
words, a maximum of 100 parallel user sessions with different certificates) and
a 75% (soft)/90% (hard) memory limit.</p>
<p>You are welcome to adjust these limits to your need through
a <a class="ulink" href="https://www.freedesktop.org/software/systemd/man/systemd.unit.html" target="_top">drop-in</a>.
For example:</p>
<pre class="programlisting">
# systemctl edit system-cockpithttps.slice
[Slice]
# change existing value
TasksMax=100
# add new restriction
CPUQuota=30%
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="certauth-forwarding"></a>Authentication to other services like sudo and ssh</h2></div></div></div>
<p>Once you logged into Cockpit with a certificate, you likely need to switch to administrative mode
(root privileges through sudo), or connect to remote machines through SSH. If your user account has a password,
that can be used for authenticating to sudo or ssh as usual.</p>
<p><span class="emphasis"><em>Supported with FreeIPA only:</em></span> As an alternative to password authentication, you can
also declare the initial Cockpit certificate authentication as trusted for authenticating to SSH,
sudo, or other services. For that purpose, Cockpit automatically creates an
<a class="ulink" href="https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-sfu/bde93b0e-f3c9-4ddf-9f44-e1453be7af5a" target="_top">S4U2Proxy Kerberos ticket</a>
in the user session:
</p>
<pre class="programlisting">
$ klist
Ticket cache: FILE:/run/user/1894000001/cockpit-session-3692.ccache
Default principal: user@EXAMPLE.COM
Valid starting Expires Service principal
07/30/21 09:19:06 07/31/21 09:19:06 HTTP/myhost.example.com@EXAMPLE.COM
07/30/21 09:19:06 07/31/21 09:19:06 krbtgt/EXAMPLE.COM@EXAMPLE.COM
for client HTTP/myhost.example.com@EXAMPLE.COM
</pre>
<p>You can set up <a class="ulink" href="https://www.freeipa.org/page/V4/Service_Constraint_Delegation" target="_top">constrained delegation rules</a>
to enumerate which hosts (including its own) that ticket is trusted to access. For example, if the cockpit session runs on host
<code class="code">myhost.example.com</code> and should be trusted to access its own host (through sudo) and another host
<code class="code">remote.example.com</code> (through ssh), create a delegation like this:
</p>
<pre class="programlisting">
# a list of target machines which can be accessed by a particular rule
ipa servicedelegationtarget-add cockpit-target
ipa servicedelegationtarget-add-member cockpit-target \
--principals=host/myhost.example.com@EXAMPLE.COM \
--principals=host/remote.example.com@EXAMPLE.COM
# allow cockpit sessions (HTTP/ principal) to access that host list
ipa servicedelegationrule-add cockpit-delegation
ipa servicedelegationrule-add-member cockpit-delegation \
--principals=HTTP/myhost.example.com@EXAMPLE.COM
ipa servicedelegationrule-add-target cockpit-delegation \
--servicedelegationtargets=cockpit-target
</pre>
<p>In addition, you need to enable GSS (Kerberos) authentication in the corresponding services.</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>For SSH, enable <code class="code">GSSAPIAuthentication yes</code> in
<a class="ulink" href="https://linux.die.net/man/5/sshd_config" target="_top">/etc/ssh/sshd_config</a>.</p></li>
<li class="listitem">
<p>For sudo, enable <code class="code">pam_sss_gss</code> as described in the
<a class="ulink" href="https://www.mankier.com/8/pam_sss_gss" target="_top">manpage</a>:
In <code class="code">/etc/sssd/sssd.conf</code>: Add an entry for your domain:</p>
<pre class="programlisting">
[domain/example.com]
pam_gssapi_services = sudo, sudo-i
</pre>
<p>In <code class="code">/etc/pam.d/sudo</code>, enable the module in the first line:</p>
<pre class="programlisting">
auth sufficient pam_sss_gss.so
</pre>
</li>
</ul></div>
<p><span class="emphasis"><em>Caveat:</em></span> The delegated S4U ticket is not yet forwarded to remote SSH
hosts when connecting to them from Cockpit, so authenticating to sudo on the remote host with
that ticket does not work. This will be provided in a future version.</p>
</div>
</div>
<div class="footer"><hr></div>
</body>
</html>