{"id":25190052,"url":"https://github.com/keyfactor/hashicorp-vault-secretsengine","last_synced_at":"2025-05-07T18:24:46.468Z","repository":{"id":62224513,"uuid":"470768769","full_name":"Keyfactor/hashicorp-vault-secretsengine","owner":"Keyfactor","description":"Plugin for HashiCorp Vault to allow certificate enrollment, signing and revocation via the Keyfactor CA.","archived":false,"fork":false,"pushed_at":"2025-03-24T17:10:41.000Z","size":31841,"stargazers_count":11,"open_issues_count":13,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-31T12:58:07.397Z","etag":null,"topics":["golang-module","hashicorp-vault","keyfactor-api-client","keyfactor-integration"],"latest_commit_sha":null,"homepage":"","language":"Go","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/Keyfactor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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}},"created_at":"2022-03-16T22:19:49.000Z","updated_at":"2025-02-04T21:05:26.000Z","dependencies_parsed_at":"2024-01-19T21:26:04.404Z","dependency_job_id":"8ed936e7-a9d6-4857-bd4c-300c7a18a459","html_url":"https://github.com/Keyfactor/hashicorp-vault-secretsengine","commit_stats":null,"previous_names":[],"tags_count":79,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keyfactor%2Fhashicorp-vault-secretsengine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keyfactor%2Fhashicorp-vault-secretsengine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keyfactor%2Fhashicorp-vault-secretsengine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keyfactor%2Fhashicorp-vault-secretsengine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Keyfactor","download_url":"https://codeload.github.com/Keyfactor/hashicorp-vault-secretsengine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252932607,"owners_count":21827338,"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":["golang-module","hashicorp-vault","keyfactor-api-client","keyfactor-integration"],"created_at":"2025-02-09T21:18:47.262Z","updated_at":"2025-05-07T18:24:46.452Z","avatar_url":"https://github.com/Keyfactor.png","language":"Go","readme":"\n# keyfactor-vault-secrets-engine\n\nA Vault plugin that allows Vault to use Keyfactor Command as a CA and issue certificates.\n\n#### Integration status: Production - Ready for use in production environments.\n\n## About the Keyfactor API Client\n\nThis API client allows for programmatic management of Keyfactor resources.\n\n## Support for keyfactor-vault-secrets-engine\n\nkeyfactor-vault-secrets-engine is open source and community supported, meaning that there is no support guaranteed from Keyfactor Support for these tools.\n\n###### To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab.\n\n---\n\n\n---\n\n\n\n# Hashicorp Vault Secrets Engine\n\nKeyfactor enables DevOps teams to get seamless access to trusted internal and public certificates via native Vault API\ncalls and commands, while security teams maintain complete visibility and control over backend PKI operations.\n\n## About the Hashicorp Vault Secrets Engine plugin by Keyfactor\n\nThe Keyfactor Secrets Engine provides a PKI backend for Vault to issue trusted certificates via the Keyfactor platform.\nIt enables developers to use native Vault API calls and\ncommands to request certificates from Keyfactor and allows security teams to maintain visibility and control over all\ncertificates issued to Vault instances.\nThis plugin connects Vault with trusted public, private, or cloud-hosted CAs configured in the Keyfactor platform.\nCertificates are requested through Vault using standard Vault commands, and are then redirected to Keyfactor so that the\ncertificates can be issued off of a trusted enterprise certificate authority. After issuance, the certificate is then \nreturned to Hashicorp Vault and stored within the Vault Secrets store to then be used in other applications.\n\n---\n\n## Table of contents\n\n- [Overview](#overview)\n- [Compatibility](#compatibility)\n- [Installation Requirements](#installation-requirements)\n    - [Keyfactor Requirements](#keyfactor-requirements)\n    - [Hashicorp Vault Requirements](#hashicorp-vault-requirements)\n- [Installation - Keyfactor](#installation---keyfactor)\n    - [Create the Active Directory service account](#create-the-active-directory-service-account)\n    - [Create a certificate template](#create-a-certificate-template)\n    - [Publish the template for the Certificate Authority](#publish-the-template-for-the-certificate-authority)\n- [Installation - Vault](#installation---vault)\n    - [Check the Vault server status](#check-the-vault-server-status)\n    - [Install and register the plugin](#install-and-register-the-plugin)\n    - [Configure the plugin](#configure-the-plugin)\n    - [Adding Roles](#adding-roles)\n- [Using the plugin](#using-the-plugin)\n    - [Issuing Certificates](#issuing-certificates)\n    - [Viewing Certificates](#viewing-certificates)\n- [Command Reference](#plugin-command-reference)\n    - [Create/update configuration](#createupdate-configuration)\n    - [Read configuration](#read-configuration)\n    - [Create/update Roles](#createupdate-role)\n    - [List roles](#list-roles)\n    - [Read a role](#read-role)\n    - [Delete a role](#delete-role)\n    - [Request a certificate](#request-certificate)\n    - [List certificates](#list-certificates)\n    - [View a certificate](#read-certificate)\n    - [Revoke a certificate](#revoke-certificate)\n    - [Sign a CSR](#sign-csr)\n    - [View CA Certificate](#read-ca-cert)\n    - [View CA Certificate Chain](#read-ca-chain)\n\n## Overview\n\nThe Keyfactor Secrets Engine for Hashicorp Vault is a Vault plugin that replicates Vault’s onboard PKI API and processes\ncertificate enrollment requests through the Keyfactor Command or Keyfactor Control platform. In many cases the onboard\nPKI engine included with Vault can be swapped for the Keyfactor engine seamlessly, with no impact to Vault client\napplications. While the simplicity of the onboard PKI is attractive to developers who are trying to implement the\nsimplest solution in order to meet encryption requirements, it presents other enterprise teams with some challenges when\nit comes to PKI operations and security:\n\n- The Vault infrastructure and root materials are not managed by PKI professionals and policies, but rather by DevOps\n  teams that may not be trained in how to properly handle and manage an enterprise PKI.\n- Lack of Certificate Lifecycle Management places organizations in a reactionary posture. If there are weaknesses in the\n  organization processes, full visibility of the certificates is necessary in order to identify these risks prior to a\n  security event or audit failure.\n- All certificates are susceptible as an attack surface and should be managed and monitored, regardless of their\n  lifetime, to ensure that issuance policies and certificate standards are followed.\n\nKeyfactor Command can provide the control and visibility needed for a Vault environment. Using the Keyfactor Secrets\nEngine plugin for Vault, PKI functionality is directed to your enterprise PKI environment, placing control back into the\nhands of the enterprise PKI admins, and allowing your PKI admins to stay in control of how and when certificates are\nissued. The Keyfactor Secrets Engine offers the following enterprise capabilities:\n\n- Issue certificates and place them into the Vault secrets store using your existing enterprise PKI.\n- Eliminate the need for a standalone PKI within the vault environment.\n- Gain complete visibility and management of certificates across all Vault instances and manage them through a single\n  pane of glass.\n- Reporting, alerting, automation, and auditing on the certificates within the environment.\n- Easily identify and revoke non-compliant or rogue certificates.\n- Integrate with SIEMs and ticketing systems for automated notifications.\n\n  ![\"high-level-architecture\"](images/arch-diagram.png)\n\n\u003e [!IMPORTANT]\n\u003e The Keyfactor Vault Secrets Engine is designed to be a drop in replacement for the native\n\u003e Vault CA, and implements most of the functionality provided by the PKI secrets engine\n\u003e to enable enterprise grade certificate management for certificates requested via\n\u003e Vault. There are some important security differences when using the Keyfactor plugin,\n\u003e namely in how certificate issuance polices are enforced. The plugin only supports domain\n\u003e and subdomain restrictive role polices and defers to the Command infrastructure for it's\n\u003e issuance security model based on certificate templates. The only role parameters utilized\n\u003e by this secrets engine are \"AllowedDomains\" and \"AllowSubDomains\". Other parameters\n\u003e utilized by the Vault native PKI secrets engine, such as \"TTL\", \"KeyType\", \"AllowIPSANs\",\n\u003e etc. For reference, the full list of fields supported by the Vault PKI secrets engine can\n\u003e be found [here](https://developer.hashicorp.com/vault/api-docs/secret/pki#list-roles).\n\u003e When architecting a solution, consideration should be given to the\n\u003e native Vault policies, the roles implemented by the secrets engine plugin, and the template\n\u003e rules available in Command.\n\n## Compatibility\n\nThis Vault Plugin has been tested against Hashicorp Vault version 1.10+ and the Keyfactor Platform 9.6+. We provide\nseveral pre-built binary files that correspond to various operating systems and processor architectures. If not building\nthe plugin from source code, select the os/architecture combination that corresponds to your environment.\n\n## Installation Requirements\n\nThe requirements for the plugin are relatively simple. It runs as a single executable on the Hashicorp Vault server.\nThere are no specific system requirements to install it, however there are a few general things that must be in place\nfor\nit to function properly. These requirements are listed below, and are then expanded in the details throughout this\ndocument.\n\n### Keyfactor Requirements\n\n- A functional instance of Keyfactor Command\n- An administrative user account to be used for configuring the Keyfactor options needed for the implementation\n- A functional integrated certificate authority to be used for issuing the certificates\n- A certificate template (or templates) defined to use for certificate issuance.\n- A user account with permissions to connect to the Keyfactor API and submit certificate requests. This user account\n  will require READ and ENROLL permissions on the certificate template that you will use for the Vault plugin.\n\n### Hashicorp Vault Requirements\n\n- A functional Hashicorp Vault Installation **version 1.10.xx or greater**.\n- An administrative account with permission to login to the Hashicorp Vault server in order to make administrative\n  changes.\n- An adequate number of unseal keys to meet the minimum criteria to unseal the Hashicorp Vault\n- A Hashicorp Vault login token\n\n## Installation - Keyfactor\n\n### Create the Service Account in Command\n\nThis plugin can authenticate via username/password, TLS certificate authentication, and oAuth/openIDConnect.  \n\nFor the purposes of this document, we will not go into the details of how to create each type of service entity.\nRefer to the Keyfactor platform documentation for guidance on creating these service accounts. \n\nThe configuration of the plugin will differ slightly for each different approach.  Here is a table with the values \nneeded for authentication for each approach:\n\n| basic | oAuth | TLS |\n| ----------------- | ----- | --- |\n| Username          | Client ID | Certificate Path |\n| Password          | Client Secret | |\n| AD Domain         | Token Endpoint | |\n\nThese values will be discussed in greater detail in the [Configure the plugin](#configure-the-plugin) section of this document.\n\n### Assign the user permissions in Keyfactor Command\n\nIn order to be able to enroll for certificates through the Keyfactor Command API, it will be necessary to create the\nnecessary role and delegate permissions within Keyfactor. It is not a requirement that this be a new role. If there is\nan existing role within your organization that allows for these basic permissions, that role can be used for this\nconnection. If you do not have an existing role, and would like to create one, those steps are described later in this\ndocument.\n\n### Create a certificate template\n\nThe first step to configuring Keyfactor is to create the certificate template that will be used for the enrollment and\npublish it into Keyfactor.  This template can be created in Active Directory for AD based Certificate Authorities, or created as \nCertificate Profiles in EJBCA and imported into Command.\n\nRefer to the Keyfactor Command documentation for instructions on how to create a Certificate Template in Command.\n\n### Allow the template to be used for CSR enrollment through Keyfactor\n\nOnce the template has been imported into Keyfactor Command, it is then necessary to enable that template for CSR\nenrollment through the console.\n\nTo enable CSR enrollment on the template:\n\n1. Select Locations from the top menu bar, then select \"Certificate Templates\"\n   ![\"template8\"](images/template8.png)\n\n1. Look through the list to locate the certificate template that was created and previously imported into the Keyfactor\n   console. Double Click on that template.\n   ![\"template11\"](images/template11.png)\n\n1. On the properties tab for the template, enable CSR enrollment. Then click Save\n   ![\"template12\"](images/template12.png)\n\n## Installation - Vault\n\nThis document covers configuration of the Keyfactor Secrets Engine Plugin for Hashicorp Vault, and assumes that there is\na running Vault environment in place. This document does not cover the steps necessary to do the initial install and\nconfiguration of Hashicorp Vault.\n\nOn the server that will host the vault plugin, it will be necessary to setup the appropriate environment variables and\nconfiguration files to enable the plugin to run and establish a connection back to Keyfactor Command. The specific\nsyntax for setting environment variables will differ slightly between Windows and Linux distributions, but the approach\nis the same.\n\n### Check the Vault server status\n\nHashicorp Vault must be installed and running to install and register the Keyfactor Secrets Plugin. To check the status\nof the Vault installation on the server being used, log into the Vault server with a logon account that has sufficient\nadministrative privileges, and issue the following command:\n\n`vault status`\n\nThe results returned should look something like this:\n\n![\"vault1\"](images/vault1.png)\n\nThere are 2 key values to look for in these results:\n\n1. **Initialized** – Verify that the vault has been initialized and the status shows TRUE. If this value is FALSE, it\n   means that this is a new instance of Vault that has not yet been initialed. You will need to go through a Vault\n   initialization using the \"vault operator init\" command prior to proceeding.\n\n1. **Unsealed** – In order to perform operations against a vault instance, the vault must be unsealed with the unlock\n   keys that were generated during the initialization process. Vault has a (m of n) key requirement… so for instance 3\n   of the 5 keys must be entered to unseal the vault. (This requirement can vary based on configuration) If the current\n   status of the vault shows SEALED then it is necessary to enter these keys to unseal the vault. These keys can be\n   entered individually (and potentially by different people or processes)\n\n```\n# vault operator unseal 3TGWPmQDdqkRsV9VamEYJ0tolsaEEo3u4kuwy2o6u6Om\n# vault operator unseal Ja4AGQ4N8193/5O7hJPpRcncmqBpnH1mdjqcQSqDVq6v\n# vault operator unseal cuE1X01NrNgeAU6ao5aNUFsjWAPhOgEPkgaW5Vl19XDg\n```\n\nor they can be all issued within a single command as illustrated below:\n\n```\n# vault operator unseal 3TGWPmQDdqkRsV9VamEYJ0tolsaEEo3u4kuwy2o6u6Om \u0026\u0026 vault operator unseal\nJa4AGQ4N8193/5O7hJPpRcncmqBpnH1mdjqcQSqDVq6v \u0026\u0026 vault operator unseal\ncuE1X01NrNgeAU6ao5aNUFsjWAPhOgEPkgaW5Vl19XDg\n```\n\nOnce the appropriate number of keys has been entered, the status should indicate \"Unsealed = True\"\n\n### Install and register the plugin\n\nTo install and register the plugin on the Vault server, follow these steps:\n\n1. Copy the Keyfactor plugin binary into a directory on the Vault server using SFTP or another file copy process. The\n   location of this file does not really matter, but typically would be in a Vault plugins directory.\n\n   An example plugins path may look like this:\n\n   `/usr/bin/vault/plugins`\n\n1. Set the file to be executable.\n\n   `chmod +x keyfactor`\n\n1. The sha256 checksum should have been provided in the release zip file.  \n   If you are building the plugin from scratch, you can run the following command to get this value:\n\n   `sha256sum ./keyfactor`\n\n   The result will show the sha256 value that will be needed in the next step.\n\n1. Registering the new secrets engine within Vault is done using a vault plugin command to register the plugin into the\n   Vault secrets catalog.\n\n   Linux:\n\n   `# vault plugin register -sha256=47f549d44ab2abcb528aa45725b3a83334a9465bb487f3d1182add55e5580c36 secret \u003cinstance name\u003e`\n\n   Windows:\n\n   `\u003e vault plugin register -sha256=97a76ee45f8bbc3e852520cba38d16206f6a92ab0b8a2d2bbd7eaaae064ae9bf -command=\"keyfactor.exe\" secret \u003cinstance name\u003e`\n\n   \u003e Windows requires the binary to have a recognized executable extension, so we name the windows executable\n   keyfactor.exe.\n\n   The result should look like this: `Success! Registered plugin: \u003cinstance name\u003e`\n\n   \u003e _For the rest of this document, we will assume that the instance of the plugin is named \"keyfactor\"._\n\n1. Enable the plugin within Hashicorp Vault\n   Once the plugin is installed into Vault, it just needs to be enabled. As a part of this enable process, you must\n   specify the endpoint name that will be used for the secrets engine. This name is arbitrary. For this example, we are\n   using keyfactor as the enpoint name, but it can be named to match existing endpoints that you are looking to replace\n   with a connection to Keyfactor if necessary.\n\n   run the following command:\n\n   `vault secrets enable keyfactor`\n\n   if successful the output should look like this:\n\n   `Success! Enabled the keyfactor secrets engine at: keyfactor/`\n\n1. Check the registered paths for the plugin\n   The Hashicorp vault plugin architecture generates endpoints for each plugin. Run the vault `path-help` command to\n   view the registered paths.\n\n   `vault path-help keyfactor`\n\n   the output should look similar to the following:\n\n```\n\n## DESCRIPTION\n\nThe Keyfactor backend is a pki service that issues and manages certificates.\n\n## PATHS\n\nThe following paths are supported by this backend. To view help for\nany of the paths below, use the help command with any route matching\nthe path pattern. Note that depending on the policy of your auth token,\nyou may or may not be able to access certain paths.\n\n    ^ca\n        Fetch a CA, CRL, CA Chain, or non-revoked certificate.\n        pass \"ca=\u003cca name\u003e\" to retrieve them for a CA other than the one set in the configuration.\n\n    ^ca_chain\n        Fetch a CA, CRL, CA Chain, or non-revoked certificate.\n        pass \"ca=\u003cca name\u003e\" to retrieve them for a CA other than the one set in the configuration.\n\n    ^certs/?$\n        Use with the \"list\" command to display the list of certificate serial numbers for certificates managed by this secrets engine.\n\n    ^certs/(?P\u003cserial\u003e[0-9A-Fa-f-:]+)$\n        Fetch a CA, CRL, CA Chain, or non-revoked certificate.\n\n    ^config$\n        Configure the Keyfactor Secrets Engine backend.\n\n    ^issue/(?P\u003crole\u003e\\w(([\\w-.]+)?\\w)?)$\n        Request a certificate using a certain role with the provided details.\n        example: vault write keyfactor/issue/\u003crole\u003e common_name=\u003ccn\u003e dns_sans=\u003cdns sans\u003e\n\n    ^revoke/(?P\u003cserial\u003e[0-9A-Fa-f-:]+)$\n        Revoke a certificate by serial number.\n\n    ^roles/?$\n        List the existing roles in this backend\n\n    ^roles/(?P\u003cname\u003e\\w(([\\w-.]+)?\\w)?)$\n        Manage the roles that can be created with this backend.\n\n    ^sign/(?P\u003crole\u003e\\w(([\\w-.]+)?\\w)?)$\n        Request certificates using a certain role with the provided details.\n        example: vault write keyfactor/sign/\u003crole\u003e csr=\u003ccsr\u003e\n\n```\n\nIf you see this, you have successfully installed the plugin.  Now we can configure it for connecting with Command for certificate enrollment.\n\n### Configure the plugin\n\nOnce the plugin has been successfully installed, the next step is to set the configuration values that will allow it to\ninteract with the Keyfactor platform.\n\nThe Keyfactor plugin implements a per-instance configuration which allows multiple instances of the plugin to exist\nsimultaneously. This could be useful for creating multiple instances of the plugin; each scoped to a specific Command service account identity that \nis specific to a particular issuance workflow.\n\nTo set a configuration value:\n\n`vault write \u003cinstance name\u003e/config \u003ckey\u003e=\"\u003cvalue\u003e\"`\n\nHere is a table of the available configuration paramaters\n| name | value type | required | default | description |\n| ---- | ---------- | -------- | ------- | ----------- |\n| **url**  | string     | yes      | | The url pointing to the keyfactor platform with no trailing slashes **(example: \"https://kftrain.keyfactor.lab\")** |\n| **api_path** | string | no       | _\"KeyfactorAPI\"_ | The path after the Command instance url to reach the Keyfactor API |\n| **ca**    | string | no[^1]      | |  | The certificate authority used when issuing certificates via the plugin **(example: kftrain.keyfactor.lab\\\\\\\\keyfactor-KFTRAIN-CA)** |\n| **template** | string | no[^1]   | | The certificate template name to use when issuing certificates. It should be issuable by the CA |\n| **username** | string | no[^2]   | | basic authentication: username |\n| **domain** | string | no[^2]     | | basic authentication: Active Directory Domain |\n| **password** | string | no[^2]   | | basic authentication: password |\n| **client_id** | string | no[^3]  | | oAuth authentication: client ID |\n| **client_secret** | string | no[^3] | |oAuth authentication: Client Secret |\n| **token_url** | string | no[^3]  | | oAuth authentication: Endpoint for retreiving the authentication token |\n| **access_token** | string | no   | | oAuth access token, if retrieved outside the context of the plugin |\n| **scopes** | []string (comma separated list) | no | | the defined scopes to apply to the retreived token in the oAuth authorization flow.  If not provided, all available scopes for the service account will be assigned to the token upon authentication |\n| **audience** | string | no | | the OpenID Connect v1.0 or oAuth v2.0 token audience |\n| **skip_verify** | bool | no | _false_ | set this to true to skip checking the CRL list of the HTTPS endpoint |\n| **command_cert_path** | string | no | | set this value to the local path of the CA cert if it is untrusted by the client and skip_verify is false\n\n[^1]: The **ca** and **template** fields can be provided via command line parameters.  If they are not provided, the plugin will default to what is set in the configuration values.  If neither are available an error will occur.\n\n#### Basic Authentication Configuration\n\nIf you are using basic authentication to Keyfactor Command, you will also need to set the following values:\n\n- **domain**\n    - The Active Directory domain of the account **(example: \"KEYFACTOR\")**\n- **username**\n    - The username of the account used for authenticating to the platform excluding the domain **(example: \"VaultUser\")**\n- **password**\n    - The password corresponding to the user account for authenticating to the platform.\n\n[^2]: While none of these configuration values are explicitly required; they are _all_ required in order to use basic (username/password) authentication into Command.\n\n#### OpenID Connect / oAuth Configuration\n\nIf you are using an oAuth or OpenID Connect provider to authenticate into Keyfactor Command, you will also need to set the following values:\n- **client_id**\n    - The client ID of the service principal account used to authenticate\n\n- **client_secret**\n    - The client secret value generated via the identity provider when the service account was created \n\n- **token_url**\n    - The url where the token can be requested\n\n[^3]: While none of these configuration values are explicitly required; they are _all_ required in order to use openID Connect / oAuth authentication into Command.\n\n##### Access Token\n\nRather than have the plugin perform the oAuth/OpenID authentication workflow, it is also possible to retreive the access token yourself and provide it in the configuration.\nIf a valid access token is provided then the values for **client_id**, **client_secret** or **token_url** are not required.\n\nOnce you've set the configuration properties, run the command:\n`vault read \u003cinstance name\u003e/config`\nin order to view the configuration settings (see example below).\n\n![\"configread\"](images/configread.png)\n\n\u003e [!NOTE]\n\u003e By default the sensitive values (password, client_secret) are hidden.  To show these, pass the \"show_hidden=true\" parameter to the request; `vault read \u003cinstance name\u003e/config show_hidden=true`\n\n\n### Adding Roles\n\nHashicorp Vault supports being able to add roles to control certificate issuance policies for allowed domains and\nallowing sub-domain certificates to be created.\nTo create a role, use the vault write command as in the below example.\n\n`vault write keyfactor/roles/hashiwebserver allowed_domains=kftrain.lab allow_subdomains=true`\n\nThis will create a role called \"hashiwebserver\" that can be used to generate certificates for domains ending with \"\nkftrain.lab\".\n\n\u003e [!NOTE]\n\u003e Use \"*\" for the value in \"allowed_domains\" to allow issuing for any domain.\n\nThese properties can also be set in the certificate template configured in Command. If they differ, the most restrictive setting is applied.\n\n## Using the plugin\n\n### Issuing Certificates\n\nWhen requesting a certificate using the Keyfactor plugin, the command is the same as if you were issuing the certificate\nthrough the vault integrated PKI. As a part of the write command you will specify the role name you would like to use,\nas well as the common name on the certificate. A typical certificate issuance command is listed below for the\nhashiwebserver role, and a CN of foo.kftrain.lab on the certificate.\n\n`vault write keyfactor/issue/hashiwebserver common_name=foo.kftrain.lab dns_sans=foo.kftrain.lab`\n\nThe resulting response will show the certificate data response for the request. This certificate will also be stored in\nthe Vault secrets store.\n\n![\"vault3\"](images/vault3.png)\n\n\u003e [!NOTE]\n\u003e The Certificate Authority and Template values can be passed via command parameters.  If they are omitted, the values set in the configuration are used.\n\n\u003e [!NOTE]\n\u003e As of v1.4, certificate Metadata is able to be provided in the command line and submitted along with the signing request.\n\u003e example: `vault write keyfactor/issue/hashiIssuer common_name=\"test.com\" dns_sans=\"test.com\" metadata='{ \\\"testMetadata\\\": \\\"arbitrary string value\\\" }' ca=\"myCA\"`\n\u003e **Make sure that the quotation marks as escaped, as above, or an error will be returned.**\n\n### Viewing Certificates\n\nAfter certificates are stored in the secrets store, you can then retrieve those certificates at a later time if\nnecessary. To list the certificates that exist within the Vault store, use the LIST option with vault. The only\nparameter that you need to include is the secrets store name for the store that you would like to read. The system will\nthen return a list of all of the serial numbers for certificates that are present in that secrets store.\n\n`vault list keyfactor/certs`\n\nThe results of the command will be a list of serial numbers for the certificates in that store location:\n\n```\nKeys\n----\n750000276546d818cbe70231b6000000002765\n750000276623facfaddb6c4ca1000000002766\n```\n\nIf you would like to retrieve a specific certificate from the store, you can do so by using the \"vault read\" command,\nand specifying the serial number of the certificate that you would like returned. The format for the command looks like\nthis:\n\n`vault read keyfactor/cert/\u003cserial\u003e`\n\nexample:\n\n`vault read keyfactor/cert/750000276546d818cbe70231b6000000002765`\n\nThe response will show the value for that certificate.\n\n```\nKey                Value\n---                -----\ncertificate        -----BEGIN CERTIFICATE-----\nLS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlGZXpDQ0JHT2dBd0lCQWdJ\nVGRRQUFKMlZHMkJqTDV3SXh0Z0FBQUFBblpUQU5CZ2txaGtpRzl3MEJBUXNGDQpB\nREJQTVJNd0VRWUtDWkltaVpQeUxHUUJHUllEYkdGaU1Sa3dGd1lLQ1pJbWlaUHlM\nR1FCR1JZSmEyVjVabUZqDQpkRzl5TVIwd0d3WURWUVFERXhSclpYbG1ZV04wYjNJ\ndFMwWlVVa0ZKVGkxRFFUQWVGdzB5TWpBME1qSXhOVE0xDQpNVGxhRncweU1qQTNN\nakV4TlRNMU1UbGFNQm94R0RBV0JnTlZCQU1URDNWMWRTNXJablJ5WVdsdUxteGhZ\nakNDDQpBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQ0FRb0NnZ0VCQU9h\nMmEwQzVoeWpvUHRWbWNqUGRVZlhuDQpKU3BvbkRyQ1dJT1ROcmxTcytkbWM3aFNw\nSjdTanZvcCtSZUIrRFVQWWhXbFBETWZlOGFFSEkyUFAwMGg3dVd3DQpBaHJ6T2Jk\nMmthUkhyOXZDU2h6dE1vYjBQd0JrTG9MK2JLUWRIK2xTM1RVMHpKQytidUV0WWJ3\ndHcvOGJSdFNFDQpIRWJaMXNrU1Y5RmJzWlBjb3I2WTVqcFV0ck85Y1dhbUs3d0Jw\ndkFnVHEzYk44ZWt5ZUl4R1V6YVhjRHd2aEVnDQoxcG5xS1loY3NmOU03b2R1Ullv\nUytpcy9BTmlXZllSMDZBV29odE41VHlJVXBlcnVIZEh6WWpBYXJ4RXhzWEFrDQpR\nd3BxVGF5dTFNUWU1cllYdWpyL1FEOG5EbGl5TXp6NjJINmNjRkRmWmhHNWZkVUJK\nK25uRTlTbllabDRCcmNDDQpBd0VBQWFPQ0FvTXdnZ0ovTUJvR0ExVWRFUVFUTUJH\nQ0QzVjFkUzVyWm5SeVlXbHVMbXhoWWpBZEJnTlZIUTRFDQpGZ1FVS0E0VkFhS3M5\na2RjL3VXQXR3Sm5TSUJleVM4d0h3WURWUjBqQkJnd0ZvQVVjQlV6UFc3WlF1cVVN\nUDNSDQpGVENiRFUxaFRHVXdnZFFHQTFVZEh3U0J6RENCeVRDQnhxQ0J3NkNCd0lh\nQnZXeGtZWEE2THk4dlEwNDlhMlY1DQpabUZqZEc5eUxVdEdWRkpCU1U0dFEwRXNR\nMDQ5UzBaVWNtRnBiaXhEVGoxRFJGQXNRMDQ5VUhWaWJHbGpKVEl3DQpTMlY1SlRJ\nd1UyVnlkbWxqWlhNc1EwNDlVMlZ5ZG1salpYTXNRMDQ5UTI5dVptbG5kWEpoZEds\ndmJpeEVRejFyDQpaWGxtWVdOMGIzSXNSRU05YkdGaVAyTmxjblJwWm1sallYUmxV\nbVYyYjJOaGRHbHZia3hwYzNRL1ltRnpaVDl2DQpZbXBsWTNSRGJHRnpjejFqVWt4\nRWFYTjBjbWxpZFhScGIyNVFiMmx1ZERDQnlBWUlLd1lCQlFVSEFRRUVnYnN3DQpn\nYmd3Z2JVR0NDc0dBUVVGQnpBQ2hvR29iR1JoY0Rvdkx5OURUajFyWlhsbVlXTjBi\nM0l0UzBaVVVrRkpUaTFEDQpRU3hEVGoxQlNVRXNRMDQ5VUhWaWJHbGpKVEl3UzJW\nNUpUSXdVMlZ5ZG1salpYTXNRMDQ5VTJWeWRtbGpaWE1zDQpRMDQ5UTI5dVptbG5k\nWEpoZEdsdmJpeEVRejFyWlhsbVlXTjBiM0lzUkVNOWJHRmlQMk5CUTJWeWRHbG1h\nV05oDQpkR1UvWW1GelpUOXZZbXBsWTNSRGJHRnpjejFqWlhKMGFXWnBZMkYwYVc5\ndVFYVjBhRzl5YVhSNU1BNEdBMVVkDQpEd0VCL3dRRUF3SUZvREE5QmdrckJnRUVB\nWUkzRlFjRU1EQXVCaVlyQmdFRUFZSTNGUWlEbWVSL2d1aXhNNGZaDQptUStCcTkx\nRWgrQzNLZ3VGc3F4YmhyVFlWUUlCWkFJQkNUQVRCZ05WSFNVRUREQUtCZ2dyQmdF\nRkJRY0RBVEFiDQpCZ2tyQmdFRUFZSTNGUW9FRGpBTU1Bb0dDQ3NHQVFVRkJ3TUJN\nQTBHQ1NxR1NJYjNEUUVCQ3dVQUE0SUJBUUNBDQpqa1ZBTi9hL0NtVm5DTVV2RW1V\nS0FuN1BhMFlpTmxxZVJwU2NIZ1dpYnZjc0NLM1Z1VTlSaENBdldpb1RBMytwDQpr\nVXhYL0c4LzFlOXRlcWJnaElMZ2ZtemJuWndvZU1BTHo0aFZqYmtVYy83cGpaSVBr\nejA1cXRaT1ZSUzluaEVMDQpRM0xocEFtcmZXbzYxU0l3bHl3WEowV1YxU050UEtu\nbUFvQUV2ZUIvSEpNSitkeTM1Q084Y2tOMFVidmk2OUhsDQoya1pIdE1LUWJsckk3\nZXV2MHdnVERqWVIvdms3Yjl0UWlxSmE0YURvMnRsZmF2KzF4Tk40WVdxa3R2QUth\nc3hsDQpBVW02bjdydVh5OEs4d005bEFVU2Rwb29iNzdQQ1lpTWhZRkF0ODUzQVlD\nR1N0bU1nT21Pa0F1YVVEUHNET3pQDQplUXd1S25Hdy82WDJlUXltaU1BWQ0KLS0t\nLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ0K\n-----END CERTIFICATE-----\nrevocation_time    0\n```\n\n## Plugin command reference\n\nThe following commands are supported by the Keyfactor Hashicorp Vault Secrets Engine plugin. These examples assume the\ninstance of the plugin is named \"keyfactor\".\n\n### Create/update configuration\n\n`vault write keyfactor/config \u003ckey\u003e=\u003cvalue\u003e`\n\n### Read configuration\n\n`vault read keyfactor/config`\n\n### Create/update role\n\n`vault write keyfactor/roles/\u003crolename\u003e allowed_domains=\"\u003cdomain1\u003e,\u003cdomain2\u003e\" allow_subdomains=true`\n\n### List roles\n\n`vault list keyfactor/roles`\n\n### Read role\n\n`vault read keyfactor/roles/\u003crolename\u003e`\n\n### Delete role\n\n`vault delete keyfactor/roles/\u003crolename\u003e`\n\n### Request certificate\n\n`vault write keyfactor/issue/\u003crolename\u003e common_name=\u003cCN\u003e dns_sans=\u003cDNS_SANS\u003e`\n\n### List certificates\n\n`vault list keyfactor/certs`\n\n### Read certificate\n\n`vault read keyfactor/certs/\u003cserial number\u003e`\n\n\u003e Note: Certificate serial numbers are provided in the output for enrollment and list commands\n\n### Revoke certificate\n\n`vault write keyfactor/revoke serial=\u003cserial\u003e`\n\n### Sign CSR\n\n`vault write keyfactor/sign/\u003crole name\u003e csr=\u003ccsr\u003e`\n\n### Read CA cert\n\n`vault read keyfactor/ca ca=\u003cca name\u003e`\n\n### Read CA chain\n\n`vault read keyfactor/ca_chain ca=\u003cca name\u003e`\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeyfactor%2Fhashicorp-vault-secretsengine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeyfactor%2Fhashicorp-vault-secretsengine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeyfactor%2Fhashicorp-vault-secretsengine/lists"}