How to Use OpenPubkey to SSH Without SSH Keys

This post was contributed by BastionZero.

What if you could SSH without having to worry about SSH keys? Without the need to worry about SSH keys getting lost, stolen, shared, rotated, or forgotten? In this article, we’ll walk you through how to SSH to your remote Docker setups with just your email account or Single Sign-On (SSO). Find instructions for setting up OpenPubkey SSH in our documentation.

What’s wrong with SSH?

We love SSH and use it all the time, but don’t often stop to count how many keys we’ve accumulated over the years. As of writing this, I have eight. I can tell you what five of them are for, I definitely shouldn’t have at least two of them, and I’m pretty sure of the swift firing that would happen if I lost at least one other. What on earth is “is_key.pem”? I have no idea, and it sounds like I didn’t know when I made it.

There’s rarely an SSH key that’s actually harmless, even if you’re only using it to access or debug remote Docker setups. Test environments get cryptojacked and proxyjacked frequently, and entire swaths of the internet are dedicated to SSH hacking. 

When was the last time you patched sshd? The tool is ubiquitous yet so rarely updated that those threats are not going away anytime soon. Managing keys is a hassle that is bound to lead to compromise, and simple mistakes can lead to horrible outcomes. Even GitHub exposed their SSH private key in a public repository last year. 

So, what can we do? How can we do better? And is it free? Yes, yes, and yes. 

Now, there’s a new way to use SSH with OpenPubkey. Instead of juggling SSH keys, OpenPubkey SSH (OPK SSH) allows you to use your regular email account or SSO to log in and securely connect to an SSH server with a quick, one-time setup. No more guessing which keys get you fired, and no cursing your past self for poor naming conventions. No keys.

OpenPubkey SSH is the first fully developed use case for OpenPubkey, an open source project led by BastionZero, Docker, and The Linux Foundation. It will continue to grow and improve as we enhance its features and adapt it to meet evolving user needs and security challenges. Read on to learn what OpenPubkey is and how it works.

Getting started with OpenPubkey SSH 

Currently, OPK SSH only supports logging in via Google. If you have a particular provider you’d prefer, come visit us in GitHub or learn more in the Getting involved section below.

OpenPubkey SSH is being offered as part of BastionZero’s zero-trust command-line utility: the zli. Instructions for installing the zli can be found in the BastionZero documentation.

After installing the zli, you’ll need to:

1. Configure your SSH server (<1 minute)
2. Log in with Google (<1 minute)
3. Test your configuration
4. Use OPK SSH for Docker remote access
5. Manage users

Configure your SSH server

The first step is to configure your SSH server. For your first-time setup, we assume you have a Google account and at least sudoer access to the SSH server you’re trying to set up.

zli configure opk <your Google email> <user>@<hostname>

Log in with Google

Then, you need to log in. This will open a browser window so you can authenticate with Google:

zli login --opk

Test your configuration

Now, you can use SSH using OPK. To test that everything configured correctly and access is working via OPK SSH, you can run the following command:

ssh -F /dev/null -o IdentityFile=~/.ssh/id_ecdsa -o IdentitiesOnly=yes user@server_ip

Because we save our certificate at a default location, SSH will always use it to authenticate. So, it is not necessary to specify the IdentityFile after removing your existing SSH keys.

Use OPK SSH for Docker remote access

If you’re already using SSH with Docker then you’re all set, you get to keep your existing remote Docker setup with no need to do anything else. Otherwise, you can set your local Docker client to connect to a remote Docker instance by doing one of the following:

# Set an environment variable
$ export DOCKER_HOST=ssh://user@server-ip

# Or, create a new context
$ docker context create ssh-box --docker "host=ssh://user@server-ip"

Then you can use Docker as usual, and it will use SSH under the hood to connect to your remote Docker instance.

Manage users

Now that you’ve set it up for one user, let’s discuss how to configure it for many. OPK SSH means that you don’t have to coordinate with users to give them access. Who you choose to allow access to your server is specified in an easy-to-read YAML policy file that might look like this:

