maxhoesel.smallstep.step_ca role – Install and initialize a Smallstep certificates server (step-ca).

Note

This role is part of the maxhoesel.smallstep collection (version 0.24.5).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install maxhoesel.smallstep.

To use it in a playbook, specify: maxhoesel.smallstep.step_ca.

Entry point main – Install and initialize a Smallstep certificates server (step-ca).

Synopsis

• This role performs the following actions:

  1. Install step-cli if required

  2. Install step-ca

  3. Create a user to run the step-ca server, if it doesn’t already exist

  4. Initialize a fresh ca server with no provisioners using step ca init

  5. Daemonize step-ca using a systemd service

• Requirements:

  • Root access using become: yes or equivalent

• Supported distributions:

  • Ubuntu 18.04 LTS or newer

  • Debian 10 or newer

  • Fedora 36 or newer

  • A CentOS-compatible distribution like RockyLinux/AlmaLinux 8 or newer. RockyLinux is used for testing

• NOTE: Please make sure that you have read the considerations for running a step-ca server in production. This role follows these considerations where possible, but you should still be familiar with the basic operation of the step-ca server.

• NOTE ON THE ROOT KEY: By default step-ca generates two keys when initialized - a root CA key and an intermediate key used to sign certificates. Both are present and encrypted on the ca host after this role exits, with the step-ca server configured to read the intermediate key password from a protected file in step_ca_path. The root key can thus only be decrypted with the password set in step_ca_root_password.

  It is thus very important that you back up your root key and password in a safe and secure location. The details of your backup scheme will depend on your environment and threat model.

• WARNING ABOUT USING EXISTING KEYS: If you want to use an existing root key, it is highly recommended that you use an encrypted keyfile and set step_ca_existing_key_password from a secure source, such as Ansible Vault or Hashicorp Vault.

  Storing your root key unencrypted (even just temporarily!) is strongly discouraged and poses a great security risk. This role will only decrypt the root key for as long as strictly neccessary.

Parameters

Parameter	Comments
step_ca_address string	The address that the new CA will listen at Default: ":443"
step_ca_dns string	The comma separated DNS names or IP addresses of the new CA Includes the hosts FQDN and main IPv4/6 addresses by default, if present Default: "{{ ansible_fqdn }},{{ ansible_default_ipv4.address | d('') }},{{ ansible_default_ipv6.address | d('') }}"
step_ca_executable path	Where to put the `step-ca` executable that will be installed by this role Must be an absolute path Default: "/usr/bin/step-ca"
step_ca_existing_key string	Whether to use an existing root key and if so from where to import it from Note that both cert and key need to be either imported, or generated. For example, you cannot import the key but generate the certificate Note that if this is unset and step_ca_existing_root/key_file is set, the files are treated as remote to preserve backwards-compatibility to previous collection versions. This behavior may be removed in a future release Choices: "remote" "local"
step_ca_existing_key_file path	The path of an existing key file of the root certificate authority Depending on the value of step_ca_existing_key, the file must either be on the remote host or the controller
step_ca_existing_key_password string	Password to decrypt the root key
step_ca_existing_root string	Whether to use an existing root certificate and if so from where to import it from Choices: "remote" "local"
step_ca_existing_root_file path	The path of an existing PEM file to be used as the root certificate authority Depending on the value of step_ca_existing_root, the file must either be on the remote host or the controller
step_ca_intermediate_password string	Password used to encrypt the intermediate key. If unset, uses the root password will be used as the intermediate password
step_ca_name string / required	The name of the new PKI
step_ca_path path	Directory under which to place step-ca configuration files Default: "/etc/step-ca"
step_ca_ra string	The registration authority name to use
step_ca_ra_credentials_file path	The registration authority credentials file to use
step_ca_ra_issuer string	The registration authority issuer name to use
step_ca_root_password string / required	Password used to encrypt the root key
step_ca_ssh boolean	Create keys to sign SSH certificates Choices: false ← (default) true
step_ca_url string	URI of the Step Certificate Authority to write in defaults.json
step_ca_user string	User under which the step-ca server will run Default: "step-ca"
step_ca_version string	Version of step-ca to install Can be a version tag (e.g. 0.15.3), or latest to always install the most recent version It is highly recommended that your ca version matches the collection version (e.g. if you are using the collection version 0.20.x you should be installing step-ca version 0.20.x as well) Note that the role will query the GitHub API if this value is set to latest. Try setting a specific version if you are running into rate limiting issues Default: "latest"
step_cli_executable path	What to name and where to put the step-cli executable that will be installed by this role Can be an absolute path (make sure that the parent directory is in $PATH) or a filename If this executable is not found and step_cli_executable is a path, the executable will be installed there If this executable is not found and step_cli_executable is a name, the executable will be installed at step_cli_install_dir with the given name Default: "step-cli"
step_cli_install boolean	Whether to install the step-cli utility Set this to false if the utility is already installed via other means (in this case, the role will use step_cli_executable Choices: false true ← (default)
step_cli_install_dir path	Used if the binary defined by step_cli_executable is not found on the system and step_cli_executable contains a executable name Sets the directory to install step_cli_executable into The directory must already exist Ignored if step_cli_executable contains a directory already Default: "/usr/bin"
step_cli_version string	Set the version of step to install Can be a version tag (e.g. 0.15.3), or latest to always install the most recent version It is highly recommended that your cli version matches the collection version (e.g. if you are using the collection version 0.20.x you should be installing step-cli version 0.20.x as well) Note that the role will query the GitHub API if this value is set to latest. Try setting a specific version if you are running into rate limiting issues Default: "latest"

Collection links

• Issue Tracker
• Repository (Sources)