Skip to main content

Advanced use cases

Gradual migration​

Mac & Linux​

If you don't want to use the 1Password SSH agent for all your hosts right away, you don't have to. The 1Password SSH agent can run alongside another SSH agent, like the OpenSSH agent.

The SSH client config file (~/.ssh/config) allows you to provide different authentication details for different hosts. So, you can try the 1Password SSH agent with one or two hosts to start, then gradually migrate the rest when you're ready.

Here are a few examples of what your ~/.ssh/config file could look like:

Windows​

Windows doesn't have the same flexibility with the ~/.ssh/config file as macOS and Linux because Microsoft OpenSSH listens to a fixed pipe (\\.\pipe\openssh-ssh-agent). If you want to use the 1Password SSH agent on Windows, you'll need to allow it to authenticate for all hosts.

SSH server six-key limit​

SSH agents work together with SSH clients by trying all public keys the agents manage, offering them one by one to SSH servers until the server acknowledges one that works. However, OpenSSH servers are configured by default to limit the amount of authentication attempts for an incoming SSH connection (MaxAuthTries) to six.

If your SSH client offers the SSH server a seventh key, the server will refuse the connection and you'll see this error message in your SSH client:

Server administrators can increase the limit by setting MaxAuthTries in the server's /etc/ssh/sshd_config, but in many cases you can't (or don't want to) change this.

Match key with host​

Instead, you can specify which host should be matched to which SSH key by doing the following:

  1. In your 1Password app, click the Download button on the "Public key" field of the SSH item.
  2. In your ~/.ssh/config file, add an entry for the host you're connecting to and set IdentityFile to the path of the public key you just downloaded. The private key can stay in 1Password.

Now your SSH clients will know which key to use when connecting to SSH servers, so you won't run into these authentication limits.

caution

Some SSH clients don't support specifying public keys in IdentityFile. See SSH client compatibility.

Create an SSH agent config file​

You can also create an optional SSH agent config file (~/.config/1Password/ssh/agent.toml). The agent config file allows you to specify which keys the SSH agent can make available to SSH servers and the order it offers those keys to servers. You can use the SSH agent config file alongside your SSH client config file (~/.ssh/config) to help further avoid authentication limits.

Use multiple GitHub accounts​

All GitHub accounts are authenticated over SSH using the git user. To use multiple GitHub accounts, such as a work and personal account, you'll need to configure which SSH key each repository uses.

  1. In your 1Password app, locate your SSH key item.

  2. Click the Download button on the "Public key" field. Repeat these steps for the other SSH keys you're using.

    Download your public key

  3. Move the public keys you just downloaded to your ~/.ssh/ directory.

  4. Configure hosts for your personal and work GitHub profile by appending the following to your ~/.ssh/config:

  5. For each repo, change the git URL to use one of the new hosts instead of git@github.com:

    For example:

Now your SSH clients will know which SSH key to use for each repository.

Was this page helpful?