<?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="authentication">
  <title>Cockpit Authentication</title>

  <section id="initial-auth">
    <title>Primary server authentication</title>

    <para>While cockpit allows you to monitor and administer several servers at the
      same time, there is always a primary server your browser connects to
      that runs the Cockpit web service (cockpit-ws) through which connections to
      additional servers are established.
      See <ulink url="https://raw.githubusercontent.com/cockpit-project/cockpit/master/doc/cockpit-transport.png">this diagram</ulink> for how it works.</para>

    <para>By default the cockpit web service is installed on the base system and
      <link linkend="listen">socket activated by systemd</link>. In this setup
      access is controlled by a cockpit specific pam stack, generally located
      at <filename>/etc/pam.d/cockpit</filename>. By default this is configured
      to allow you to login with the username and password of any local account on the
      system. You can also setup a <link linkend="sso">Kerberos based SSO
      solution</link> or <link linkend="cert-authentication">certificate/smart
      card authentication</link>.
    </para>

    <para>You can also <ulink url="https://github.com/cockpit-project/cockpit/blob/master/doc/authentication.md#actions">disable
    authentication schemes</ulink> to enforce authentication policies, or to suppress
    undesired browser GSSAPI authentication dialogs.</para>

    <para>The web server can also be run from the
      <ulink url="https://hub.docker.com/r/cockpit/ws/">cockpit/ws</ulink>
      container. If you are running cockpit on a container host operating system like
      <ulink url="https://getfedora.org/coreos/">Fedora CoreOS</ulink>
      this will be the only supported mode. In this setup, cockpit establishes an
      SSH connection from the container to the underlying host, meaning that it is up to
      your SSH server to grant access. To login with a local account, <filename>sshd
      </filename> will need to be configured to allow password based authentication.
      Alternatively you can setup a <link linkend="sso">Kerberos based SSO
      solution</link>.</para>

    <para>Like <filename>sshd</filename>, cockpit can be configured to limit the number
      of concurrent login attempts allowed. This is done by adding a <code>MaxStartups</code>
      option to the <code>WebService</code> section of your <code>cockpit.conf</code>.
      Additional connections will be dropped until authentication succeeds or
      the connections are closed.</para>

  </section>

  <section id="secondary-auth">
    <title>Secondary server authentication</title>

    <para>Once you are able to login to the primary server you will be able to connect to
      additional servers. These servers will need to be running an SSH server on port 22
      and be configured to support one of the following authentication methods.</para>

    <section id="password">
      <title>Password</title>
      <para>The target server will need to have password based authentication
        enabled in <filename>sshd</filename>. When this is setup for the first time,
        Cockpit will ensure that the user connected to primary server has the
        same password on the secondary server.</para>
    </section>

    <section id="kerberos">
      <title>Kerberos</title>
      <para>The target server will need to be a member of the same domain as the
        primary server and your domain must be whitelisted in your browser.
        See the <link linkend="sso">SSO documentation</link> for how to set
        this up.</para>
    </section>

    <section id="public-key">
      <title>Public key</title>

    <para>When you successfully log into the primary server, an <filename>ssh-agent
      </filename> is started. The following keys are then preloaded into the
      <filename>ssh-agent</filename> provided they are supported by your SSH
      version, present, with the correct permissions, and either unencrypted
      or encrypted with the same password that was used to login.</para>

<programlisting>
~/.ssh/id_rsa
~/.ssh/id_dsa
~/.ssh/id_ed25519
~/.ssh/id_ecdsa
</programlisting>

    <para>Cockpit provides an interface for loading other keys into the agent
      that could not be automatically loaded.</para>

    <para>The target server will need to have public key authentication enabled in
      <filename>sshd</filename>, and the public key you wish to use must be present in
      <filename>~/.ssh/authorized_keys</filename>.</para>

    <para>Note that when a user is authenticated in this way the authentication
      happens without a password, as such the standard cockpit reauthorization
      mechanisms do not work. The user will only be able to obtain additional
      privileges if they do not require a password.</para>

    </section>
  </section>
</chapter>
