Keys

What are Keys?

Keys are similar to the public and private keypairs you use with Secure Shell technology (SSH). Keys work with SSH and are configured in the same way. They are unique to each user.

What's different is Keys include your PairSpaces identity. Virtual machines interpret a conventional keypair as meaning, "Allow access to this keypair". Spaces interpret Keys as meaning, "Allow access to this identity". Spaces use Keys to verify your identity, not only your ownership of the Keys.

Keys use the identity provided by Single Sign-On (SSO) providers to securely access virtual machines using SSH. This SSO-to-SSH combination creates two requirements to access Spaces - ownership of a keypair and an identity that a Space recognizes.

SSO-to-SSH (S2S) builds on top of the open-source OpenPubkey Project (see OpenPubkey). OpenPubkey is supported by the Linux Foundation and used by Docker to securely sign their offical images.

What is SSO-to-SSH?

SSO-to-SSH (S2S) is the process PairSpaces uses to associate your PairSpaces identity with your Spaces.

When you create Keys PairSpaces creates a conventional public and private keypair (1 in the figure below) and sends it with a nonce (number used once) to an OIDC provider (2-3). The combination of nonce and public key permits the OIDC provider to sign both using its private key, binding the user's identity to their keypair.

When authenticating, the public key and nonce are used by an OpenID Connect (OIDC) provider to create tokens (4-5). The identity token includes the OIDC provider's signature of the user's public key and nonce. This signature confirms that the user has the private key that is now certified by the OIDC provider.

PairSpaces creates a certificate using the identity token and the user's public key and then signs the certificate using the user's private key (6-7).

How does PairSpaces use S2S?

When a user requests access to a Space they do so using conventional SSH (1 in the figure below), but a Space does not use the AuthorizedKeysFile to create a SSH session. Instead, each Space uses the AuthorizedKeysCommand to create a SSH session (2-3).

The command associated with AuthorizedKeysCommand verifies the user's public key certificate was signed by the OIDC provider and the identity contained within it is associated with the Keys created by the PairSpaces user (4).

The command also verifies that the identity verified by the OIDC provider is associated with the Space (5-6).

If the user is both the owner of the Keys and has been granted access to the Space, a conventional SSH session is created and access is allowed.

Creating Keys

You can create Keys using the PairSpaces web application or the PairSpaces CLI.

When using the PairSpaces web application, navigate to Settings and click Create Keys.

After the Keys are created, click Download Keys and move the Keys to the default location for SSH keypairs.

Using the PairSpaces CLI, you create Keys using pair keys. The PairSpaces CLI creates keys at the default location for your operating system. Before doing this, the PairSpaces CLI will backup your existing keys, for example, ~/.ssh/id_ecdsa is copied to ~/.ssh/id_ecdsa.bak.

> pair keys

Your private key is available from ~/.ssh/id_ecdsa and your previous key was moved to ~/.ssh/id_ecdsa.bak.

> pair keys

Your private key is available from ~/.ssh/id_ecdsa and your previous key was moved to ~/.ssh/id_ecdsa.bak.

> pair.exe keys

Your private key is available from ~/.ssh/id_ecdsa and your previous key was moved to ~/.ssh/id_ecdsa.bak.

Note PairSpaces does not keep a copy of your Keys. If you lose your Keys, use the PairSpaces web application or PairSpaces CLI to recreate them.