- 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/