Project: Teleport (Provisioning / Security & Compliance)
File: 0018-agent-loading.md

authors: Russell Jones (rjones@goteleport.com) state: implemented raised UX concerns about how `tsh` loads keys into an SSH agent. `tsh` will by default attempt to load the users certificate upon login into any running agent. This breaks some SSH agents like `gpg-agent` that do not support certificates. `tsh` has a flag that can be used in multiple ways for certificate loading behavior that users have found confusing. `tsh` always writes certificates to disk, users have asked to only load certificates into the running agent. Furthermore, users have legitimate reasons for wanting to control this behavior (hence the flags). They may want to force load a certificate (our automatic detection algorithm may be incorrect) or not (the user does not want to load Teleport certificates into their agent). By default `tsh login` should attempt to load the fetched certificate into the agent. If `tsh` thinks the agent does not support SSH certificates, like `gpg-agent`, Teleport should not load the certificate and instead print a warning informing the user the certificate was not loaded and how to force load. To make complex things possible a `--add-keys-to-agent` (short flag `-k`) flag should be added to `tsh` that can be used to control if `tsh` attempts to load a certificate into the running agent or not. This matches the option that OpenSSH supports: ``` AddKeysToAgent Specifies whether keys should be automatically added to a running ssh-agent(1). If this option is set to yes and a key is loaded from a file, the key and its passphrase are added to the agent with the default lifetime, as if by ssh-add(1). If this option is set to ask, ssh(1) will require confirmation using the SSH_ASKPASS program before adding a key (see ssh-add(1) for details). If this option is set to confirm, each use of the key must be confirmed, as if the -c option was specified to ssh-add(1). If this option is set to no, no keys are added to the

Alternately, this option may be specified as a time interval using the format described in the TIME FORMATS section of sshd_config(5) to specify the key's lifetime in ssh-agent(1), after which it will automatically be removed. The argument must be no (the default), yes, confirm (optionally followed by a time interval), ask or a time interval. ``` The `--add-keys-to-agent` (short flag `-k`) should support following values `auto`, `only`, `yes`, `no`. The default value should be `auto`. `auto` indicates that a best effort attempt will be made to detect the agent, and if it supports SSH certificates, load the certificate into the running agent. `only` indicates that keys will only be loaded into the running agent and not written to disk. It's behavior is `yes` in that no detection logic will be used. `yes` indicates that an attempt will be made to load the certificate into the running agent. `no` indicates that no attempt will be made to load the certificate into the running agent. The initial detection algorithm should be simple. `tsh` should read in the `$SSHAUTHSOCK` environment variable. If the path contains a string that indicates the agent does not support SSH certificates, like `gpg-agent`, it will not attempt to load the certificate into the agent. The existing `use-local-ssh-agent` flag will be hidden and depreciated but will continued to be supported forever to not break existing users workflow. The existing flag will be mapped to the following values: | use-local-ssh-agent | add-keys-to-agent | | -- | -- | | true | auto | | false | false | For most users, not specifying the `add-keys-to-agent` (where the default `auto` is used) is the behavior they want and expect. For example, for `ssh-agent`. ``` $ tsh --proxy=proxy.example.com login [...] $ ssh-add -l 2048 SHA256:HiqSRCpljSaGt7eHCxlGGlCHcqRxSJ1vu5K7Sgl9pp4 teleport:rjones (RSA-CERT) 2048 SHA256:HiqSRCpljSaGt7eHCxlGGlCHcqRxSJ1vu5K7Sgl9pp4 teleport:rjones (RSA) ``` If `gpg-agent` is being used no keys will be loaded. ``` $ SSHAUTHSOCK=$(gpgconf --list-dirs agent-ssh-socket) $ tsh --proxy=example.com login [...] Warning: Certificate was not loaded into agent because the agent at SSHAUTHSOCK does not appear to support SSH certificates. To force load the certificate into the running agent, use the --add-keys-to-agent=yes flag. $ gpg-connect-agent 'keyinfo --list' /bye OK $ ```