An Ansible collection containing roles/modules to install, configure and interact with the Smallstep certificate server and the CLI tool. Possible uses for this collection include:
- Managing your
step-ca
server install (installation, configuration, provisioners) - Automated bootstrapping of hosts to trust your CA
- Token or certificate creation from within your Ansible playbooks
- Complete configuration of client certificates via ACME, including automatic renewal
π Documentation
- For role documentation, see their
README.md
s or the online docs here - For modules documentation, see the online docs here
Role | Description |
---|---|
step_ca |
Install step-ca as an internal CA. |
step_bootstrap_host |
Configure a client host to trust your CA using step-cli. |
step_acme_cert |
Set up a Let's Encrypt-style certificate on a host using your ca, including automatic renewal. |
step_cli |
Install step-cli and nothing else. Used by bootstrap_host and step_ca under the hood. |
Module | Description | Remote (Online mode) | Local (Offline mode) |
---|---|---|---|
step_ca_bootstrap |
Initialize step-cli to trust a step-ca server |
β | β |
step_ca_certificate |
Generate a new private key and certificate signed by the CA root certificate | β | offline parameter |
step_ca_provisioner |
Manage provisioners on a step-ca server |
admin parameters, if configured |
β |
step_ca_renew |
Renew a valid certificate | β | offline parameter |
step_ca_revoke |
Revoke a Certificate | β | offline parameter |
step_ca_token |
Generate an OTT granting access to the CA | β | offline parameter |
- A recent release of Ansible. This collection is tested against the 2 most recent Ansible releases. Older versions might still work, but are not supported
- Python 3.7 or newer on the target nodes
Individual roles or modules may have additional dependencies, please check their respective documentation.
Each minor version of this collection designed to be compatible with the corresponding minor release of the step-cli
utility.
For example, The collection releases with version 0.24.x
are compatible with the step-cli
utility versions 0.24.x
.
This coupling is needed as newer minor versions of the step-cli
tool may introduce breaking changes and affect this collection.
To install the correct collection version, check your step-cli
version (step-cli --version
), then use that value when installing the collection.
For step-cli versions <0.20
: Use the collection version >=0.4,<0.5
.
Via ansible-galaxy (recommended):
ansible-galaxy collection install maxhoesel.smallstep>=your-step-cli-version,<next-major-version
Alternatively, you can download a collection archive from a previous release.
This collection contains several modules for managing your smallstep environment.
Most of them wrap around step-cli
commands, so they usually support all the features of the respective command.
If you'd like to know more about an individual module, you can view its documentation using ansible-doc maxhoesel.smallstep.<step_module_name>
(or use the online docs).
The step-cli
tool has two sets of commands - standalone and CA.
- Standalone commands are executed by
step-cli
directly with no external CA required. Example:step-cli certificate create
- CA commands require the usage of an external step CA (Example:
step-cli ca certificate
). Depending on the module, there are two modes:- Online mode:
step-cli
communicates with the CA over HTTPS and requests the data it needs. - Offline/Local mode:
step-cli
accesses the CA files (certificates, config) directly. This only works on the CA host itself.
- Online mode:
Most CA modules can use either online or offline mode using the offline
parameter, but there are some exceptions.
For example, the step_ca_provisioner_(claims)
modules(s) need to run in offline mode as they directly write to the CA config.
See this table for details.
In order to talk to your CA in online mode, step-cli
needs to already trust it. You can achieve this by:
- Running the module on a host that was configured with
step_bootstrap_host
as root (recommended). - Pasing the
ca_url
androot
parameters to the module.
For offline mode, you need to:
- Provide
step-cli
with the path to your CA config ($STEPPATH/config/ca.json
by default). You can override this with theca_config
parameter if required. - Run the module as the user the CA is running as to prevent permission issues
Below are some examples to showcase the different options. These examples assume that a CA is already set up on the local host.
- hosts: ca
tasks:
- name: Run a module in online mode by specifying the CA URL and CA cert
maxhoesel.smallstep.step_ca_certificate:
root: /etc/ssl/myca.crt
ca_url: https://my-ca.localdomain
#params go here
# This will only work if you ran step_bootstrap_host on this host first!
- name: Run a module as root to use the CA configured during bootstrapping
maxhoesel.smallstep.step_ca_certificate:
#params go here
become: yes
- name: Run a module in offline mode
maxhoesel.smallstep.step_ca_certificate:
offline: yes
# params go here
become: yes
# You should run modules acting on a local CA as the user that the CA runs as.
# If you configured your CA with `step_ca`, the default user name is `step-ca`.
become_user: step-ca
- name: Run a offline-only module and manually supply the ca_config
maxhoesel.smallstep.step_ca_provisioner:
ca_config: /etc/step-ca/config/ca.json
#params go here
become: yes
become_user: step-ca
All modules in this collection respect the $STEPPATH
environment variable used to customize the step-cli config directory:
- name: Use the custom $STEPPATH in a module
maxhoesel.smallstep.step_ca_certificate:
# params go here
environment:
STEPPATH: /etc/step-cli
This section will show you how to install a step-ca server and configure clients to trust that CA using this collection. This guide will give you a good overview of how to use the tools in this collection.
Let's start with our inventory: In this example, we have a single server that we want to use as a step CA and three clients that we want to trust the server:
all:
children:
step_ca:
my-ca.localdomain
clients:
hosta.localdomain
hostb.localdomain
hostc.localdomain
To create a CA server from scratch, this role contains the step_ca
role.
It will install and initialize a step-ca server for you, which you can then configure however you want.
Below is a simple example for how to do so. If you want to know more, check out the documentation for step_ca
.
NOTE
Please make sure that you have read the considerations for running a step-ca server in production.
step_ca
follows these considerations where possible, but you should still be familiar with the basic operation of the step-ca
server.
See the step_ca
documentation for more details on how private keys are handled.
ca.yml
:
- hosts: step_ca
become: yes
tasks:
# Install and initialize the CA server.
# There are a lot of configuration options, see the step_ca README for details
- name: Install step-ca
include_role:
name: maxhoesel.smallstep.step_ca
vars:
step_ca_name: Foobar Internal CA
step_ca_root_password: "incredibly secret password"
step_ca_intermediate_password: "very secret password"
# The CA root cert fingerprint is used by clients to verify the authenticity of your CA.
# You can save the output of this task and then pass it on to any client that you want to trust the CA.
- name: Get root CA fingerprint
command: 'step-cli certificate fingerprint /etc/step-ca/certs/root_ca.crt'
register: root_ca_fp
- name: Show root CA fingerprint
debug:
msg: "Fingerprint of root cert: {{ root_ca_fp.stdout }}"
To establish trust between your clients and the CA, you will need the fingerprint of the CA root cert - see the Create a CA section for more details. This fingerprint identifies your CA to your clients and allows them to verify the CA cert.
To actually initialize the clients, you can use step_bootstrap_host
. This role will install step-cli
and configure the host to trust your CA.
clients.yml
:
- hosts: clients
become: yes
tasks:
- name: Bootstrap the hosts to trust the CA
include_role:
name: maxhoesel.smallstep.step_bootstrap_host
vars:
# These values point the hosts to your newly created CA
step_bootstrap_ca_url: https://my-ca.localdomain
step_bootstrap_fingerprint: "your root CA certs fingerprint"
- name: Verify that everything is working
command: step-cli ca health
changed_when: no
At this point, your CA is up and running and your hosts are configured to trust it. You're ready to go! You can take a look at the available modules to further configure your CA and hosts if you wish to do so.
Created & Maintained by Max HΓΆsel (@maxhoesel) and Contributors
Licensed under the GPL 3.0 or later