step-ca supports the Automated Certificate Management Environment (ACME) protocol.
You can get X.509 certificates from your own certificate authority (CA) using popular ACME clients and libraries, or via the
step command's built-in ACME client.
ACME is a modern, standardized protocol for automatic validation and issuance of X.509 certificates from a CA to clients.
- Learn about the ACME certificate flow and the most common ACME challenge types.
- Learn how to use an ACME challenge to issue X.509 certificates to endpoints automatically.
step-cato enable ACME, and get your first certificate via
step ca certificate.
- Open source - This tutorial assumes you have initialized and started up a
step-caserver (see Getting Started).
- Smallstep Certificate Manager - follow the instructions provided in the Certificate Manager ACME documentation.
With ACME, machines can get certificates from a CA without any human interaction involved.
For example, you can:
- Use ACME in production to issue X.509 certificates to internal workloads, proxies, queues, databases, etc. so you can use mutual TLS for authentication and encryption.
- Simulate Let’s Encrypt’s certificate authority in development and pre-production scenarios where connecting to Let’s Encrypt’s staging server is problematic.
Here's how an ACME client might request an X.509 certificate from a CA.
- The ACME client creates an account with an ACME CA server and submits a certificate order. You can think of an ACME account as a place to store open certificate requests for that particular client.
- The CA responds with a set of challenges. To complete the challenges, the client must prove it controls each subject name (domain name, IP address, or hardware device ID) that it is requesting in the certificate.
- The CA verifies the client's challenge reponses.
- Once the client successfully completes the ACME challenges, it submits a certificate signing request (CSR) to the CA.
- The CA verifies that the client has control of the private key associated with the certificate request.
- The CA issues a certificate to the client.
The ACME API for certificate requests requires an HTTPS connection between the client and CA.
There is not a single standard way to prove control over an identifier, so the core ACME specification makes this an extension point. Today, most commonly, ACME clients respond to challenges via HTTP, DNS, or TLS protocols.
A Device ID may be a device's serial number, or another identifier assigned at manufacture.
The ACME CA challenges the client to host a random number at a random URL under
/.well-known/acme-challenge on port 80. The CA verifies client control by issuing an HTTP GET request to that URL.
When To Use It
This is a good general-purpose challenge type.
By hosting the challenge response via HTTP on port 80, the client proves its control over a protected port on the domain being requested.
http-01 challenge type is the easiest to set up, because any web server will let you host the challenge response as a static file.
The ACME CA challenges the client to provision a random DNS
TXT record for the domain in question. It verifies the challenge by querying DNS for that
When To Use It
dns-01 challenge type is good if your ACME server cannot reach the requested domain directly.
The server only needs to be able to perform a DNS lookup to confirm the challenge.
However, because the ACME client needs to modify DNS records, configuring a
dns-01 client is usually more involved.
The ACME CA uses TLS to validate a challenge, leveraging application layer protocol negotiation (ALPN) in the TLS handshake. The client presents a self-signed TLS certificate containing the challenge response as a special X.509 certificate extension.
When To Use It
This challenge type is useful when a security policy requires the CA to reach the client via a TLS connection. This is a popular challenge type in cases where an ingress controller fronts clients attempting to receive a certificate.
You can use
device-attest-01 for Apple Managed Device Attestation (MDA) and other secure zero-touch provisioning (SZTP) applications as part of your device management (MDM) strategy.
step-ca supports attestation challenges using Apple devices and YubiKeys.
Certificates identify specific hardware devices, via permanent device IDs. These are typically client certificates that can be used for device authentication.
Let's get an X.509 certificate via the ACME
http-01 challenge, using
First, add an ACME provisioner to your
step-ca configuration to enable ACME support:
step ca provisioner add acme --type ACME
You may need to restart
step-ca to pick up the configuration changes.
step as an ACME client to request a certificate.
The client will start a web server on port 80 to respond to the ACME challenge.
step ca certificate --provisioner acme example.com example.crt example.key
✔ Provisioner: acme (ACME) Using Standalone Mode HTTP challenge to validate example.com . done! Waiting for Order to be 'ready' for finalization .. done! Finalizing Order .. done! ✔ Certificate: example.crt ✔ Private Key: example.key