[[authentication]]= Cockpit AuthenticationWhile cockpit allows you to monitor and administer several servers atthe same time, there is always a primary server your browser connects tothat runs the Cockpit web service (cockpit-ws) through which connectionsto additional servers are established. Seehttps://raw.githubusercontent.com/cockpit-project/cockpit/main/doc/cockpit-transport.png[thisdiagram] for how it works.Normally, a session is established on the primary server, and you usethe Shell UI of that session to connect to secondary servers.However, it is also possible to instruct the `+cockpit-ws+` process onthe primary server to directly connect to a secondary server, withoutopening a session on the primary server at all. This is done on the mainlogin page of Cockpit, by filling out the "Connect to" field.[[initial-auth]]== Directly logging into the primary serverThe most common way to use Cockpit is to just log directly into theserver that you want to access. This can be done if you have directnetwork access to port 9090 on that server.By default the cockpit web service is installed on thec base system andxref:listen.adoc[socket activated by systemd]. In this setup access iscontrolled by a cockpit specific pam stack, generally located at`+/etc/pam.d/cockpit+`. By default this is configured to allow you tologin with the username and password of any local account on the system.You can also setup a xref:sso.adoc[Kerberos based SSO solution] orxref:cert-authentication.adoc[certificate/smart card authentication].You can alsohttps://github.com/cockpit-project/cockpit/blob/main/doc/authentication.md#actions[disableauthentication schemes] to enforce authentication policies, or tosuppress undesired browser GSSAPI authentication dialogs.The web server can also be run from thehttps://quay.io/cockpit/ws[cockpit/ws] container. If you arerunning cockpit on a container host operating system likehttps://getfedora.org/coreos/[Fedora CoreOS] this will be the onlysupported mode. In this setup, cockpit establishes an SSH connectionfrom the container to the underlying host, meaning that it is up to yourSSH server to grant access. To login with a local account, `+sshd+` willneed to be configured to allow password based authentication.Alternatively you can setup a xref:sso.adoc[Kerberos based SSO solution].Like `+sshd+`, cockpit can be configured to limit the number ofconcurrent login attempts allowed. This is done by adding a`+MaxStartups+` option to the `+WebService+` section of your`+cockpit.conf+`. Additional connections will be dropped untilauthentication succeeds or the connections are closed.[[direct-secondary-auth]]== Directly logging into a secondary server without a primary sessionIt is also possible to log into a secondary server without opening asession on the primary server. This is useful if you are not actuallyinterested in the primary server and would only use it because you donot have direct network access to the secondary server.In this case, `+cockpit-ws+` still runs on the primary server, but thecredentials from the login screen are directly used with SSH to log intothe secondary server given in the "Connect To" field of the loginscreen.Thus, the PAM configuration and accounts on the primary server don'tmatter at all. Often, the only purpose of the primary server is to siton the boundary of your network and forward connections to internalmachines.In this case, the login page will prompt you to verify unknown SSH keys.Accepted keys will be remembered in the local storage of your browser.[[secondary-auth]]== Logging into a secondary server from the primary sessionOnce you have a session on the primary server, it is possible connect toadditional servers by using the host switching UI of the Cockpit Shell.This is useful if you have direct network access to the primary server,but not to the secondary server.On the command line, you would log into the primary server and then useSSH to log into the secondary one. Cockpit does just the same, and usesSSH to log into the secondary server. Instead of running a interactiveshell there, however, it starts a `+cockpit-bridge+` process._Warning:_ Unlike with SSH on the command line though, this will alsoload and use the Cockpit pages (i.e. JavaScript) from the remotemachine, which means that the remote machine can execute arbitrary codeon your primary and all other connected secondary machines. Hence, onlyconnect to _machines which you trust_.Due to this security risk, this host switcher functionality is disabledby default, except on long-term stable Linux distributions (Red HatEnterprise Linux 9, Debian 12, and Ubuntu 22.04/24.04 LTS). If you arecomfortable with the security implications, you can enable it manuallywith the `+AllowMultiHost+` option in `+cockpit.conf+`.These servers will need to be running an SSH server and be configured tosupport one of the following authentication methods.=== PasswordThe target server will need to have password based authenticationenabled in `+sshd+`.=== KerberosThe target server will need to be a member of the same domain as theprimary server and your domain must be whitelisted in your browser. Seethe xref:sso.adoc[SSO documentation] for how to set this up.=== Public keyWhen you successfully log into the primary server, a `+ssh-agent+` isstarted and keys are loaded into it by running `+ssh-add+` without anyarguments. Any passphrase prompt is answered with the password used tolog into the primary server.Cockpit provides a user interface for loading other keys into the agentthat could not be automatically loaded.The target server will need to have public key authentication enabled in`+sshd+`, and the public key you wish to use must be present in`+~/.ssh/authorized_keys+`. Cockpit has a user interface for creatingSSH keys and for authorizing them.[[host-keys]]=== SSH host keysCockpit will prompt the user to verify unknown SSH host keys, and willwrite accepted host keys into `+~/.ssh/known_hosts+`.