Device Passport

Quick start: run a CA

This page takes a team from nothing to a CA that issues 10-minute SSH certificates to devices that pass your policy. Allow about an hour, most of it for the SSO application.

What you need

1. Install

Run the following from a checkout of the Device Passport source repository. Repository access is required.

cargo install --locked --path crates/dp-ca

A container image definition is in packaging/ca/ if you would rather run the CA that way.

2. Generate the keys and write the config

sudo dpass-ca init --dir /etc/dpass-ca         # prints the TrustedUserCAKeys line
sudo cp crates/dp-ca/dpass-ca.example.toml /etc/dpass-ca/dpass-ca.toml
sudo $EDITOR /etc/dpass-ca/dpass-ca.toml        # public_url, [oidc], [principals], policy

The policy is a list of environments. Each one names the checks a device must pass to get a certificate for it:

[[environment]]
name = "production"
principals = ["alice", "bob"]
hosts = ["build1.prod.example.com"]
require = ["disk_encrypted", "os_patched_within:14d", "firewall_enabled"]

Operating the CA has the full config reference and the steps for Google Workspace and Okta.

3. Check it and serve

dpass-ca check-config --config /etc/dpass-ca/dpass-ca.toml
dpass-ca serve --config /etc/dpass-ca/dpass-ca.toml

dpass-ca serve speaks plain HTTP on 127.0.0.1:8443. Put your TLS terminator in front of it at public_url.

4. Trust the CA on your servers

# sshd_config
TrustedUserCAKeys /etc/ssh/dpass_ca.pub

/etc/ssh/dpass_ca.pub holds the contents of /etc/dpass-ca/ssh_ca_ed25519.pub. dpass-ca sshd-config --config /etc/dpass-ca/dpass-ca.toml prints the lines for you. No sshd patches are needed.

5. Enroll the first device

Send a teammate or an outside collaborator to Enroll a device. Their enrollment and SSH configuration use the following command after the device software is installed:

dp setup https://ssh-ca.example.com

6. Watch and manage

dpass-ca devices list
dpass-ca devices revoke <device_id>
dpass-ca people revoke <email>
dpass-ca certs list --since 24h

The admin console shows the same data in a browser. See Desktop and console source documentation.

Next