$ cat policy.yaml
users:
    - email: [email protected]
      principals:
        - root
        - luffy
    - email: [email protected]
      principals:
        - luffy

Note that principals is SSH-speak for the users you’re allowed to SSH in as.

If you’re flying solo or in a small group, then you’ll likely never have to deal with this file directly; our zli configuration command takes care of this for you. However, larger groups may be more interested in how this works at scale, and we’ve got answers for you. To discuss how OPK SSH can specifically fit your needs, reach out to us at BastionZero. For any issues or troubleshooting questions during the process, visit our guide.

How it works

Docker already lets you use SSH to execute Docker commands on remote containers by specifying a different host either as an environment variable or as part of a context.

# Set an environment variable
$ export DOCKER_HOST=ssh://user@server-ip

# Or, create a new context
$ docker context create ssh-box --docker "host=ssh://user@server-ip"

For OPK SSH, you don’t need to change any of that. Docker is using your pre-configured SSH under the hood for you. OpenPubkey is a different configuration that’s more secure yet completely compatible with Docker or any other access use case that relies on SSH (Figure 1).

OpenPubkey slides in nicely with how SSH is already designed. We only use integration mechanisms that are well-used and widely deployed. First, we use SSH certificates instead of SSH keys, and second, we use the AuthorizedKeysCommand to invoke the OpenPubkey verifier program. This is all taken care of for you by our zli configure command.

$ cat /etc/ssh/sshd_config
...
AuthorizedKeysCommand /etc/opk/opk-ssh verify %u %k %t
AuthorizedKeysCommandUser root
...

SSH certificates remove the need for any keys. Instead of using them as in a traditional certificate ecosystem, such as x509, our goal is to embed them with a special token that we can verify on the server. That’s where the AuthorizedKeysCommand comes in. 

The AuthorizedKeysCommand allows users to have their access evaluated by a program instead of by comparing it against preconfigured, public keys in an authorized_keys file. Once you’ve configured your sshd to use our OPK verifier, it can grant or deny access for all OPK-generated SSH certificates you give it going forward.

What is OpenPubkey?

OpenPubkey isn’t just about SSH; it is so much more. Docker is using it to sign Docker Official Images and BastionZero is using it for zero-trust infrastructure access. OpenPubkey is a joint effort between the Linux Foundation, BastionZero, and Docker. It is an open source project built on top of OpenID Connect (OIDC) that adds new functionality without impacting any of the old. 

OIDC is a protocol that lets you log into websites or applications using your personal (or work) email accounts. When you log in, you’re actually generating an identity token (ID token) that’s only for the specific application and that attests to the fact that you’re you. It also includes some handy personal information — essentially whatever you’ve given that application permission to request. 

Basically, OpenPubkey adds a temporary public key to your ID token so that you can sign messages. Because it’s attested to by trusted identity providers like Google, Microsoft, Okta, etc., anyone can verify it anywhere, at any time.

But OpenPubkey isn’t just about adding a public key to your ID token; it’s also about how you use it. One issue with vanilla OIDC is that any application that respects that token assumes you are you. With OpenPubkey, proving that you’re you isn’t just about presenting a public token, but also a single-use, signed message. So, the only way to impersonate you is to steal your public token and a private secret that never leaves your machine.  

Getting involved

There are plenty of ways to get involved. We’re building a passionate and engaged community. We discuss things at both a high level for those who like to architect and at a fun, gritty, technical level for those who like to be a different kind of architect. Come to hang out; we appreciate the support in whatever capacity you can provide.

If you’d like to get involved, visit our OpenPubkey repo. And if you’re ready to try OPK SSH to SSH without SSH keys, refer to our documentation’s comprehensive guide.

Learn more

• Watch the on-demand webinar How to use OpenPubkey to SSH without SSH keys.
• Read How to Use OpenPubkey with GitHub Actions Workloads.
• Signing Docker Official Images Using OpenPubkey
• Get the latest release of Docker Desktop.
• Vote on what’s next! Check out our public roadmap.
• Have questions? The Docker community is here to help.
• New to Docker? Get started.