<refentry id="pam_cockpit_cert.8">

  <!--
  This file is part of Cockpit.

  Copyright (C) 2019 Red Hat, Inc.

  Cockpit is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  Cockpit is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with Cockpit; If not, see <http://www.gnu.org/licenses/>.
  -->

  <refentryinfo>
    <title>pam_cockpit_cert</title>
    <productname>pam_cockpit_cert</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>pam_cockpit_cert</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>pam_cockpit_cert</refname>
    <refpurpose>PAM module for authenticating to Cockpit with a client certificate</refpurpose>
  </refnamediv>

  <refsect1><title>DESCRIPTION</title>
  <para>
    pam_cockpit_cert provides an PAM authentication module for identifying and
    authenticating users through a TLS client certificate. Commonly this is
    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. See the
    <ulink url="https://www.freeipa.org/page/V4/User_Certificates">FreeIPA User Certificates documentation</ulink>
    for details. The <filename>sssd-dbus</filename> package must be installed for this to work.
  </para>

  <para>
    In authentication mode, <refname>pam_cockpit_cert</refname> is invoked with the
    user name unset. It checks whether the web browser presented and validated
    a TLS client certificate to Cockpit. If so, that gets passed to sssd. If
    that can successfully map the certificate to a user, this PAM module sets
    the user name and succeeds, which should be treated as a sufficient authentication.
  </para>

  <para>
    Cockpit does not use certificate based authentication by default; it has to be
    explicitly enabled in <filename>cockpit.conf</filename>. If not enabled, this
    PAM module is inert and always returns <literal>ignore</literal>.
  </para>
  </refsect1>

  <refsect1 id="options">
    <title>Options</title>
    <variablelist>
      <varlistentry id="debug">
        <term><option>debug</option></term>
          <listitem>
            <para>This option will turn on debug logging to syslog.</para>
          </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="result-codes">
    <title>Result codes</title>
    <variablelist>
      <varlistentry>
        <term><option>success</option></term>
          <listitem>
            <para>Certificate is present, mapped to a user, and the user name is set in the PAM stack.</para>
          </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>user_unknown</option></term>
          <listitem>
            <para>Certificate is present, but sssd cannot map it to a user. Effectively
              a definitive failed authentication.</para>
          </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>ignore</option></term>
          <listitem>
            <para>The PAM user is already set, so this authentication process does not use a certificate.</para>
          </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>unavail</option></term>
          <listitem>
            <para>sssd is not available for mapping certificates to users.</para>
          </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>service_err</option></term>
          <listitem>
            <para>sssd is available in general, but responded with an invalid answer. This
            might indicate a compatibility problem with a future version.</para>
          </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Usage in PAM configuration</title>

    <para>The module should be added to service PAM configurations like this:</para>

    <programlisting>
-auth      [success=done new_authtok_reqd=done user_unknown=die default=ignore]   pam_cockpit_cert.so
# fallback authentication methods such as pam_unix
   </programlisting>

   <para>
     This <emphasis>must</emphasis> be first module in the "auth" stack as it
     sets the <code>PAM_USER</code> variable on successful mapping of a certificate
     to a user name. Also, <emphasis>if</emphasis> a certificate is being presented,
     then failure to map that to a user should usually be treated as fatal,
     without falling back to other methods such as password. Other errors should
     usually be considered non-fatal, and just try the next authentication method in the stack.
   </para>
  </refsect1>

  <refsect1 id="pam-cockpit-cert-see-also">
    <title>SEE ALSO</title>
    <para>
      <citerefentry> <refentrytitle>cockpit.conf</refentrytitle><manvolnum>5</manvolnum> </citerefentry>,
      <citerefentry> <refentrytitle>cockpit-tls</refentrytitle><manvolnum>8</manvolnum> </citerefentry>,
      <citerefentry> <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum> </citerefentry>,
      <citerefentry> <refentrytitle>sssd</refentrytitle><manvolnum>8</manvolnum> </citerefentry>,
      <citerefentry> <refentrytitle>sssd-ifp</refentrytitle><manvolnum>5</manvolnum> </citerefentry>
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
    <para>Cockpit has been written by many
      <ulink url="https://github.com/cockpit-project/cockpit/">contributors</ulink>.</para>
  </refsect1>

  <refsect1>
    <title>BUGS</title>
    <para>
      Please send bug reports to either the distribution bug tracker or the
      <ulink url="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</ulink>.
    </para>
  </refsect1>

</refentry>
