step-ca on AWS User Guide

Overview

This image runs step-ca, the open source online certificate authority from Smallstep for secure, automated X.509 and ACME certificate management. step-ca lets you run your own private PKI: an internal certificate authority that issues short-lived TLS certificates to your services, devices and workloads, with full support for the ACME protocol so any ACME client can request and renew certificates automatically. The image is delivered as a ready-to-use certificate authority appliance: step-ca.service is enabled and starts on boot, and every instance bootstraps its own unique certificate authority the first time it boots, so the moment an engineer connects over SSH the CA is already running and healthy.

This is a headless certificate authority service. There is no web interface. step-ca runs as a long-lived daemon as a dedicated unprivileged user, serving the CA's X.509 and ACME API over TLS on the standard HTTPS port. The matching step command line tool is installed for bootstrapping clients, inspecting certificates and issuing certificates from the provisioner. The instance security group opens port 22 for SSH and port 443 for the CA API; you open port 443 to the clients that need to reach the CA.

The certificate authority configuration, the root and intermediate certificates and the encrypted signing keys all live on a dedicated, independently resizable EBS data volume mounted at /etc/step-ca, which is the CA's STEPPATH. The CA material sits on durable storage you can resize and snapshot independently of the operating system disk.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound port 443 from the clients that need certificates
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for step-ca. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 443 from the clients that will request certificates. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation generates the instance's own unique certificate authority and takes a short moment after the instance state becomes Running and the status checks pass; step-ca.service is serving its API by the time you can connect.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg step-ca Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 443.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=step-ca}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

A welcome banner prints the most useful commands. The first boot writes the certificate authority details to a protected file: the per-instance CA key password, the provisioner password and the root certificate fingerprint. Read it with:

sudo cat /root/step-ca-credentials.txt

Keep these values safe: the passwords are unique to this instance and are required to issue certificates and to decrypt the CA keys, and the root fingerprint is what clients use to bootstrap trust in your CA.

Step 4: Verify the Service

step-ca runs as a system service that is enabled and started on boot. Confirm the daemon is active:

systemctl is-active step-ca

That prints active. For the full unit status, including the main PID, the dedicated step user it runs as and the command line the daemon is running, use:

systemctl status step-ca --no-pager

Confirm the installed binary and version, which is pinned to step-ca 0.30.2 on this image:

step-ca version

You should see step-ca 0.30.2 reported. The matching step command line tool is installed alongside it:

step version

Step 5: Check the CA Health

step-ca serves its X.509 and ACME API over TLS on port 443. The API is served with the CA's own certificate chain, which is rooted in this instance's own CA root rather than a public certificate authority, so you query the health endpoint with curl -k (insecure transport verification) — that is expected and correct for a private CA. The health endpoint returns {"status":"ok"} with HTTP 200 while the CA is healthy:

curl -k https://127.0.0.1/health

You can also use the step tool, which verifies the connection against the CA's own root certificate on disk:

step ca health --ca-url https://127.0.0.1 --root /etc/step-ca/certs/root_ca.crt

That prints ok. The certificate authority is up and serving its X.509 and ACME API.

Step 6: Inspect the Root and Issue a Certificate

Each instance has its own unique root certificate. Inspect it to see the subject, validity and key details of your certificate authority:

step certificate inspect /etc/step-ca/certs/root_ca.crt --short

Note the root certificate fingerprint, which is also in the credentials file. Clients bootstrap trust in your CA with this fingerprint:

step certificate fingerprint /etc/step-ca/certs/root_ca.crt

To issue a short-lived leaf certificate directly from the admin provisioner, use step ca certificate. The following requests a certificate for an internal service name, signed by your CA; supply the provisioner password from the credentials file when prompted. These are customer-facing commands you run against your own CA:

step ca certificate "svc.internal" /tmp/svc.crt /tmp/svc.key \
  --provisioner admin \
  --ca-url https://127.0.0.1 \
  --root /etc/step-ca/certs/root_ca.crt
step certificate inspect /tmp/svc.crt --short

The second command inspects the leaf certificate you just issued, confirming it was signed by your CA and carries the requested name.

A default ACME provisioner is also configured, so any standard ACME client (certbot, acme.sh, Caddy, Traefik and others) can request and renew certificates automatically. Point your ACME client at the CA's directory endpoint, replacing <this-host> with the address your clients use to reach the instance:

echo "https://<this-host>/acme/acme/directory"

Step 7: Configure the CA

step-ca reads its configuration from a single JSON file under STEPPATH. The configuration directory and the certificates and keys live on the dedicated data volume:

ls /etc/step-ca/

The main configuration is config/ca.json. It defines the CA's address, the root and intermediate certificates, the database and the provisioners. Review it with:

sudo jq '.address, (.authority.provisioners[] | {type, name})' /etc/step-ca/config/ca.json

To change the CA, edit config/ca.json or use the step ca provisioner commands to add and remove provisioners, then reload the service. You can adjust certificate lifetimes and templates, enable SSH certificates, and add JWK, OIDC, ACME or X5C provisioners. After editing the configuration, reload step-ca to apply your changes:

sudo systemctl reload step-ca

Open port 443 to the clients that need to reach the CA in the instance security group.

Step 8: The Data Volume

The certificate authority configuration (config/ca.json), the root and intermediate certificates (certs/), the encrypted signing keys (secrets/) and the database all live on a dedicated EBS volume mounted at /etc/step-ca, which is the CA's STEPPATH. This keeps the CA material off the operating system disk and lets you resize and snapshot the volume independently. Confirm the mount with:

df -h /etc/step-ca

To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. To back up your certificate authority, snapshot this volume; it holds everything needed to restore the CA, so protect the snapshot accordingly.

Support

This image is published and supported by cloudimg. Support covers PKI design, provisioner configuration, ACME automation, certificate templates and lifetimes, SSH certificates, client bootstrapping, certificate renewal, the CA health and configuration, and upgrade planning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.