
Cockpit Authentication
================================

Cockpit authorizes users by looking at the Authorization header on requests
to /login. Cockpit will attempt to perform the start the authentication command that
is configured for the auth scheme contained in the header.

To configure an auth scheme add a section to cockpit.conf for that scheme. For example
to configure an command for the "Bearer" auth scheme your cockpit.conf should contain
the following section.

```
[bearer]
command = example-verify-token
timeout = 300
```

The command is then responsible to:

 * verify the given credentials
 * setup an appropriate session and enviroment based on those credentials
 * launch a bridge that speaks the cockpit protocol on stdin and stdout.

The default command is ```cockpit-session``` it is able to handle basic and gssapi
authentication.

The command will be called with a single argument which is the host that the user
is connecting to.

cockpit-ws will then send contents of the Authorization http header, without the
auth scheme, on a special authentication fd to the command. For ```basic```
and ```negotiate``` auth schemes the data will be base64 decoded before sending. For
any other auth schemes. The data will be untouched.

Once the command has processed the credentials it MUST write a JSON response to the
same authentication fd. Cockpit opens this fd using SOCK_SEQPACKET so messages can be
sent and received in one operation. Each message should be no more than 65536 bytes.

By default the special authentication fd is fd #3. If your command needs to use a
different FD for some reason you may add a ```authFD``` option to your auth schema
configuration. The configured number must be greater than 2 and less than 1024.

By default cockpit-ws will wait a maximum of 30 seconds to receive this response.
The number of seconds to wait can be adjusted by adding a timeout parameter along
side the auth schema configuration in your config file. The given value should be
a number between 1 and 900.

If more information is needed the command should respond with a json object containing
a ```prompt``` string. These message will be displayed to the user and the user will be
prompted for a response. If the user does not respond within 60 seconds the command will be
closed and the login aborted. The number of seconds to wait can be adjusted by adding a
response-timeout parameter along side the auth schema configuration in your config file.
The given value should be a number between 1 and 900.

An error response should contain the following fields:

 * problem: Values of ```authentication-failed```, ```authentication-unavailable``` or ```access-denied``` are translated to the appropriate cockpit error codes. Any other values are treated as generic errors
 * message: Optional text with more details about the error.

A successful response must contain a ```user``` field with the user
name of the user that was just logged in. Additional fields may be present.

If a successful response contains a ```login-data``` field and that field contains a valid
json object that object will be included in the HTTP response sent to client.

Once the response has been sent fd #3 should be closed and a bridge should be launched
speaking the cockpit protocol on stdin and stdout.

# Remote machines

Cockpit also supports logging directly into remote machines. The remote machine to
connect to is provided by using a application name that begins with ```cockpit+=```.
The default command used for this is cockpit-ssh.

The section ```SSH-Login``` defines the options for all ssh commands. The section
has the same options as the other authentication sections with the following additions.

 * ```host``` The default host to log into. Defaults to 127.0.0.1.
 * ```allowUnknown```. By default cockpit will refuse to connect to any machines that
 are not already present in ssh's global known_hosts file (usually ```/etc/ssh/ssh_known_hosts```).
 Set this to ```true``` is to allow those connections to proceed.

# Actions

Setting an action can modify the behavior for an auth scheme. Currently two actions
are supported.

 * **remote-login-ssh** Use the ```SSH-Login``` section instead.
 * **none** Disable this auth scheme.

To configure an action add the ```action``` option. For example to disable basic authentication.
cockpit.conf should contain the following section.

```
[basic]
action = none
```

# Limits

Like ```sshd``` cockpit can be configured to limit the number of concurrent
login attempts allowed. This is done by adding a ```MaxStartups```
option to the ```WebService``` section of your cockpit configuration.
Additional connections will be dropped until authentication succeeds or
the connections are closed. See the man page for cockpit.conf for more
details. By default the limit is set to 10.

Environment Variables
================================

The following environment variables are set by cockpit-ws when spawning an auth process

 * **COCKPIT_REMOTE_PEER** Set to the ip address of the connecting user.

The following environment variables are used to set options for the ```cockpit-ssh``` process.

 * **COCKPIT_SSH_ALLOW_UNKNOWN**` Set to ```1``` to  allow connecting to hosts that are not saved in the current knownhosts file. If not set cockpit will only connect to unknown hosts if either the remote_peer is local or if the ```Ssh-Login``` section in ```cockpit.conf``` has a ```allowUnknown``` option set to a truthy value (```1```, ```yes``` or ```true```).
 * **COCKPIT_SSH_KNOWN_HOSTS_FILE** Path to knownhost files. Defaults to ```PACKAGE_SYSCONF_DIR/ssh/ssh_known_hosts```
 * **COCKPIT_SSH_KNOWN_HOSTS_DATA** Known host data to validate against or '*' to skip validation```
 * **COCKPIT_SSH_BRIDGE_COMMAND** Command to launch after a ssh connection is established. Defaults to ```cockpit-bridge``` if not provided.
 * **KRB5CCNAME** Kerberos credentials cache name. Not set when no active kerberos session is active.
