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.
This requires the host to be in an Identity Management domain like FreeIPA or Active Directory, which can associate certificates to users.
To authenticate users from a Identity Management domain, the server that Cockpit is running on must be joined to that domain. See the SSO server requirements for details.
Generating the certificates for users is usually done with a certificate management system like certmonger or FreeIPA, which are not documented here. For testing purposes, these commands will generate a self-signed certificate/key for the "alice" user:
# 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
You can now import alice.p12 directly into your browser,
with giving the transfer password set above. Or
put the certificate onto a smart card:
pkcs15-init --store-private-key alice.p12 --format pkcs12 --auth-id 01
The domain's users get associated to certificates with
the ipa user-add-cert command. This expects PEM format, but without the
-----BEGIN/-----END markers. See the
FreeIPA User Certificates documentation:
ipa user-add-cert alice --certificate="$(grep -v ^---- alice.pem)"
The domain user certificates get imported into the userCertificate;binary
LDAP attribute. The following commands convert the PEM certificate into binary DER form, create an
LDIF
file and apply it to the LDAP server running on the domain contoller
"dc.example.com":
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
At least some versions of Samba
do not support the userCertificate;binary LDAP attribute, so the
import has to happen in base64 PEM form into the textual
userCertificate attribute instead. Also, Samba uses a slightly
different user hierarchy:
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
As userCertificate is a text instead of binary field, you need to set up a
certificate mapping rule
in sssd.conf(5)
in a [certmap/domain/rulename] section, for example:
[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})
Certificate authentication needs to be enabled in cockpit.conf explicitly:
[WebService] ClientCertAuthentication = yes
Warning
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.
Do not use this with local sssd certmap rules
which only match on Subject/Issuer properties!
When enabling this mode,
other authentication types commonly get disabled, so that only
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 basic (passwords) or negotiate (Kerberos). For example,
password authentication gets disabled with:
[basic] action = none
When using certificate authentication, all requests with a particular certificate will be handled by a separate and isolated instance of the cockpit-ws 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.
To mitigate that, all cockpit-ws instances run
in a system-cockpithttps.slice
systemd slice unit
which limits
the collective resources of these web server instances: by default,
this slice sets a limit of 200 threads (roughly 100 instances of cockpit-ws -- in other
words, a maximum of 100 parallel user sessions with different certificates) and
a 75% (soft)/90% (hard) memory limit.
You are welcome to adjust these limits to your need through a drop-in. For example:
# systemctl edit system-cockpithttps.slice [Slice] # change existing value TasksMax=100 # add new restriction CPUQuota=30%
Once you logged into Cockpit with a certificate, you likely need to switch to administative 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.
Supported with FreeIPA only: 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 S4U2Proxy Kerberos ticket in the user session:
$ 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
You can set up constrained delegation rules
to enumerate which hosts (including its own) that ticket is trusted to access. For example, if the cockpit session runs on host
myhost.example.com and should be trusted to access its own host (through sudo) and another host
remote.example.com (through ssh), create a delegation like this:
# 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
In addition, you need to enable GSS (Kerberos) authentication in the corresponding services.
For SSH, enable
GSSAPIAuthentication yesin /etc/ssh/sshd_config.-
For sudo, enable
pam_sss_gssas described in the manpage: In/etc/sssd/sssd.conf: Add an entry for your domain:[domain/example.com] pam_gssapi_services = sudo, sudo-i
In
/etc/pam.d/sudo, enable the module in the first line:auth sufficient pam_sss_gss.so
Caveat: 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.