{"id":15602296,"url":"https://github.com/trfore/ansible-smallstep","last_synced_at":"2025-04-19T20:19:31.986Z","repository":{"id":235576041,"uuid":"790857510","full_name":"trfore/ansible-smallstep","owner":"trfore","description":"Collection of Ansible Roles for Smallstep - Debian/Ubuntu and RedHat/CentOS","archived":false,"fork":false,"pushed_at":"2025-03-18T21:02:28.000Z","size":2974,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T21:29:37.598Z","etag":null,"topics":["ansible-collection","pki","smallstep","ssh-certificates","tls"],"latest_commit_sha":null,"homepage":"https://galaxy.ansible.com/ui/repo/published/trfore/smallstep/","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trfore.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-23T16:52:06.000Z","updated_at":"2025-03-18T21:02:30.000Z","dependencies_parsed_at":"2024-04-23T22:24:27.106Z","dependency_job_id":"f745b1c6-c8be-467a-a635-b692b99ee00f","html_url":"https://github.com/trfore/ansible-smallstep","commit_stats":null,"previous_names":["trfore/ansible-smallstep"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trfore%2Fansible-smallstep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trfore%2Fansible-smallstep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trfore%2Fansible-smallstep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trfore%2Fansible-smallstep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trfore","download_url":"https://codeload.github.com/trfore/ansible-smallstep/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246187219,"owners_count":20737460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible-collection","pki","smallstep","ssh-certificates","tls"],"created_at":"2024-10-03T02:41:01.014Z","updated_at":"2025-03-29T12:45:35.577Z","avatar_url":"https://github.com/trfore.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ansible Collection - trfore.smallstep\n\n[![CI](https://github.com/trfore/ansible-smallstep/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/trfore/ansible-smallstep/actions/workflows/ci.yml)\n[![CD](https://github.com/trfore/ansible-smallstep/actions/workflows/cd.yml/badge.svg)](https://github.com/trfore/ansible-smallstep/actions/workflows/cd.yml)\n[![Release Check](https://github.com/trfore/ansible-smallstep/actions/workflows/release-check.yml/badge.svg)](https://github.com/trfore/ansible-smallstep/actions/workflows/release-check.yml)\n\n- 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.\n- 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: true` and initialize the PKI via an Ansible playbook, for more details see:\n  - [`step_ca` readme](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_ca/README.md) or [scenario guide: ca](https://trfore.github.io/ansible-smallstep/branch/main/docsite/guide_ca_nonproduction.html)\n- 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:\n  - [`step_cert` readme](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_cert/README.md) or [scenario guide: client](https://trfore.github.io/ansible-smallstep/branch/main/docsite/guide_client.html)\n  - [`step_ssh` readme](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_ssh/README.md) or [scenario guide: ssh](https://trfore.github.io/ansible-smallstep/branch/main/docsite/guide_ssh.html)\n\n## Install the Collection\n\nYou can install this collection with the Ansible Galaxy CLI:\n\n```bash\nansible-galaxy collection install trfore.smallstep\n```\n\n## Roles\n\n- 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\n  - [`step_ca`](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_ca) - Install and Initialize Step CA\n  - [`step_ca_cert`](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_ca_cert) - Download and add the CA root certificate to trust stores\n  - [`step_cert`](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_cert) - Request an x509 certificate from the CA and automatically renew it\n  - [`step_cli`](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_cli) - Install Step CLI\n  - [`step_provisioner`](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_provisioner) - Add provisioners to Step CA\n  - [`step_ssh`](https://github.com/trfore/ansible-smallstep/tree/main/roles/step_ssh) - Generate SSH host certificate and configure server to accept user certificates\n\n## Tested Platforms\n\n- `ansible-core` 2.16, 2.17 \u0026 2.18\n- CentOS Stream 9\n- Debian 11 \u0026 12\n- Ubuntu 22.04 \u0026 24.04\n\n## Example Playbook\n\n### Production Workflow\n\n- Phase I: Create a step CA server.\n\n```yaml\n---\n- name: Setup Step CA Server\n  hosts: ca-server\n  become: true\n  gather_facts: true\n  roles:\n    - name: Install Step CLI\n      role: trfore.smallstep.step_cli\n\n    - name: Install Step Certificates\n      role: trfore.smallstep.step_ca\n### Initialize the CA Offline, storing the root key in an encrypted drive ###\n```\n\n- Phase II: Configure clients to request certificates from the CA.\n\n```yaml\n---\n- name: Extract Root CA Information\n  hosts: ca-server\n  become: true\n  tasks:\n    - name: Get Root CA Fingerprint\n      ansible.builtin.command: step certificate fingerprint /etc/step-ca/certs/root_ca.crt\n      register: ca_fingerprint\n      changed_when: true\n\n- name: Setup Step CA Clients (Servers)\n  hosts: ca_clients\n  become: true\n  gather_facts: true\n  roles:\n    - name: Install Step CLI\n      role: trfore.smallstep.step_cli\n\n    - name: Bootstrap Step CA Root Certificate\n      role: trfore.smallstep.step_ca_cert\n      vars:\n        step_ca_fingerprint: \"{{ hostvars['ca-server'].ca_fingerprint.stdout }}\"\n        step_ca_url: \"https://ca.example.com\"\n\n    - name: Request x509 Certificate\n      role: trfore.smallstep.step_cert\n```\n\n### Non-production Example with CA Initialization\n\n- A complete playbook file is available under [playbooks/non-production.yml (link)](https://github.com/trfore/ansible-smallstep/blob/main/playbooks/non-production.yml) with example [playbooks/group_vars (link)](https://github.com/trfore/ansible-smallstep/tree/main/playbooks/group_vars).\n\n```yaml\n---\n- name: Setup Step CA Server\n  hosts: ca-server\n  become: true\n  gather_facts: true\n  roles:\n    - name: Install Step Certificates\n      role: trfore.smallstep.step_ca\n      vars:\n        step_ca_initialize: true\n        step_ca_enable_service: true\n        step_ca_name: \"Example.com CA\" # Required\n        step_ca_password: \"password01\" # Required\n        step_ca_provisioner_password: \"password02\" # Required\n        step_ca_ssh_mgmt: true # For SSH certificates\n\n    - name: Add Provisioner to Step CA\n      role: trfore.smallstep.step_provisioner\n      vars:\n        step_provisioner:\n          - name: acme\n            type: acme\n            renewal_after_expiry: true\n            x509_default_dur: \"48h\"\n            x509_max_dur: \"168h\"\n          - name: google\n            type: oidc\n            ssh: true # For SSH certificates\n            client_id: \"\" # From GCP API Config\n            client_secret: \"\" # From GCP API Config\n            config_endpoint: \"https://accounts.google.com/.well-known/openid-configuration\"\n            domain: \"gmail.com\"\n          - name: sshpop # For SSH certificate renewal\n            type: sshpop\n            ssh: true\n\n  tasks:\n    - name: Get root CA fingerprint\n      ansible.builtin.command: step certificate fingerprint /etc/step-ca/certs/root_ca.crt\n      register: ca_fingerprint\n      changed_when: false\n      failed_when: ca_fingerprint.rc == 1\n\n- name: Setup Step CA Clients (Servers)\n  hosts: ca_clients\n  become: true\n  gather_facts: true\n  roles:\n    - name: Install Step CLI\n      role: trfore.smallstep.step_cli\n\n    - name: Bootstrap Step CA Root Certificate\n      role: trfore.smallstep.step_ca_cert\n      vars:\n        step_ca_fingerprint: \"{{ hostvars['ca-server'].ca_fingerprint.stdout }}\"\n        step_ca_url: \"https://ca.example.com\"\n\n    - name: Request x509 Certificate\n      role: trfore.smallstep.step_cert\n\n    # For SSH certificates\n    - name: Configure Host for SSH Certificates\n      role: trfore.smallstep.step_ssh\n      vars:\n        step_ssh_provisioner: \"Example.com\" # JWK provisioner name extracted from 'Example.com CA'\n        step_ssh_provisioner_password: \"password02\" # Same value passed to 'step_provisioner_password', see 'step_ssh' README for details.\n```\n\n## Author and License Information\n\nTaylor Fore (https://github.com/trfore)\n\nSee LICENSE file for this Ansible collection.\n\nSmallstep (`certificates` and `cli`) is Apache 2.0 license software from Smallstep Labs, Inc. For additional information see:\n\n- https://smallstep.com/terms-of-use/\n- https://github.com/smallstep/certificates/blob/master/LICENSE\n- https://github.com/smallstep/cli/blob/master/LICENSE\n\n## References\n\n- https://smallstep.com/docs/step-ca/certificate-authority-server-production/\n- https://smallstep.com/docs/step-ca/provisioners/\n- https://smallstep.com/docs/step-cli/reference/ca/provisioner/add/\n\n### Using Smallstep in Production\n\n- Using a Yubikey as an alternative to a HSM, https://smallstep.com/blog/build-a-tiny-ca-with-raspberry-pi-yubikey/\n- https://smallstep.com/docs/step-ca/certificate-authority-server-production/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrfore%2Fansible-smallstep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrfore%2Fansible-smallstep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrfore%2Fansible-smallstep/lists"}