🧰Installation & Deployment

The following guide covers how to install and deploy OpenPubkey SSH to enable SSH access without the use of SSH keys.

Prerequisites

  • OpenPubkey SSH requires the use of the Zero Trust Command Line Interface (ZLI), which is supported on MacOS, Linux, and Windows devices.

  • OpenPubkey SSH provides SSH access to servers and containers running Linux.

  • Your remote server must be running OpenSSH v. 8.1 or greater.

  • OpenPubkey SSH assumes that the person looking to configure their remote host(s) is able to SSH to that box and has at minimum, sudo-er permissions on that machine.

  • OpenPubkey SSH supports only Google as an OpenID Provider (OP) at this time.

There Are Two Parts To Deploying OpenPubkey SSH:

  1. Configuring the client to speak OPK SSH

  2. Configuring the remote host to authenticate and verify using OPK SSH

Step 1: How To Configure the Client

OpenPubkey SSH is currently available only for those with a Google email (Gmail or G Suite).

Configuring OpenPubkey SSH (OPK SSH) is managed through the Zero Trust Command Line Interface (ZLI).

Please install the ZLI on your local machine and ensure it is version >= 6.36.1.

LogoInstalling the ZLIProduct Docs
Use this link to view instructions on installing the ZLI.

Once installed, you are ready to configure and authenticate with OPK SSH! See our guide for Accessing Your Remote Host if your host is already configured or continue with the instructions below.

Step 2: How To Configure Your Remote Server

Configuring a remote server with OPK SSH requires that:

  1. The user has existing SSH access to the machine.

  2. The user has, at minimum, sudo-er permissions on the machine.

  3. The host you are looking to secure must have an entry in your local ~/.ssh/config file. The zli configure command relies on your ssh config to connect to your remote host. See What Does The Configure Command Do? for more details.

  4. For collaborative access, the user with sudo permissions runs the configure command first before non-root users add themselves to the policy file.

To configure your server to use OPK SSH, execute the following command from your terminal:

zli configure opk <Google or G Suite email> <Linux user>@<hostname>

For example, this may look like zli configure opk [email protected] ec2-user@my-aws-box.

OPK SSH requires there are no existing AuthorizedKeysCommands configured on your remote host.

This is because when you initiate a connection to your server, sshd will run the first AuthorizedKeysCommand command it finds in its configuration. If there is an existing command, the OPK verifier will not be run, and OPK SSH will not work.

To avoid this situation, when you configure your server, OPK SSH automatically comments out any existing AuthorizedKeysCommands in sshd_config. This is usually harmless, but before configuring, you may wish to check /etc/ssh/sshd_config to prevent disrupting any existing access control processes you have previously set up.

With this configuration complete, your remote host is now able to facilitate SSH access through OPK SSH.

What Does The Configure Command Do?

This configure command does the following:

  • The ZLI uses the provided <Linux user>@<hostname> to connect to the host via SSH and executes a Bash script that:

    1. Copies the OPK SSH binary to the host.

    2. Creates or amends a policy file, policy.yml, (if it does not already exist) to allow access for the <Google email> as the <Linux user> to the <hostname>. In the example above, that configure command allows [email protected] to access my-aws-box as the ec2-user via OPK SSH.

    3. Ensures the OpenPubkey SSH binary and policy.yml file are both owned by root and permissions are set to 700 and 600 respectively.

    4. Configures sshd to invoke the OPK SSH binary to check if the user is authenticated when attempting to SSH into the server (or in other words, enables sshd to recognize the AuthorizedKeysCommand).

    5. Restarts sshd.

How To Test OPK SSH Is Configured Correctly

To test your setup was a success:

  1. Ensure you have logged in with the ZLI using the same Gmail or G Suite email used above in the configure step. If you need to take this action, use zli login --opk. For more information on the details of this command, see What Does The Login Command Do?.

  2. Run the following command to SSH to the remote host you configured:

// -F /dev/null tells ssh to disregard your ~/.ssh/config file 
// -o IdentityFile specifies an explicit SSH key to use
// -o IdentitiesOnly=yes tells ssh to disregard any keys registered via `ssh-agent` binary
// NOTE: because we're using -F, you must use <host ip> instead of <hostname>
ssh -F /dev/null -o IdentityFile=~/.ssh/id_ecdsa -o IdentitiesOnly=yes <Linux user>@<host ip>

If your SSH command successfully connects, then you no longer need to rely on your existing SSH keys.

If you’re unable to connect after configuring and logging in, you may need to make additional changes to your server-side SSH configuration. See Troubleshooting for assistance.

Remove Your SSH Keys

Now that you have confirmed your OPK SSH configuration, remove the server-side authorized_keys entry from ~/.ssh/authorized_keys that allowed you access to your remote host prior to OPK SSH setup. This ensures SSH will leverage OPK SSH and removes any need for that lengthy SSH command used above for testing. ☺️

Product feedback? Send us a note at [email protected].

PreviousOpenPubkey SSHNextManaging Personal & Collaborative Access

Last updated