## Certificate/smart card authentication

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. 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

## Certificate mapping with FreeIPA

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

## 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 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

## 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

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

## 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%