<?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 &lt;&lt;EOF &gt; alice.ldif
version: 1
dn: cn=alice,ou=users,ou=YOUR_NETBIOS_NAME,dc=example,dc=com
changetype: modify
add: userCertificate;binary
userCertificate;binary:&lt; 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 &lt;&lt;EOF &gt; 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 = &lt;KU&gt;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/main/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>

  <section id="certauth-forwarding">
    <title>Authentication to other services like sudo and ssh</title>

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

    <para><emphasis>Supported with FreeIPA only:</emphasis> 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
      <ulink url="https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-sfu/bde93b0e-f3c9-4ddf-9f44-e1453be7af5a">S4U2Proxy Kerberos ticket</ulink>
      in the user session:
    </para>

<programlisting>
$ 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
</programlisting>

    <para>You can set up <ulink url="https://www.freeipa.org/page/V4/Service_Constraint_Delegation">constrained delegation rules</ulink>
      to enumerate which hosts (including its own) that ticket is trusted to access. For example, if the cockpit session runs on host
      <code>myhost.example.com</code> and should be trusted to access its own host (through sudo) and another host
      <code>remote.example.com</code> (through ssh), create a delegation like this:
    </para>

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

    <para>In addition, you need to enable GSS (Kerberos) authentication in the corresponding services.</para>

    <itemizedlist>
      <listitem>
        <para>For SSH, enable <code>GSSAPIAuthentication yes</code> in
          <ulink url="https://linux.die.net/man/5/sshd_config">/etc/ssh/sshd_config</ulink>.</para>
      </listitem>

      <listitem>
        <para>For sudo, enable <code>pam_sss_gss</code> as described in the
          <ulink url="https://www.mankier.com/8/pam_sss_gss">manpage</ulink>:
          In <code>/etc/sssd/sssd.conf</code>: Add an entry for your domain:</para>

<programlisting>
[domain/example.com]
pam_gssapi_services = sudo, sudo-i
</programlisting>

        <para>In <code>/etc/pam.d/sudo</code>, enable the module in the first line:</para>

<programlisting>
auth sufficient pam_sss_gss.so
</programlisting>

      </listitem>
    </itemizedlist>

    <para><emphasis>Caveat:</emphasis> 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.</para>

  </section>

</chapter>
