From 75c397c41fd8612500d89dcbdb8532876bd28905 Mon Sep 17 00:00:00 2001 From: 3keyroman <46850604+3keyroman@users.noreply.github.com> Date: Sun, 31 Mar 2024 10:53:27 +0200 Subject: [PATCH] Initial documentation on Vault integration (#143) --- .../26-hashicorp-vault/01-overview.md | 28 ++++++++++ .../03-enable-pki-engine.md | 33 ++++++++++++ .../05-create-acl-policy.md | 54 +++++++++++++++++++ .../07-enable-auth-methods.md | 36 +++++++++++++ .../26-hashicorp-vault/_category_.json | 7 +++ 5 files changed, 158 insertions(+) create mode 100644 docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/01-overview.md create mode 100644 docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/03-enable-pki-engine.md create mode 100644 docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/05-create-acl-policy.md create mode 100644 docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/07-enable-auth-methods.md create mode 100644 docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/_category_.json diff --git a/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/01-overview.md b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/01-overview.md new file mode 100644 index 000000000..5b9be7e48 --- /dev/null +++ b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/01-overview.md @@ -0,0 +1,28 @@ +# Overview + +This document outlines the steps necessary to be taken to integrate the CZERTAINLY with the HashiCorp Vault PKI secrets engine to manage and automate certificate lifecycle. + +This integration guide was tested on: +- Vault version 1.14.0+ + +## HashiCorp Vault + +[HashiCorp Vault](https://www.vaultproject.io/) is a tool for securely accessing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, and more. Vault provides a unified interface to any secret, while providing tight access control and recording a detailed audit log. + +Vault provides a PKI secrets engine that generates X.509 certificates on demand. The PKI secrets engine generates dynamic X.509 certificates based on configured roles. The certificates are signed by the Vault's internal CA or an external CA. + +:::info[Vault installation] +This guide assumes that you have already installed and configured HashiCorp Vault. If you haven't done so, refer to the [HashiCorp Vault documentation](https://learn.hashicorp.com/tutorials/vault/getting-started-install) for installation and configuration instructions. + +For more information about the PKI secrets engine, refer to the [Vault PKI secrets engine documentation](https://www.vaultproject.io/docs/secrets/pki). +::: + +## Integration + +The following steps should be done to successfully integrate HashiCorp Vault with CZERTAINLY: + +| # | Reference | Short description | +|-------|--------------------------------------------------------|----------------------------------------------------------------| +| **1** | [Enable PKI Secrets Engine](./enable-pki-engine) | Enable and configure the PKI secrets engine | +| **2** | [Create ACL Policy](./create-acl-policy) | Create ACL policy with permissions for CZERTAINLY | +| **3** | [Enable Authentication Methods](./enable-auth-methods) | Enable authentication methods that can be used | diff --git a/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/03-enable-pki-engine.md b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/03-enable-pki-engine.md new file mode 100644 index 000000000..9b9b118e3 --- /dev/null +++ b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/03-enable-pki-engine.md @@ -0,0 +1,33 @@ +# Enable PKI Secrets Engine + +To enable and configure the PKI secrets engine, follow the official HashiCorp Vault documentation for [PKI secrets engine](https://www.vaultproject.io/docs/secrets/pki). + +Each PKI secrets engine is mounted at a specific path in the Vault. The path is used as the endpoint for all API requests. The PKI secrets engine can be mounted multiple times at different paths, each with its own configuration. + +Although the PKI secrets engine can have multiple issuers, their purpose is to rotate key and certificate. We are using the default issuer for the certificate management. + +## PKI secrets engine roles + +The PKI secrets engine generates dynamic X.509 certificates based on configured roles. Role maps a name in Vault to a procedure for generating a certificate. The role contains the parameters that are used to generate the certificate, such as the allowed domains and subdomains, the key type, maximum time-to-live, and more. + +For a complete list of the role parameters, refer to the [Vault PKI secrets engine documentation](https://www.vaultproject.io/docs/secrets/pki). + +### Request common name + +The common name is a required parameter for the certificate generation, and it is taken from the certificate signing request (CSR) by default. + +In some cases, the common name in the subject of the certificate can be empty. This is for example default behaviour of `certbot` when requesting the certificate for the domain. In such cases, the PKI secrets engine role must be configured to not require the common name (optional common name when requesting a certificate). + +For more information, see [`require_cn`](https://developer.hashicorp.com/vault/api-docs/secret/pki#require_cn) and [`use_csr_common_name`](https://developer.hashicorp.com/vault/api-docs/secret/pki#use_csr_common_name) parameters. + +### Request SANs + +By default, the SANs are taken from the CSR and therefore the PKI secrets engine role must be configured to use CSR SANs. The subject alternate names in the CSR will be used to generate the certificate. + +For more information, see [`use_csr_sans`](https://developer.hashicorp.com/vault/api-docs/secret/pki#use_csr_sans) parameter. + +### Storing certificates in the Vault + +The [`no_store`](https://developer.hashicorp.com/vault/api-docs/secret/pki#no_store) parameter can be used to disable storing the certificate in the Vault after they are generated. This can be useful when the certificate is generated for the external service and the Vault is used only for the certificate management. + +However, when the `no_store` is enabled, the certificate is not stored in the Vault and certificate issued by that role will not be discoverable by the CZERTAINLY platform. diff --git a/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/05-create-acl-policy.md b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/05-create-acl-policy.md new file mode 100644 index 000000000..8b0cc08a6 --- /dev/null +++ b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/05-create-acl-policy.md @@ -0,0 +1,54 @@ +# Create ACL Policy + +Vault policies are used to define a set of permissions for a path in the secrets engine. Policies are written in HashiCorp Configuration Language (HCL) and define a set of capabilities that are allowed on a given path. + +For more information about the Vault policies, refer to the [Vault policies documentation](https://www.vaultproject.io/docs/concepts/policies). + +## PKI secrets engine ACL policy + +This following policy assumes the PKI secrets engine is enabled at the `/pki` path in Vault. Since it is possible to enable secrets engines at any location, the policy should be adjusted accordingly: + +```hcl title="czertainly-policy.hcl" +# Allow to list pki issuers +path "pki/issuers" { + capabilities = ["list"] +} + +# Allow to list available pki roles +path "pki/roles" { + capabilities = ["list"] +} + +# Allow to read configuration of pki roles +path "pki/roles/*" { + capabilities = ["read"] +} + +# Allow to list certificates issued +path "pki/certs" { + capabilities = ["list"] +} + +# Allow signing of certificates for all roles +path "pki/sign/*" { + capabilities = ["create", "update"] +} + +# Allow to revoke certificate +path "pki/revoke" { + capabilities = ["update"] +} +``` + +This policy assumes access to all roles that are configured in the PKI secrets engine. If you want to restrict access to specific roles, adjust the policy accordingly. + +## Create `czertainly` policy + +Create a new policy named `czertainly` with the permissions defined in the [`czertainly-policy.hcl`](#pki-secrets-engine-acl-policy): + +```shell +$ vault policy write czertainly czertainly-policy.hcl +Success! Uploaded policy: admin +``` + +For more information on how to create and manage policies, refer to the [Vault policies](https://developer.hashicorp.com/vault/tutorials/policies/policies). diff --git a/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/07-enable-auth-methods.md b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/07-enable-auth-methods.md new file mode 100644 index 000000000..2e5cb7e01 --- /dev/null +++ b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/07-enable-auth-methods.md @@ -0,0 +1,36 @@ +# Enable Authentication Methods + +To authenticate with the HashiCorp Vault, you need to enable authentication methods that can be used. The authentication methods are used to authenticate users and applications to the Vault. + +The following authentication methods are available for the integration with the CZERTAINLY platform: + +| Method | Description | Default mount path: `auth/` | +|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| +| [AppRole](https://www.vaultproject.io/docs/auth/approle) | The AppRole authentication method allows machines or applications to authenticate with the Vault. The AppRole requires a role ID and a secret ID to authenticate and can be used for machine-to-machine authentication independently of the infrastructure where the Vault is running. | `approle` | +| [Kubernetes](https://www.vaultproject.io/docs/auth/kubernetes) | The Kubernetes authentication method allows Kubernetes pods to authenticate with the Vault. In this case the Vault is running in the Kubernetes cluster and has access to `TokenReview` API to validate Kubernetes tokens. | `kubernetes` | +| [JWT/OIDC](https://www.vaultproject.io/docs/auth/jwt) | The JWT/OIDC authentication method allows users to authenticate with the Vault using a JSON Web Token (JWT) token. This authentication method is used when Vault is not running in the Kubernetes cluster but can validate the tokens of the pod running in the Kubernetes cluster, whether using the Kubernetes service account public key or OIDC provider. | `jwt` | + + +## Enable AppRole authentication method + +The AppRole authentication method allows machines or applications to authenticate with the Vault. + +Using the AppRole authentication method requires a role ID and a secret ID to authenticate. The role ID is used to identify the role that the machine or application is allowed to authenticate with, and the secret ID is used to authenticate the machine or application. + +For more information about the AppRole authentication method, refer to the [Vault AppRole documentation](https://www.vaultproject.io/docs/auth/approle). + +## Enable Kubernetes authentication method + +The Kubernetes authentication method allows Kubernetes pods to authenticate with the Vault. The token that is automatically mounted in the Kubernetes pod is used to authenticate with the Vault. The default location of the token is `/var/run/secrets/kubernetes.io/serviceaccount/token`. + +For more information about the Kubernetes authentication method, refer to the [Vault Kubernetes documentation](https://www.vaultproject.io/docs/auth/kubernetes). + +## Enable JWT/OIDC authentication method + +The JWT/OIDC authentication method allows users to authenticate with the Vault using a JSON Web Token (JWT) that is automatically mounted in the Kubernetes pod at the `/var/run/secrets/kubernetes.io/serviceaccount/token` location. + +For more information about the JWT/OIDC authentication method, refer to the [Vault JWT/OIDC documentation](https://www.vaultproject.io/docs/auth/jwt). + +## Authentication mount path + +The authentication methods are mounted at a specific path in the Vault. When not specified during the configuration, the default mount path is used. diff --git a/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/_category_.json b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/_category_.json new file mode 100644 index 000000000..64202fa76 --- /dev/null +++ b/docs/10-certificate-key/20-integration-guides/26-hashicorp-vault/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "HashiCorp Vault", + "link": { + "type": "doc", + "id": "overview" + } +}