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
|
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="cert-authentication">
<title>Certificate/smart card authentication</title>
<para>
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.
</para>
<para>
This requires the host to be in an Identity Management domain like
<ulink url="https://www.freeipa.org">FreeIPA</ulink> or
<ulink url="https://en.wikipedia.org/wiki/Active_Directory">Active Directory</ulink>,
which can associate certificates to users.
</para>
<para>To authenticate users from a Identity Management domain, the server that
Cockpit is running on must be joined to that domain. See the
<link linkend="sso-server">SSO server requirements</link> for details.</para>
<section id="certauth-server-cert-generation">
<title>User certificate generation</title>
<para>Generating the certificates for users is usually done with a certificate management system like
<ulink url="https://pagure.io/certmonger">certmonger</ulink> or
<ulink url="https://www.freeipa.org/page/PKI">FreeIPA</ulink>, which are not documented here.
For testing purposes, these commands will generate a self-signed certificate/key for the "alice" user:</para>
<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
</programlisting>
<para>You can now import <code>alice.p12</code> directly into your browser,
with giving the transfer password set above. Or
<ulink url="https://linux.die.net/man/1/pkcs15-init">put the certificate onto a smart card</ulink>:</para>
<programlisting>
pkcs15-init --store-private-key alice.p12 --format pkcs12 --auth-id 01
</programlisting>
</section>
<section id="certauth-server-ipa">
<title>Certificate mapping with FreeIPA</title>
<para>The domain's users get associated to certificates with
the <command>ipa user-add-cert</command> command. This expects PEM format, but without the
<code>-----BEGIN</code>/<code>-----END</code> markers. See the
<ulink url="https://www.freeipa.org/page/V4/User_Certificates#Feature_Management">
FreeIPA User Certificates documentation</ulink>:</para>
<programlisting>
ipa user-add-cert alice --certificate="$(grep -v ^---- alice.pem)"
</programlisting>
</section>
<section id="certauth-server-ms-ad">
<title>Certificate mapping with Microsoft Active Directory</title>
<para>The domain user certificates get imported into the <code>userCertificate;binary</code>
LDAP attribute. The following commands convert the PEM certificate into binary DER form, create an
<ulink url="https://ldap.com/ldif-the-ldap-data-interchange-format/">LDIF</ulink>
file and apply it to the LDAP server running on the domain contoller
"dc.example.com":</para>
<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
</programlisting>
</section>
<section id="certauth-server-samba-ad">
<title>Certificate mapping with Samba Active Directory</title>
<para>At least some versions of <ulink url="https://www.samba.org/">Samba</ulink>
do not support the <code>userCertificate;binary</code> LDAP attribute, so the
import has to happen in base64 PEM form into the textual
<code>userCertificate</code> attribute instead. Also, Samba uses a slightly
different user hierarchy:</para>
<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
</programlisting>
<para>As <code>userCertificate</code> is a text instead of binary field, you need to set up a
<ulink url="https://www.mankier.com/5/sssd.conf#Certificate_Mapping_Section">certificate mapping rule</ulink>
in <citerefentry><refentrytitle>sssd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
in a <code>[certmap/domain/rulename]</code> section, for example:</para>
<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})
</programlisting>
</section>
<section id="certauth-server-cockpitconf">
<title>Cockpit web server configuration</title>
<para>Certificate authentication needs to be enabled in
<ulink url="./cockpit.conf.5.html">cockpit.conf</ulink> explicitly:</para>
<programlisting>
[WebService]
ClientCertAuthentication = yes
</programlisting>
<warning>
<para>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.
<emphasis>Do not use this with local sssd <code>certmap</code> rules</emphasis>
which only match on Subject/Issuer properties!
</para>
</warning>
<para>When enabling this mode,
<ulink url="https://github.com/cockpit-project/cockpit/blob/master/doc/authentication.md">
other authentication types</ulink> commonly get disabled, so that <emphasis>only</emphasis>
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>basic</code> (passwords) or <code>negotiate</code> (Kerberos). For example,
password authentication gets disabled with:</para>
<programlisting>
[basic]
action = none
</programlisting>
</section>
<section id="certauth-server-resourcelimits">
<title>Cockpit web server resource limits</title>
<para>When using certificate authentication, all requests with a particular
certificate will be handled by a separate and isolated instance of the
<ulink url="./cockpit-ws.8.html">cockpit-ws</ulink> 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.</para>
<para>To mitigate that, all <code>cockpit-ws</code> instances run
in a <code>system-cockpithttps.slice</code>
<ulink url="https://www.freedesktop.org/software/systemd/man/systemd.slice.html">systemd slice unit</ulink>
which <ulink url="https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html">limits
the collective resources</ulink> of these web server instances: by default,
this slice sets a limit of 200 threads (roughly 100 instances of <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.</para>
<para>You are welcome to adjust these limits to your need through
a <ulink url="https://www.freedesktop.org/software/systemd/man/systemd.unit.html">drop-in</ulink>.
For example:</para>
<programlisting>
# systemctl edit system-cockpithttps.slice
[Slice]
# change existing value
TasksMax=100
# add new restriction
CPUQuota=30%
</programlisting>
</section>
</chapter>
|
