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.

User certificate generation

Generating the certificates for users is usually done with a certificate management system like certmonger or FreeIPA, which are not documented here. This command generates a simple key and certificate request for the "alice" user:

openssl req -new -newkey rsa:2048 -days 365 \
    -keyout alice.key -out alice.csr -subj "/CN=alice"

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:

openssl pkcs12 -export -in alice.pem -inkey alice.key -out alice.p12

Don’t forget to clean up the key file when you do not need it any more:

shred -u alice.key

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

Certificate mapping with FreeIPA

The recommended method to sign a user certificate request and associate it to a user is ipa cert-request:

ipa cert-request alice.csr --principal=alice --certificate-out=alice.pem

Alternatively, if you are using a different CA, you can use ipa user-add-cert to associate the signed certificate to the user. This expects PEM format, but without the -----BEGIN/-----END markers:

ipa user-add-cert alice --certificate="$(grep -v ^---- alice.pem)"

See the FreeIPA User Certificates documentation for details.

Certificate mapping with Microsoft Active Directory

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 controller "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

Certificate mapping with Samba Active Directory

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})

Cockpit web server configuration

Set the trusted Certificate Authority of your user certificates in sssd, either by copying the CA PEM file to /etc/sssd/pki/sssd_auth_ca_db.pem or setting the pam_cert_db_path configuration option to the path of the CA. If you use FreeIPA and its CA:

cp /etc/ipa/ca.crt /etc/sssd/pki/sssd_auth_ca_db.pem

Certificate authentication needs to be enabled in cockpit.conf explicitly:

[WebService]
ClientCertAuthentication = yes

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

Cockpit web server resource limits

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%

Authentication to other services like sudo and ssh

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.

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 yes in /etc/ssh/sshd_config.

  • For sudo, enable pam_sss_gss as 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.