Setup Servers and User Machines to Use SSH Certificates

  • This guide will demonstrate how to setup a server and client machine to use SSH certificates to authenticate remote connections. It assumes the following:

    • A CA is already configured to issue SSH certificates, and has a JWK, OIDC and SSHPOP provider configured. For instructions see: CA Server (x509 and SSH Certificates).

    • The root CA certificate fingerprint is known, i.e. on the CA server run step certificate fingerprint /etc/step-ca/certs/root_ca.crt.

  • Both the server and user machine will need to trust the central CA server then request:

    • A host certificate for server.

    • A user certificate for the user machine.

  • Currently, the step_ssh role supports request authentication using the JWK provisioner for host certificates. And its recommended to use an OIDC provisioner for user certs (see below).

Configure Servers to Use SSH Certificates

  • To configure a server to use SSH certificate the following playbook will:

    • Use the default JWK provider to request a SSH host certificate.

    • Use the SSHPOP provider for SSH host certificate renewal.

  • This is a minimal playbook that demonstrates the server using SSH certificates without requesting x509 certs. To also request x509 certs see: non-production.yml (link).

Playbook

- name: Setup Step CA Clients (Servers)
  hosts: ca_clients
  become: true
  gather_facts: true
  roles:
    - name: Add Step CA Root Certificate to Trust Store
      role: trfore.smallstep.step_ca_cert
      vars:
        step_ca_fingerprint: "CA_FINGERPRINT"
        step_ca_url: "CA_URL" # https://ca.example.com

    - name: Configure Host for SSH Certificates
      role: trfore.smallstep.step_ssh
      vars:
        step_ssh_provisioner: "Example.com" # JWK provisioner
        step_ssh_provisioner_password: "password02" # JWK provisioner password

Step CA Directory Layout

/etc/step-ca/
|-- certs
|   |-- root_ca.crt
|   `-- ssh_user_key.pub
`-- config
    `-- defaults.json

Configure User Machine for SSH User Certificate

1. Download and Add CA Certificate to Trust Store

  • Bootstrap the machine to download root CA certificate and create a step configuration file at /home/USER/.step.

# download root CA cert and create step configuration
$ step ca bootstrap --ca-url [CA_URL] --fingerprint [CA_FINGERPRINT]
# add root CA cert to trust store, e.g. /etc/ssl/certs
$ step certificate install $(step path)/certs/root_ca.crt

2. Request SSH User Certificate

  • Request a user certificate using a OIDC (recommended) or JWK provisioner:

    • For OIDC, the user will be redirected to the OAuth2 identity provider.

    • For a JWK provisioner, the user will need a token. Note: The default JWK token should only be used in testing, as it provides full access to the CA. Additionally, providing short-lived encrypted single-use tokens is beyond the scope of the role and collection.

# OIDC
$ step ssh login USERNAME@example.com --provisioner "google"
# JWK
$ step ssh login USERNAME --provisioner "JWK_NAME"

3. Configure User’s SSH client

$ step ssh config

4. Test the Connection

$ ssh USERNAME@server01.example.com

  • Optional, add SSH options and host server USERNAME to ~/.ssh/config.

Host server01.example.com
    User USERNAME
    ControlMaster auto
    ControlPath ~/.ssh/control-%r@%h:%p
    ControlPersist 15s

Directory Layout

  • Step Directory

/home/USER/.step/
├── certs
│   └── root_ca.crt
├── config
│   └── defaults.json
└── ssh
    ├── config
    ├── includes
    └── known_hosts

  • Also creates the following files:

    • /usr/local/share/ca-certificates/Example_Root_CA_*.crt

    • /etc/ssl/certs/Example_Root_CA_*.pem

Principals

OIDC Provisioner: Email Addresses With Special Characters

  • If an email contains periods, for example jordan.doe@example.com. Step will create multiple principles from the email address - jordandoe, jordan.doe and jordan.doe@example.com.

  • Additionally the default USER will be jordandoe in ~/.step/ssh/config.

$ step ssh login jordan.doe@example.com --provisioner "google"
$ step ssh list --raw | grep jordan.doe@example.com | step ssh inspect
        Type: ecdsa-sha2-nistp256-cert-v01@openssh.com user certificate
        ...
        Key ID: "jordan.doe@example.com"
        ...
        Principals:
                jordandoe
                jordan.doe
                jordan.doe@example.com

Additional Guides and References

OAuth2 Credentials