- This collection is for setting up a a public key infrastructure (PKI) using Smallstep. It will install CA server and, optionally, configure the CA server and host servers ("clients") to request x509 certificates from the CA.
- The default values for the collection are set with the intention of being used in production and initializing the CA server offline, outside of an Ansible play. However, you can set
step_ca_initialize: trueand initialize the PKI via an Ansible playbook, for more details see: - For client servers, the default argument values for the roles are designed for generating a single ACME certificate and automatically renew it on each host. Yet, you can configure the roles to generate and request multiple x509 certificates and SSH certificates as well. See the example playbook below, READMEs and scenario guides for more details:
You can install this collection with the Ansible Galaxy CLI:
ansible-galaxy collection install trfore.smallstep- Variables and default values are listed in each role's README and available at the documentation website: https://trfore.github.io/ansible-smallstep/branch/main
step_ca- Install and Initialize Step CAstep_ca_cert- Download and add the CA root certificate to trust storesstep_cert- Request an x509 certificate from the CA and automatically renew itstep_cli- Install Step CLIstep_provisioner- Add provisioners to Step CAstep_ssh- Generate SSH host certificate and configure server to accept user certificates
ansible-core2.17, 2.18 & 2.19- CentOS Stream 9
- Debian 11 & 12
- Ubuntu 22.04 & 24.04
NOTE: For installs with numerous end-points (50+) or repetitive playbook testing, we highly recommend using STEP_*_VERSION variables in your playbook
to avoid hitting GitHub's API rate limiter (60 unauthenticated request per hour).
- Phase I: Create a step CA server.
- name: Setup Step CA Server
hosts: ca-server
become: true
gather_facts: true
roles:
- name: Install Step CLI
role: trfore.smallstep.step_cli
vars:
step_cli_version: "0.28.7"
- name: Install Step Certificates
role: trfore.smallstep.step_ca
vars:
step_ca_version: "0.28.4"
### Initialize the CA Offline, storing the root key in an encrypted drive ###- Phase II: Configure clients to request certificates from the CA.
---
- name: Extract Root CA Information
hosts: ca-server
become: true
tasks:
- name: Get Root CA Fingerprint
ansible.builtin.command: step certificate fingerprint /etc/step-ca/certs/root_ca.crt
register: ca_fingerprint
changed_when: true
- name: Setup Step CA Clients (Servers)
hosts: ca_clients
become: true
gather_facts: true
roles:
- name: Install Step CLI
role: trfore.smallstep.step_cli
- name: Bootstrap Step CA Root Certificate
role: trfore.smallstep.step_ca_cert
vars:
step_ca_fingerprint: "{{ hostvars['ca-server'].ca_fingerprint.stdout }}"
step_ca_url: "https://ca.example.com"
- name: Request x509 Certificate
role: trfore.smallstep.step_cert- A complete playbook file is available under playbooks/non-production.yml (link) with example playbooks/group_vars (link).
---
- name: Setup Step CA Server
hosts: ca-server
become: true
gather_facts: true
roles:
- name: Install Step Certificates
role: trfore.smallstep.step_ca
vars:
step_ca_initialize: true
step_ca_enable_service: true
step_ca_name: "Example.com CA" # Required
step_ca_password: "password01" # Required
step_ca_provisioner_password: "password02" # Required
step_ca_ssh_mgmt: true # For SSH certificates
- name: Add Provisioner to Step CA
role: trfore.smallstep.step_provisioner
vars:
step_provisioner:
- name: acme
type: acme
renewal_after_expiry: true
x509_default_dur: "48h"
x509_max_dur: "168h"
- name: google
type: oidc
ssh: true # For SSH certificates
client_id: "" # From GCP API Config
client_secret: "" # From GCP API Config
config_endpoint: "https://accounts.google.com/.well-known/openid-configuration"
domain: "gmail.com"
- name: sshpop # For SSH certificate renewal
type: sshpop
ssh: true
tasks:
- name: Get root CA fingerprint
ansible.builtin.command: step certificate fingerprint /etc/step-ca/certs/root_ca.crt
register: ca_fingerprint
changed_when: false
failed_when: ca_fingerprint.rc == 1
- name: Setup Step CA Clients (Servers)
hosts: ca_clients
become: true
gather_facts: true
roles:
- name: Install Step CLI
role: trfore.smallstep.step_cli
- name: Bootstrap Step CA Root Certificate
role: trfore.smallstep.step_ca_cert
vars:
step_ca_fingerprint: "{{ hostvars['ca-server'].ca_fingerprint.stdout }}"
step_ca_url: "https://ca.example.com"
- name: Request x509 Certificate
role: trfore.smallstep.step_cert
# For SSH certificates
- name: Configure Host for SSH Certificates
role: trfore.smallstep.step_ssh
vars:
step_ssh_provisioner: "Example.com CA" # JWK provisioner name extracted from 'Example.com CA'
step_ssh_provisioner_password: "password02" # Same value passed to 'step_provisioner_password', see 'step_ssh' README for details.See LICENSE file for this Ansible collection.
Smallstep (certificates and cli) is Apache 2.0 license software from Smallstep Labs, Inc. For additional information see:
- https://smallstep.com/terms-of-use/
- https://github.com/smallstep/certificates/blob/master/LICENSE
- https://github.com/smallstep/cli/blob/master/LICENSE
- trfore - original author and maintainer
Special thanks to all those who have contributed to the project! Interested in adding a feature or fixing a bug? Checkout the contributing guide.
- https://smallstep.com/docs/step-ca/certificate-authority-server-production/
- https://smallstep.com/docs/step-ca/provisioners/
- https://smallstep.com/docs/step-cli/reference/ca/provisioner/add/
- Using a Yubikey as an alternative to a HSM, https://smallstep.com/blog/build-a-tiny-ca-with-raspberry-pi-yubikey/
- https://smallstep.com/docs/step-ca/certificate-authority-server-production/