{"id":23637030,"url":"https://github.com/ansibleguy/infra_pki","last_synced_at":"2025-03-21T07:26:51.547Z","repository":{"id":65958634,"uuid":"602231733","full_name":"ansibleguy/infra_pki","owner":"ansibleguy","description":"Ansible Role to provision and manage one or multiple PKI's on the target server","archived":false,"fork":false,"pushed_at":"2024-07-21T05:16:20.000Z","size":167,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"latest","last_synced_at":"2024-07-21T16:43:02.936Z","etag":null,"topics":["ansible","ansible-role","certificate","certificate-authorities","certificate-authority","certificate-generation","certificate-generator","certificates","easyrsa","easyrsa-pki","easyrsa3","iac","infrastructure-as-code","it-automation","pki","public-key-infrastructure","ssl","ssl-certificates","tls","tls-certificate"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ansibleguy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"ansible0guy","github":"ansibleguy"}},"created_at":"2023-02-15T19:17:48.000Z","updated_at":"2024-07-21T05:16:23.000Z","dependencies_parsed_at":"2024-06-02T11:42:32.355Z","dependency_job_id":"a9c25f81-f41f-4931-983f-9b44e73baf3e","html_url":"https://github.com/ansibleguy/infra_pki","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansibleguy%2Finfra_pki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansibleguy%2Finfra_pki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansibleguy%2Finfra_pki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansibleguy%2Finfra_pki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ansibleguy","download_url":"https://codeload.github.com/ansibleguy/infra_pki/tar.gz/refs/heads/latest","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244754960,"owners_count":20504810,"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","ansible-role","certificate","certificate-authorities","certificate-authority","certificate-generation","certificate-generator","certificates","easyrsa","easyrsa-pki","easyrsa3","iac","infrastructure-as-code","it-automation","pki","public-key-infrastructure","ssl","ssl-certificates","tls","tls-certificate"],"created_at":"2024-12-28T06:17:29.687Z","updated_at":"2025-03-21T07:26:51.528Z","avatar_url":"https://github.com/ansibleguy.png","language":"Shell","funding_links":["https://ko-fi.com/ansible0guy","https://github.com/sponsors/ansibleguy"],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://en.wikipedia.org/wiki/Public_key_infrastructure\"\u003e\n  \u003cimg src=\"https://github.com/ansibleguy/infra_pki/blob/latest/docs/pki.svg\" alt=\"Public Key Infrastructure\" width=\"600\"/\u003e\n\u003c/a\u003e\n\n# Ansible Role - Public Key Infrastructure (PKI)\n\nRole to provision and manage one or multiple [PKI's](https://en.wikipedia.org/wiki/Public_key_infrastructure) on the target server.\n\nThe [EasyRSA script](https://easy-rsa.readthedocs.io/en/latest/) is used as 'backend' to simplify the automation process.\n\n[![Lint](https://github.com/ansibleguy/infra_pki/actions/workflows/lint.yml/badge.svg)](https://github.com/ansibleguy/infra_pki/actions/workflows/lint.yml)\n[![Ansible Galaxy](https://badges.ansibleguy.net/galaxy.badge.svg)](https://galaxy.ansible.com/ui/standalone/roles/ansibleguy/infra_pki)\n\n**Molecule Integration-Tests**:\n\n* Status: [![Molecule Test Status](https://badges.ansibleguy.net/infra_pki.molecule.svg)](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/molecule.sh.j2) |\n[![Functional-Tests](https://github.com/ansibleguy/infra_pki/actions/workflows/integration_test_result.yml/badge.svg)](https://github.com/ansibleguy/infra_pki/actions/workflows/integration_test_result.yml)\n* Logs: [API](https://ci.ansibleguy.net/api/job/ansible-test-molecule-infra_pki/logs?token=2b7bba30-9a37-4b57-be8a-99e23016ce70\u0026lines=1000) | [Short](https://badges.ansibleguy.net/log/molecule_infra_pki_test_short.log) | [Full](https://badges.ansibleguy.net/log/molecule_infra_pki_test.log)\n\nInternal CI: [Tester Role](https://github.com/ansibleguy/_meta_cicd) | [Jobs API](https://github.com/O-X-L/github-self-hosted-jobs-systemd)\n\n**Tested:**\n* Debian 11\n* Debian 12\n\n----\n\n## Install\n\n```bash\n# latest\nansible-galaxy role install git+https://github.com/ansibleguy/infra_pki\n\n# from galaxy\nansible-galaxy install ansibleguy.infra_pki\n\n# or to custom role-path\nansible-galaxy install ansibleguy.infra_pki --roles-path ./roles\n\n# install dependencies\nansible-galaxy install -r requirements.yml\n```\n\n----\n\n## Advertisement\n\n* Need **professional support** using Ansible? Contact us:\n\n  E-Mail: [contact@oxl.at](mailto:contact@oxl.at)\n\n  Tel: [+43 3115 40 900 0](tel:+433115409000)\n\n  Web: [EN](https://www.o-x-l.com) | [DE](https://www.oxl.at)\n\n  Language: German or English\n\n* You want a simple **Ansible GUI**?\n\n  Check-out this [Ansible WebUI](https://github.com/ansibleguy/webui)\n\n----\n\n## Usage\n\n### Config\n\nDefine the config as needed:\n\n### Example\n\nYou can find a more detailed example here: [Example](https://github.com/ansibleguy/infra_pki/blob/latest/Example.md)\n\n#### Minimal setup\n\n```yaml\npki:\n  crl_distribution:\n    domain: 'crl.ansibleguy.net'\n\n  instances:\n    root:\n      pwd_ca: !vault |\n        $ANSIBLE_VAULT;1.1;AES256\n        ...\n\n      sub_cas:\n        main:\n          pwd_ca: !vault |\n            $ANSIBLE_VAULT;1.1;AES256\n            ...\n\n          certs:\n            server:  # server certificates\n              ansibleguy_net:\n                cn: 'AnsibleGuy Website'\n                san:\n                  dns: ['www.ansibleguy.net', 'ansibleguy.net']\n                  ip: '135.181.170.217'\n                  uri: 'https://www-ansibleguy.net'\n\n            client:  # client certificates\n              workstation1:\n                cn: 'AnsibleGuy Workstation'\n```\n\n\nYou might want to use 'ansible-vault' to encrypt your passwords:\n```bash\nansible-vault encrypt_string\n```\n\n### Execution\n\nRun the playbook:\n```bash\nansible-playbook -K -D -i inventory/hosts.yml playbook_pki.yml\n```\n\nThere is also an 'entrypoint' for managing single certificates - that can be useful if they are automagically managed by other roles.\n```bash\n# to run it interactively\nansible-playbook -K -D -i inventory/hosts.yml playbook_single_cert.yml\n```\n\n\nThere are also some useful **tags** available:\n* instances =\u003e skip basic tasks but process all PKI-instances (RootCA's)\n* subcas =\u003e skip basic and instance (RootCA) tasks but process all SubCA tasks\n* certs =\u003e only process task related to managing certificates\n* certs_create =\u003e create non-existent certificates\n* certs_renew =\u003e renew certificates that have the state 'renewed' set\n* certs_revoke =\u003e revoke certificates that have the state 'revoked' or 'absent' set\n\nTo debug errors - you can set the 'debug' variable at runtime:\n```bash\n# WARNING: Will log passwords!\nansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e debug=yes\n```\n\nNote: `--check` mode is not supported by this role as it heavily depends on scripted command-tasks.\n\n----\n\n## Functionality\n\n* **Package installation**\n  * OpenSSL\n\n\n* **Configuration**\n  * Usage of a group to allow read-only access to public-keys\n\n\n  * **Default config**:\n    * Paths:\n      * PKI base: '/var/local/lib/pki'\n      * Script: '/usr/local/sbin/easyrsa'\n    * PKI user: 'pki'\n    * Read-only group: 'pki_read'\n    * **EasyRSA vars**:\n      * Expiration:\n        * Root-CA: 20 years\n        * Sub-CA: 15 years\n        * Certificates: 3 years\n      * Digest:\n        * Root-CA: sha512\n        * Sub-CA/Certificates: sha256\n      * Algorithm: rsa\n      * Key size: 4096\n    * Certificates:\n      * Don't password-encrypt certificate private-keys\n      * Export formats:\n        * pkcs12 (_private/\u003ccert\u003e.p12_)\n        * certificate chain (_issued/\u003ccert\u003e.chain.crt_)\n \n\n  * **Default opt-ins**:\n    * Adding dedicated PKI-user and read-only group\n    * Saving CA/Sub-CA/Certificate passwords to files for easier automation\n      * See the information below for alternatives\n    * Installation and configuration of a Nginx webserver to server CRL's and CA-PublicKey's (_not yet implemented_)\n\n\n  * **Default opt-outs**:\n    * Purging of orphaned (_existing but not configured_) certificates\n    * Encryption of certificate private-keys (_non CA/Sub-CA_)\n\n----\n\n## Info\n\n\n* **Note:** Most of the role's functionality can be opted in or out.\n\n  For all available options - see the [default-config located in the main defaults-file](https://github.com/ansibleguy/infra_pki/blob/latest/defaults/main/1_main.yml)!\n\n\n* **Info:** To make sure the role config 'behaves' as expected - it tested by this role using molecule!\n\n  Per example: The certificate-attributes, file- \u0026 directory-permissions \u0026 -ownership are checked after generating multiple certificates using multiple Root- \u0026 Sub-CA's.\n\n  See [Verification Tests](https://github.com/ansibleguy/infra_pki/blob/latest/molecule/default/verify.yml)\n\n\n* **Warning:** Not every setting/variable you provide will be checked for validity. Bad config might break the role!\n\n\n* **Note:** If you want to read more about PKI's and certificates:\n\n  * The EasyRSA project has a [nice documentation](https://easy-rsa.readthedocs.io/en/latest/intro-to-PKI/)\n  * For (_x509_) certificates check out the [OpenSSL documentation](https://www.openssl.org/docs/man1.0.2/man5/x509v3_config.html).\n  * If you want to read a good explanation of how 'keyUsage' and 'extendedKeyUsage' are to be used - check out this StackExchange answer: [LINK](https://superuser.com/questions/738612/openssl-ca-keyusage-extension/1248085#1248085)\n  * If you want to know how to manually create a PKI/SubCA's using EasyRSA - check out [@QueuingKoala](https://gist.github.com/QueuingKoala)'s clean example on how to do that: [GitHub Gist](https://gist.github.com/QueuingKoala/e2c1c067a312384915b5) \n\n\n* **Warning:** For gained security against CA-compromise you should:\n\n  1. Make sure all your needed Sub-CA's are created by the role\n  2. Copy the CA private-key (_${path_base}/ca/private/ca.key_) to an offline medium (_keep redundancy in mind_)\n  3. Save the password you used to initialize the CA (_not on the same medium_)\n  4. Remove the ca.key file from your Online-system using a 'secure-deletion' tool like 'shred':\n  \n      ```bash\n      shred -vzu -n10 ca.key\n      ```\n\n\n* **Note:** You have multiple options to supply the CA/Sub-CA/Certificate passwords:\n\n  * if 'save_passwords' is set to true - the saved password will be retrieved after the CA is initialized\n  * as inventory variable (_ansible-vault encrypted to be decrypted at runtime_)\n  * --extra-vars at runtime\n  * if no password was set, the role will prompt for one at runtime\n\n\n* **Note:** Certificate variables you set on:\n\n  * global level will be inherited by all instances and their sub-ca's\n  * instance-level will be inherited by its sub-ca's\n  * specific config on instance/subca level will always override the inherited one\n\n\n* **Note:** You can find scripts for automated certificate-expiration monitoring that can be integrated with monitoring systems like [Zabbix](https://www.zabbix.com/documentation/current/en/manual/discovery/low_level_discovery) at [files/usr/local/bin/monitoring](https://github.com/ansibleguy/infra_pki/tree/latest/files/usr/local/bin/monitoring).\n\n\n* **Warning:** The CRL-Distribution settings **CANNOT BE CHANGED** easily.\n\n  All existing certificates would have to be re-generated once the settings are changed.\n\n\n* **Note:** The 'cert_expire' variable of the root-ca will set the runtime of the sub-ca's!\n\n\n* **Note:** Passwords used for CA/Sub-CA/Certificate encryption are checked for complexity rules:\n\n  * min. 8 characters long\n  * must contain\n    * number\n    * uppercase letter\n    * lowercase letter\n\n\n* **Note:** **Certificates states** can be set to either:\n\n  * 'present' or 'created' to make sure a certificate exists\n  * 'absent' or 'revoked' to make sure a certificate does not exist\n  * 'renewed' to renew a certificate\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansibleguy%2Finfra_pki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fansibleguy%2Finfra_pki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansibleguy%2Finfra_pki/lists"}