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
|
<!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>
</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.
For testing purposes, these commands will generate a self-signed certificate/key for the "alice" user:</p>
<pre class="programlisting">
# create self-signed certificate and key
# some browsers insist on specifying key usage, so it needs a config file
printf '[req]\ndistinguished_name=dn\nextensions=v3_req\n[dn]\n
[v3_req]\nkeyUsage=digitalSignature,keyEncipherment,keyAgreement\n' > /tmp/openssl.cnf
openssl req -x509 -newkey rsa:2048 -days 365 -nodes -keyout alice.key \
-out alice.pem -subj "/CN=alice" -config /tmp/openssl.cnf -extensions v3_req
# browsers and smart cart utilities accept PKCS#12 format, convert it
# this needs to set a transfer/import password
openssl pkcs12 -export -password pass:somepassword \
-in alice.pem -inkey alice.key -out alice.p12
</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 domain's users get associated to certificates with
the <span class="command"><strong>ipa user-add-cert</strong></span> command. This expects PEM format, but without the
<code class="code">-----BEGIN</code>/<code class="code">-----END</code> markers. See the
<a class="ulink" href="https://www.freeipa.org/page/V4/User_Certificates#Feature_Management" target="_top">
FreeIPA User Certificates documentation</a>:</p>
<pre class="programlisting">
ipa user-add-cert alice --certificate="$(grep -v ^---- alice.pem)"
</pre>
</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 contoller
"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>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>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p>Any client can generate certificates with arbitrary information, thus
the client certificates must be checked for validity. Cockpit currently
accepts any client certificate and relies on sssd to verify their validity.
This is secure only when the entire certificate gets matched, i.e. when
importing the complete certificates into Identity Management as shown above.
<span class="emphasis"><em>Do not use this with local sssd <code class="code">certmap</code> rules</em></span>
which only match on Subject/Issuer properties!
</p>
</div>
<p>When enabling this mode,
<a class="ulink" href="https://github.com/cockpit-project/cockpit/blob/master/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>
<div class="footer"><hr></div>
</body>
</html>
|
