SSH Certificates

This tutorial will describe configuring SSH user and host certificates with Pritunl Zero. User certificates allow users to connect to SSH servers with a temporary certificate removing the need to configure authorized_keys on every SSH server. Host certificates allow users to validate the authenticity of the SSH server to prevent man-in-the-middle attacks.

Configure User Domain

First follow Getting Started to install and configure Pritunl Zero. Next a user domain will need to be configured. This domain will be used to allow users to login to a web console to manage their active sessions and validate SSH certificates. The domain must be different then the management domain and any service domains. Once the DNS and certificate are configured for the domain set the User Domain field in the node settings.

User and Server Roles

Before starting organize all users and servers into groups that will be assigned roles. The roles should be distinct enough to limit unnecessary user access to servers. For large organizations user roles should be managed by the authentication provider such as Google, OneLogin or Okta.

Create Certificate Authority

In the Authorities tab click New to create a certificate authority. Each authority will represent a certificate authority. Users and hosts can be configured to use multiple certificate authorities, this can be useful to use a separate authority for production and development servers. The Match roles option allows limiting which users will receive a certificate from this authority. This option should not be used to control user access to servers. The principles in the certificate given to the user will always only contain the users roles. These certificate principles will be matched with principles configured on each server to determine if the user is granted access. The option should only be used to prevent a user from receiving too many certificates when several certificate authorities are configured.

Configure SSH Servers

The web console can automatically generate a deploy script by clicking Deploy Script in the Authorities tab, alternatively this script can be manually created. Each server will need to be configured to accept connections from trusted certificate authorities. The authorized principals will also need to be configured. Pritunl Zero user roles are represented by principals in SSH certificates. The authorized principals configured on the server will determine which user roles are able to connect. The additional emergency role should be added to all servers. This role will allow the emergency ssh client to be used to connect to all servers if the Pritunl Zero servers were to become inaccessible. It is best to automate this configuration with a configuration management tool but it can also be done manually or using the deploy script below. Replace EXAMPLE_ROLE with the Pritunl Zero roles separated by a newline that will be allowed to access the server. Replace EXAMPLE_SSH_PUB_KEY with the text in the Public Key field in the authority settings in the Pritunl Zero admin console. Separate each public key with a newline.

sudo sed -i '/^TrustedUserCAKeys/d' /etc/ssh/sshd_config
sudo sed -i '/^AuthorizedPrincipalsFile/d' /etc/ssh/sshd_config
sudo tee -a /etc/ssh/sshd_config << EOF

TrustedUserCAKeys /etc/ssh/trusted
AuthorizedPrincipalsFile /etc/ssh/principals
EOF
sudo tee /etc/ssh/principals << EOF
emergency
EXAMPLE_ROLE_1
EXAMPLE_ROLE_2
EXAMPLE_ROLE_3
EOF
sudo tee /etc/ssh/trusted << EOF
ssh-rsa EXAMPLE_SSH_PUB_KEY_1
ssh-rsa EXAMPLE_SSH_PUB_KEY_2
EOF

Configure Host Certificates

Host certificates are optional and allow users to validate the authenticity of the SSH server to prevent man-in-the-middle attacks. To use host certificates a small Python cron script must be installed on each server to validate and renew the host certificate when it expires. To use host certificates enable the Host certificates option in the authority settings and enter a Host Domain. All servers in this authority will need to have a DNS record on this domain. The Pritunl Zero SSH host client can automatically configure DNS records in Route 53, a configuration management tool can also be used. Follow the Install SSH Host Client section for information on installing the client.

Configure Bastion Host

A bastion host is optional and can be used to limit the number of servers with open SSH ports. To use first configure a separate server with SSH that will serve as the bastion host. Then configure all other servers to only accept SSH connections from this host. A host certificate must also be configured on this server. Once done set the Bastion Host field in the authority settings. When users attempt to connect to servers on the authority domain the connections will automatically be routed through the bastion host. This is done transparently to the end user, they will not need to specify the bastion host when making connections. The Pritunl SSH client will make the necessary configuration changes to the users SSH configuration for the bastion host. The users certificate and roles/principals will be authenticated separately on both the bastion server and the internal server.

Install SSH Client

Each user will need to install a small Python script that is used to retrieve SSH certificates. It will also make changes to the SSH configuration if strict host checking or a bastion host is used. The script does not wrap around or modified the ssh command. Instruct users to follow the Install SSH Client section to configure the client.

Session Length

If strong security is needed for SSH connections the Certificate Expire Minutes option in the authority settings and User Session Max Duration Minutes in settings can be set to low values. Setting a low duration for user sessions will require the user to login more frequently when retrieving SSH certificates.

Keybase Authentication

Keybase can be used to provide strong device based authentication with minimal interference to the users workflow. Using Keybase authentication allows the user to authenticate and retrieve an SSH certificate from the command line without needing to open a browser. More information on this can be found in the Keybase Authentication section.

Two-Factor Authentication

Two-factor SSH with Pritunl Zero can be configured by enabling Authority two-factor authentication in a policy and setting a 1-2 minute certificate expiration time. If the user is authenticating with Keybase a prompt with provider factors will be shown in the command line. If only push authentication is enabled the prompt won't be shown. If Keybase is not used a web browser will open prompting the user to authentication with the two-factor provider. Once authenticated the user will be able to connect to SSH servers for the next 1-2 minutes until they are prompted again. The user can run the command pritunl-ssh alias to configure a bash alias for ssh to run pritunl-ssh; ssh. This will run pritunl-ssh before every SSH command to renew the certificate if it has expired.